Have ideas to improve npm?Join in the discussion! »

    shellcraft

    1.3.6 • Public • Published

    shellcraft.js

    npm version dependencies Build Status gitter

    Simple CLI and shell for Node.js based on commander and inquirer.

    This module provides a way in order to use commander and inquirer together. There are a CLI and a shell mode, and the same commands can be used everywhere.

    shellcraft.js supports the command history and the auto-completion (in shell mode).

    Documentation

    Installation

    NPM Badge

    $ npm install shellcraft

    Hello, World

    var shellcraft = require('shellcraft');
     
    var options = {
      version: '0.1.0',
    };
     
    shellcraft.begin(options, function (err, results) {
      if (results) {
        console.log(results);
      }
    });

    API

    There are only two public API in order to play with shellcraft.


    shellcraft.begin (options, callback)

    ✤ options

    options = {
      version: '0.1.0',
      prompt: '>',
      promptFixed: false,
    };

    The version is used by Commander with the -V, --version parameter. The default prompt > can be changed by something else, like for example:

    myprompt>

    The promptFixed option is experimental and disabled by default. The purpose is to keep the prompt at the bottom even if async console.log outputs are used. In other words, (most) outputs are put before the prompt. Outputs via process.stdout.write (or stderr) are not handled by this option.

    ✤ callback (results)

    The callback is called when the shell or the CLI is terminated. Note that currently the results argument is not consistent between the CLI and the shell mode. This behavior will change in the future.

    Example
    shellcraft.begin(
      {
        version: '0.0.1',
        prompt: 'orc>',
      },
      function (err, results) {
        if (results) {
          console.log(results);
        }
      }
    );

    shell mode

    $ node myShell.js
    orc> _
    orc> help
     exit     exit the shell
     help     list of commands
     scope    change scope
    
    orc> exit
    $ _
    

    CLI mode

    $ node myShell.js -h
    
      Usage: myShell [options]
    
      Options:
    
        -h, --help         output usage information
        -V, --version      output the version number
        -s, --scoped       include scoped commands (CLI only)
    
    $ _
    

    shellcraft.registerExtension (shellExt, callback);

    There are two builtin commands help and exit. For more commands you must register one or more extensions. An extension must be "requirable" and must export two functions (register() and unregister()).

    ✤ shellExt

    The path on the .js file where the register and unregister methods are exported. An extension argument is passed with the register call. This object has four methods, command, option, remove and reload. It looks like the commander API in some ways.

    extension
      .command('foo', 'foo description', options, function (callback, args) {
        /*
         * callback (wizard, function (answers) {})
         *   Is called in order to return to the prompt (or exit if CLI). The wizard
         *   argument must be used only in order to process an Inquirer definition
         *   in the shell (or the CLI). Otherwise you must call the callback without
         *   arguments.
         *   The Inquirer answers are retrieved with the second argument.
         *
         * args
         *   Are the arguments provided with the command.
         */
      })
      .option('-f, --foo', 'foo description', options, function (callback, args) {
        /*
         * callback ()
         *
         * args
         *   This array can not have more than one item.
         */
      });
     
    /* Remove a specific command or option */
    extension.remove('foo');
     
    /* Reload for autocomplete (for example after removing a command) */
    extension.reload();

    The options can be (for command):

    options : {
      wizard : false,              /* when it needs Inquirer          */
      params : {
        scope: 'goblin',           /* override global scope filter    */
        required: 'argName',       /* a required argument             */
        optional: 'optionals...'   /* several optionals arguments     */
                                   /* do not append ... in order to   */
                                   /* limit to one optional argument  */
      }
    }

    It's possible to have an array of required or optional arguments, for example:

    options : {
      params : {
        required: ['arg1', 'arg2'],
        optional: ['opt1', 'opt2', 'opts...']
      }
    }

    The options can be (for option):

    options : {
      params : {
        required: 'argName',       /* a required argument             */
      }
    }

    ✤ callback ()

    The callback must be called when the extension is registered.

    Example

    myShellExtension.js

    'use strict';
     
    var zog = 'zog';
     
    var cmd = {};
    var opt = {};
     
    cmd.hello = function (callback, args) {
      console.log(zog + ' tells "Hello, ' + args.join(' ') + '"');
      callback();
    };
     
    cmd.wizard = function (callback) {
      var wizard = [
        {
          /* Inquirer definition... */
          type: 'input',
          name: 'zog',
          message: 'tell ' + zog,
        },
      ];
     
      callback(wizard, function (answers) {
        /* stuff on answers */
        if (answers.zog === zog) {
          console.log(zog + ' ' + zog);
        } else {
          console.log('lokthar?');
        }
     
        /*
         * You can return false if you must provide several wizard with only
         * one call to this command handler.
         * You can call callback () without argument in order to return to the
         * prompt instead of returning true.
         */
        return true;
      });
    };
     
    opt.foobar = function (callback, args) {
      if (args) {
        zog = args[0];
      } else {
        zog = 'lokthar';
      }
      callback();
    };
     
    exports.register = function (extension, callback) {
      extension
        .command(
          'hello',
          'print Hello, John',
          {
            wizard: false,
            params: {
              required: 'name',
              optional: 'etc...',
            },
          },
          cmd.hello
        )
        .command(
          'wizard',
          'begins a wizard',
          {
            wizard: true,
            scope: 'warcraft',
          },
          cmd.wizard
        )
        .option(
          '-f, --foobar',
          'zog is foobar',
          {
            params: {
              required: 'who',
            },
          },
          opt.foobar
        );
     
      callback();
    };
     
    exports.unregister = function (callback) {
      /* internal stuff */
      callback();
    };

    myShell.js

    'use strict';
     
    var path = require('path');
    var shellcraft = require('../');
     
    var options = {
      version: '0.0.1',
      prompt: 'orc>',
    };
    var shellExt = path.join(__dirname, 'myShellExtension.js');
     
    shellcraft.registerExtension(shellExt, function () {
      shellcraft.begin(options, function (err, results) {
        if (results) {
          console.log(results);
        }
      });
    });

    shell mode

    $ node myShell.js
    orc> _
    orc> help
     exit                    exit the shell
     help                    list of commands
     scope                   change scope (warcraft)
     hello <name> [etc...]   print Hello, John
    
    orc> hello Tux
    zog tells "Hello, Tux"
    orc> exit
    $ _
    

    CLI mode

    $ node myShell.js -h
    
      Usage: myShell [options] [command]
    
    
      Commands:
    
        *
        hello <name> [etc...]  print Hello, John
    
      Options:
    
        -h, --help          output usage information
        -V, --version       output the version number
        -s, --scoped        include scoped commands (CLI only)
        -f, --foobar <who>  zog is foobar
    
    $ _
    $ node myShell.js hello Alice
    zog tells "Hello, Alice"
    $ node myShell.js -f Bob hello Alice
    Bob tells "Hello, Alice"
    $ _
    

    Note that the commands which are in a different scope (like wizard in this example), are not shown in the global help output.

    In order to see all commands, you must pass the -s, --scope argument:

    $ node examples/myShell -sh
    
      Usage: myShell [options] [command]
    
    
      Commands:
    
        *
        hello <name> [etc...]  print Hello, John
        warcraft@wizard        begins a wizard
    
      Options:
    
        -h, --help          output usage information
        -V, --version       output the version number
        -s, --scoped        include scoped commands (CLI only)
        -f, --foobar <who>  zog is foobar
    
    $ _
    

    License

    The MIT License (MIT)
    
    Copyright (c) 2014-2017 Xcraft <mathieu@schroetersa.ch>
    Copyright (c) 2015      Xcraft <sam@loup.io>
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.
    

    Install

    npm i shellcraft

    DownloadsWeekly Downloads

    9

    Version

    1.3.6

    License

    MIT

    Unpacked Size

    52.8 kB

    Total Files

    19

    Last publish

    Collaborators

    • avatar
    • avatar