Nanoseconds Produce Minutes

    jargs
    TypeScript icon, indicating that this package has built-in type declarations

    0.4.7 • Public • Published

    jargs

    Simple node arg parser with explicit tree structure schema

    CircleCI

    About

    Jargs is a node argv parser that takes inspiration from docopt. Unlike other arg parsers, jargs allows you to define your commands, arguments, etc in a tree structure. This way you can have, for example, nested sub-commands, or arguments that are attached to a specific command.

    Installation

    npm install jargs --save

    Usage

    Require jargs

    import {
      collect,
      Program,
      Command,
      KWArg,
      Flag,
      Arg,
      Required,
      RequireAll,
      RequireAny
    } from 'jargs';

    Create a schema

    Here's a cutdown example of how to create a schema for NPM.

    Note: you can nest nodes as many times as necessary.

    const tree = collect(
      Help(
        'help',
        null,
        Program(
          'npm',
          null,
          RequireAny(
            Command(
              'init'
            ),
            Command(
              'install', {alias: 'i'},
              Arg(
                'lib'
              ),
              Flag(
                'save', {alias: 'S'}
              ),
              Flag(
                'save-dev', {alias: 'D'}
              ),
              Flag(
                'save-exact', {alias: 'E'}
              ),
              Flag(
                'save-optional', {alias: 'O'}
              )
            ),
            Command(
              'run', {alias: 'run-scripts'},
              Arg(
                'command'
              )
            )
          )
        )
      ),
      process.argv
    );

    This collects the arguments that match the schema you've defined.

    Calling the command npm returns the following.

    {
      name: 'npm',
      kwargs: {},
      flags: {},
      args: {}
    }

    Calling the command npm install jargs --save returns the following.

    {
      name: 'npm',
      command: {
        name: 'install',
        kwargs: {},
        flags: {
          save: true
        },
        args: {
          lib: 'jargs'
        }
      },
      kwargs: {},
      flags: {},
      args: {}
    }

    If we set the lib Arg to multi: true, then we can supply multiple args and they will be added to an array.

    Arg(
      'lib',
      {
        multi: true
      }
    )

    Calling the command npm install jargs another-lib --save with mutli returns the following.

    {
      name: 'npm',
      command: {
        name: 'install',
        kwargs: {},
        flags: {
          save: true
        },
        args: {
          lib: ['jargs', 'another-lib']
        }
      },
      kwargs: {},
      flags: {},
      args: {}
    }

    Collecting arguments

    The collect function is provided with your program and argv (from process). Collect returns a tree that represents the matched arguments, and handles calling the callbacks of any commands that were matched with the relevant part of the tree.

    collect(Program('my-command'), process.argv);

    Querying the tree

    Each node always contains the keys command, kwargs, flags, args and rest so that you can easily query them.

    Querying Commands

    if (tree.command) {
      switch (tree.command.name) {
        case 'install':
          // Install stuff
          break;
        default:
          // This should never be hit since we check for the command existence first
      }
    }

    Rest

    Rest is a key that is populated with all remaining arguments when the user provides -- in their command. This is often used to pass all remaining arguments to a sub-process.

    Running npm test -- --coverage would return something like

    {
      name: 'npm',
      command: {
        {
          name: 'test',
          kwargs: {},
          flags: {},
          args: {},
          rest: ['--coverage']
        }
      },
      kwargs: {},
      flags: {},
      args: {}
    }

    Querying Flags, KWArgs, and Args

    Flags
    if (tree.flags.verbose) {
      doSomethingWithThisFlag(tree.flags.verbose);
    }
    KWArgs
    if ('lib' in tree.kwargs) {
      doSomethingWithThisKWArg(tree.kwargs.lib);
    }
    Args
    if ('lib' in tree.args) {
      doSomethingWithThisArg(tree.args.lib);
    }

    Nodes

    All nodes (excluding require nodes, see blow for more info) take the following arguments, though Command and Program take additional arguments (more info about individual nodes below).

    Node(name, options);

    Note: the available options vary per node.

    Command and Program can take an infinite number or arguments. Any arguments after name & options become that node's child nodes e.g.

    Command(name, options, KWArg(), Flag(), Arg());

    Both options and childNodes are optional. All keys in options are optional and have defaults (more info below). childNodes are any arguments following the name & options (only valid for Command and Program).

    You can nest Commands as many times as necessary.

    Program

    Program is the main command / name of your program. This should always be the root node in your schema.

    Takes the following options.

    Program(
      'program-name'
      {
        description: 'A command', // default: empty string
        usage: 'program-name sub-command --flag', // default: empty string
        examples: ['program command-name --flag'], // default: empty array
        callback: function (tree) {}
      },
      ...childNodes
    )

    Command

    A sub-command of your command line interface. Program is the main command / name of your program. Commands form a fork in the tree - only one command at each level can be satisfied.

    Takes the following options.

    Command(
      'command-name'
      {
        alias: 'command-alias', // default: undefined
        description: 'A command', // default: empty string
        usage: 'program-name sub-command --flag', // default: empty string
        examples: ['program command-name --flag'], // default: empty array
        callback: function (tree) {}
      },
      ...childNodes
    )

    KWArg

    A key word argument such as --outfile that takes a custom value. These can be defined in 2 different ways: --outfile filename.js and --outfile=filename.js. You don't need to add the -- to the name, these are dealt with internally. If an alias is defined e.g. {alias: 'o'} this KWArg will also get the value of -o=filename.js (note the single -).

    Takes the following options.

    KWArg(
      'kwarg-name'
      {
        alias: 'k', // default: undefined
        description: 'A key word argument', // default: empty string
        type: 'string',
        multi: false // default: false
      }
    )

    Flag

    Like a KWArg, but do not take a custom value. These are used like booleans. --verbose is an example of a flag. You don't need to add the -- to the name, these are dealt with internally. If an alias is defined e.g. {alias: 'v'} this Flag will also be true if -v is present (note the single -).

    Takes the following options.

    Flag(
      'flag-name'
      {
        alias: 'f', // default: undefined
        description: 'A flag', // default: empty string
      }
    )

    Arg

    Positional argument that takes a custom value. In the command npm install jargs, jargs is an Arg.

    Takes the following options.

    Arg(
      'arg-name'
      {
        description: 'An arg', // default: empty string
        type: 'string',
        multi: false // default: false
      }
    )

    Help

    By wrapping your Program node in the Help node users can get nicely formatted help & usage output about any part of your schema by passing the --help flag (you can change the help node name & alias).

    Note: if you provide another flag / kwarg node with the same name or alias as the help node, no help will be output. This allows you to override the help output, and output some custom usage info.

    Help(
      'help',
      {
        alias: 'h', // default: undefined
        description: 'Display help & usage' // default: empty string
      }
    )

    Require Nodes

    There are 3 different types of require nodes that you can wrap your argument / command nodes in to ensure that they are supplied.

    Note: you cannot require more than one Command at the same level unless you use RequireAny, as Commands form a fork in the tree and only one at each level can be satisfied.

    Required

    Takes a single node as an argument and ensures it is supplied.

    Required(
      Arg('arg-name')
    )

    RequireAll

    Takes any number of nodes as arguments and ensures they are all supplied.

    RequireAll(
      KWArg('kwarg-name'),
      Arg('arg-name')
    )

    RequireAny

    Takes any number of nodes as arguments, and ensures that one of them is supplied.

    RequireAny(
      Command('command1'),
      Command('command2')
    )

    Callbacks

    The Program and Command nodes can take a callback. If satisfied, these callbacks will be called with the tree at that level, the parentTree, and anything returned from the previous callback.

    program --kwarg=value command
    Program(
      'program',
      {
        callback: function (tree) {
          /*
     
          tree = {
            name: 'program',
            command: {name: 'command', ...etc},
            args: {},
            flags: {},
            kwargs: {
              kwarg: 'value'
            }
          };
     
          */
     
          return 'Hello, World!';
        }
      },
      KWArg(
        'kwarg'
      ),
      Command(
        'command',
        {
          callback: function (tree, parentTree, data) {
            /*
     
          tree = {
            name: 'command',
            args: {},
            flags: {},
            kwargs: {}
          };
     
          parentTree = {
            name: 'program',
            command: {name: 'command', ...etc},
            args: {},
            flags: {},
            kwargs: {
              kwarg: 'value'
            }
          };
     
          data = 'Hello, World!';
     
          */
          }
        }
      )
    )

    Command examples

    npm install jargs --save

    In the above command install is a Command, jargs is an Arg, and --save is a Flag.

    browserify --transform babelify --outfile=build/indexjs src/index.js

    In the above command --transform is a KWArg and its value is babelify, --outfile is also a KWArg (note the alternative kwarg syntax) with the value build/index.js, and src/index.js is an Arg

    Complex schema examples

    This example shows how to create the following commands (taken from docopt).

    Commands

    naval_fate ship new <name>...
    naval_fate ship <name> move <x> <y> [--speed=<kn>]
    naval_fate ship shoot <x> <y>

    Schema

    const tree = collect(
      Program(
        'naval_fate',
        null,
        Command(
          'ship', null,
          RequireAny(
            Arg(
              'shipName'
            ),
            Command(
              'new', null,
              Required(
                Arg(
                  'shipName'
                )
              )
            ),
            Command(
              'shoot', null,
              RequireAll(
                Arg(
                  'shootX'
                ),
                Arg(
                  'shootY'
                )
              )
            )
          ),
          Command(
            'move', null,
            RequireAll(
              Arg(
                'moveX'
              ),
              Arg(
                'moveY'
              )
            ),
            KWArg(
              'speed'
            )
          )
        )
      ),
      process.argv
    );

    Install

    npm i jargs

    DownloadsWeekly Downloads

    0

    Version

    0.4.7

    License

    MIT

    Unpacked Size

    125 kB

    Total Files

    37

    Last publish

    Collaborators

    • jakesidsmith