Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    cliparsepublic

    Declarative CLI parsing for node apps

    Build StatusGitter chat Coverage Status

    This is a library designed to express command-line options. It supports commands and subcommands (at an arbitrary depth), automatically generates help text and usage contents. You can use custom parsers for attributes and options values (types supported out of the box: int, bool, string).

    Its design is vaguely inspired from optparse-applicative which is a great CLI parsing library. JS being not as expressive as Haskell, a direct port is not possible.

    Enough talk, show me the code

    npm install cliparse
    #!/usr/bin/env node
     
    var cliparse = require("cliparse");
    var parsers = cliparse.parsers;
     
    function echoModule(params) {
        
    }
     
    function addModule(params) {
        
    }
     
    var cliParser = cliparse.cli({
      name: "my-executable",
      description: "Simple CLI written for the sake of the example",
      commands: [
     
        cliparse.command(
          "echo",
          { description: "Display the given value",
            args: [ cliparse.argument("value", { description: "Simple value" })],
            options: [ cliparse.flag("reverse", { aliases: ["r"], description: "Reverse the value"}) ]
          },
          echoModule),
     
        cliparse.command(
          "add2",
          { description: "Add 2 to the given integer and display the result",
            args: [
              cliparse.argument("int",
                { default: 0,
                  parser: parsers.intParser,
                  description: "Int to add 2 to" })
            ]
          },
          addModule)
      ]
    });
     
    cliparse.parse(cliParser);

    Where echoModule and addModule are callbacks taking a { args: ['value'], options: {key: 'value'} } parameter.

    Generated output

    Top-level help

    $ my-executable --help
    Usage: my-executable
    Simple CLI written for the sake of the example.
    
    
    Options:
    [--help, -?]                    Display help about this program
    
    Available commands:
    help                            Display help about this program
    echo VALUE                      Display the given value
    add2 [INT]                      Add 2 to the given integer and display the result
    

    Command-level help

    $ my-executable echo --help
    Usage : my-executable echo VALUE
    display the given value
    
    Arguments:
    VALUE                           Simple value
    
    Options:
    [--help, -?]                    Display help about this program
    [--reverse, -r]                 Reverse the value
    

    Subcommands

    The command constructor takes an optional commands attribute which allows you to nest subcommands at an arbitrary level.

    var testCli = cliparse.cli({
      name: "testCli",
      description: "Simple CLI written for the sake of the example",
      commands: [
        cliparse.command(
          "number",
          { description: "perform simple arithmetic calculations",
            commands: [
              cliparse.command(
                "add",
                { description: "add two integers",
                  args: [ intArgument, intArgument]
                }, numberModule.add),
              cliparse.command(
                "multiply",
                { description: "multiply two integers",
                  args: [ intArgument, intArgument]
                }, numberModule.multiply)
            ]
          }),
      ]
    });

    Help command

    An help command is automatically generated, with the following syntax:

    $ my-executable help <command> <subcommand> <...>

    It can be disabled by setting helpCommand to false in cliparse.cli options.

    Autocompletion

    CLI parse allows you to generate autocompletion scripts for bash and zsh (work in progress). Generate the script in your npm post-install hook and add it to your users shell completion scripts to enable it.

    It supports completion on commands, options and arguments, as well as on the help command. Completion on options and arguments are configurable: you can declare your own completion methods.

    All the completion logic is handled within your app, so it will work with dynamically defined commands.

    Bash

    Generate the completion script and put it in bash completion dir:

    $ my-executable --bash-autocomplete-script /complete/path/to/my-executable > ~/.bash_completion.d/my-executable

    Normally .bash_completion.d is automatically sourced. You can put the file where you want and source it manually.

    ZSH

    Generate the completion script and put it in zsh completion dir:

    $ my-executable --zsh-autocomplete-script /complete/path/to/my-executable > ~/.zsh.d/completion/_my-executable

    The file name must be _my-executable (if your executable is named my-executable). You can put the file where you want as long as it's in a directory listed in $fpath.

    Custom completion

    You can have custom completion for option or arguments, by passing a custom complete function (see API).

    For instance to complete on a list of colors:

    var colorCompleter = function() {
      return autocomplete.words(['mauve', 'blue', 'yellow', 'purple', 'parabolic']);
    };

    To complete on a list of files:

    var fileCompleter = function() {
      return autocomplete.files;
    };

    The complete function can also return a promise for async results.

    API

    cli

    cli(opts, cb);

    Where opts can contain

    • name: the name of the executable (if not provided, process.argv is used)
    • description: a one-line description of the executable
    • version: the version number of the executable (displayed by --version. Default value: null
    • options: array of top-level options (constructed with option or flag). Default value: [].
    • commands: array of commands (constructed with command). Default value: []
    • args: array of arguments (constructed with argument). If your app doesn't have commands.
    • helpCommand: Generate a help command. Default value: true.

    If your application is not solely made of commands, you can pass an action callback. If you don't give a callback, calling your application without any argument will display a usage message describing the available commands.

    option

    option(name, opts);

    Where name is the name of the flag, and opts can contain

    • aliases: array of other names (the shorthand name for instance. Default value: []
    • metavar: the name of the value of the option (if applicable: for flags, see below)
    • parser: the parser used to parse the value. Default value: stringParser which is a noop parser returning the string.
    • description: a single-line description of what the option is about. Default value: the empty string.
    • required: make option mandatory
    • default: value used if the option is not given any value. If set, overrides the required setting.
    • complete: a function returning completion results for the option (or a promise of results). Default value: a function returning an empty result.
    • expects_value: does the option expect a value? Default: true. Rather than setting it yourself, use flag.

    flag

    Shorthand for flags (ie options with boolean values, defaulting to false, doesn't expect a value)

    flag(name, opts);

    Acts like option, with different defaults:

    • parser defaults to booleanParser, which parses boolean values
    • default defaults to false

    argument

    argument(name, opts);

    Where opts can contain

    • parser: ther parser used to parse the value of the argument. Default value: stringParser
    • description: a single-line description of what the argument is about.
    • default: value used if the argument is not given any value
    • complete: a function returning completion results for the argument. Default value: a function returning an empty result.

    command

    command(name, opts, cb);

    Where name is the name of the command , and opts can contain

    • description: a single line description of the command
    • args: array of arguments (constructed with argument). Default value: []
    • options: array of options (constructed with option). Default value: []
    • commands: array of subcommands (constructed with command). Default value: []

    cb is a callback which is called when the command match (if no subcommand match). It is called with a { args: ['value'], options: {key: 'value'}} object. opts contains both the options of the command and the options of the parent commands.

    Parsers

    Basic scalar types (int, bool, and string) are already supported. It is possible to declare your own parsers to validate more specific types of values (eg. enums).

    A parser is a function String -> Result where Result is either

    • { success: <parsed value> }
    • or { error: <error message> }

    Parser results can be constructed with parsers.success(<value>) and parsers.error(<reason>).

    For instance, to parse an hexadecimal RBG color:

    var colorParser = function(input) {
      var pattern = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i;
      var matches = input.match(pattern);
      if(matches !== null) {
        var components = matches.slice(1,4)
              .map(function(x) { return parseInt(x, 16); });
        return parsers.success(components);
      } else {
        return parsers.error("invalid color code");
      }
    }

    Autocompletion helpers

    Autocompletion results

    autocomplete.empty: no results

    autocomplete.words([…]): list of words

    autocomplete.glob(<glob>): files matching glob (eg. *.log).

    autocomplete.files: files

    autocomplete.directories: directories

    You can combine autocompletion results:

    autocomplete.mappend(<result1, result2>): combine results from result1 and result2. As globs can't be combined, the last one wins (if set).

    autocomplete.mconcat([ <results> ]): reduce a list of result to a composite result with mappend. If the list is empty, then empty is returned.

    Contributing

    Make sure you don't break anything.

    npm test

    ToDo

    For 0.3.0

    Later

    Keywords

    none

    install

    npm i cliparse

    Downloadsweekly downloads

    28

    version

    0.3.0

    license

    MIT

    repository

    github.com

    last publish

    collaborators

    • avatar