- Notifications
You must be signed in to change notification settings - Fork739
Using ShellJS Plugins
Using an existing plugin (list)
Using ShellJS plugins is very easy! To useshelljs-plugin-foo, follow these steps:
$ npm install --save shelljs$ npm install --save shelljs-plugin-foo
// index.js// Require all ShellJS plugins firstrequire('shelljs-plugin-foo');// Require ShellJS itselfvarshell=require('shelljs');// 'shelljs/global' is allowed instead// Require any other packages you likevarret=shell.foo();// this function works!shell.echo(ret.stdout);// most plugins return a ShellString, just like ShellJS commands!shell.foo().grep('o').sed(/o/g,'a');// most plugins will be fully pipe-able
Disclaimer: this API is not yet stable, and it's likely to change a bit
We recommend the following format:shelljs-plugin-<your command name>. If you're writing agit plugin, you'd name itshelljs-plugin-git.
The most important thing is to require the most recent version of ShellJS as apeer-dependency. If you want to add unit tests for your plugin as well, you'll probably want it as adev-dependency too:
{"name":"shelljs-plugin-foo","version":"0.1.0","description":"A foo plugin for ShellJS","main":"index.js","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"keywords":["shelljs","plugin","foo"],"author":"Joe Smith","license":"MIT","devDependencies":{"shelljs":"^0.7.3"},"peerDependencies":{"shelljs":"^0.7.3"}}
Create a file namedindex.js and start hacking away! You'll need to implement your command as a JavaScript function, and then register that command with ShellJS. Here's an example:
// This exposes the plugin utilitiesvarplugin=require('shelljs/plugin');// Require whatever modules you need for your project here// Implement your command in a function, which accepts `options` as the// first parameter, and other arguments after thatfunctionfooImplementation(options,fileName){return'Hello world';}// Register the new plugin as a ShellJS commandplugin.register('foo',fooImplementation,{cmdOptions:{},// There are no supported options for this command});// Optionally, you can export the implementation of the command like so:exports.foo=fooImplementation;
plugin.register() can take a few different options. In the example above, we use thecmdOptions attribute. For the list of available options, check outthe source code (note: this is subject to change until the API is officially released).
Look atthis file to see some options in action.
TODO: once the API stabilizes, we'll add an actual table of options, defaults, and their meanings.
| Option | Type | Default | Meaning |
|---|---|---|---|
allowGlobbing | Boolean | true | Should arguments be automatically glob-expanded? |
canReceivePipe | Boolean | false | Can this command handle piped input? |
cmdOptions | Object/null | null | An object specifying the command's allowed options. Ifnull, no option parsing will happen (the options string will be passed bare to your command). If{}, then no options will be allowed (and the first parameter your command receives will always be{}). Otherwise, the options-string will be parsed such thatcmdOptions: { '-f': 'foo' } will result in your function receiving{ foo: true } or{ foo: false }, depending on if-f was specified. |
globStart | Number (int) | 1 | The first argument to glob-expand (all arguments following this will also be glob-expanded) |
pipeOnly | Boolean | false | Should this commandonly be allowed on the right-hand-side of pipes (e.g.tr)? |
wrapOutput | Boolean | true | Should output be wrapped as aShellString() object? |
You should now have a functioning shelljs-plugin! Feel free to use the following README badge:
[](https://github.com/shelljs/shelljs/wiki/Using-ShellJS-Plugins)Also, feel free to add your plugin to thelist of available plugins.