Classes

A single positional argument. These are intended to be nested within Command objects, but can also be used standalone.

By default, an Argument represents a single, required argument with no validation or preprocessing applied. All of these defaults can be modified.

Preprocessors can validate and modify the argument.
An Argument can be optional, preventing CommandErrors from being thrown for missing values.
Variable arguments (varargs) can be enabled to take in multiple values.

Command

A text-based command with positional arguments.

A Command can be given a set of Arguments (or multiple sets of Arguments), parse strings into an object of values (see Args), and pass those values to a function that runs on command execution.

CommandError ⇐ Error

Error thrown during execution of Argument, Command, and CommandRegistry objects.

Anything thrown in user-provided code (command handlers and argument preprocessors) is wrapped with a CommandError. The CommandError instance also contains additional context, such as extended error messages and a reference to the Command that threw (if any). This allows callers to do command-specific error handling, if necessary.

SetupError ⇐ Error

Error thrown when setting up Argument, Command, and CommandRegistry objects. These are typically thrown for invalid values, such as passing non-Function values for handler functions.

CommandRegistry

A registry containing commands. Can take in command strings and delegate them to the appropriate commands.

Typedefs

Args

An Object of parsed arguments for a command. Matches the format from other argument parsing libraries, such as Yargs.

Handler ⇒ any | Promise.<?any>

A function a Command calls when it is executed.

DefaultHandler ⇒ any | Promise.<?any>

A function a CommandRegistry can optionally call when it gets an unrecognized command.

NOTE the arguments passed to a DefaultHandler function are slightly different than a normal Handler. It gets the string array of command parts instead of a parsed Object of arguments.

ErrorHandler ⇒ any | Promise.<?any>

A function a Command can optionally use to handle values thrown during execution.

NOTE the arguments passed to an ErrorHandler function are slightly different than a normal Handler. It gets the value thrown during execution.

HelpHandler ⇒ any | Promise.<?any>

A function a CommandRegistry can optionally use for its help command.

NOTE the arguments passed to a HelpHandler function are slightly different than a normal Handler. It gets the command map of a CommandRegistry as the second parameter.

Preprocessor ⇒ any

A function a Argument can optionally use to validate and apply preprocessing to an argument.

Argument

A single positional argument. These are intended to be nested within Command objects, but can also be used standalone.

By default, an Argument represents a single, required argument with no validation or preprocessing applied. All of these defaults can be modified.

Preprocessors can validate and modify the argument.
An Argument can be optional, preventing CommandErrors from being thrown for missing values.
Variable arguments (varargs) can be enabled to take in multiple values.

Kind: global class

Argument
- new Argument(name)
- accessor
- builder
  - .asynchronous(enabled) ⇒ Argument
  - .optional(enabled) ⇒ Argument
  - .preprocess(func) ⇒ Argument
  - .varargs(enabled) ⇒ Argument
- execution
  - .parse(args) ⇒ any | Array.<any> | Promise.<any> | Promise.<Array.<any>>
  - .usage() ⇒ String

new Argument(name)

Creates a new Argument with the given name. This name is used in the usage text (see usage).

Throws:

SetupError for non-String or empty String names.

Param	Type	Description
name	`String`	The name for this `Argument`.

Example

function coerceToNumber(val) {
    if (!Number.isInteger(val)) throw new Error('not a number!');
    return Number.parseInt(val);
}
const arg = new Argument('thing')
    .optional(true)
    .varargs(true)
    .preprocessor(coerceToNumber);

const vals1 = arg.parse('123');           // vals1 = [123]
const vals2 = arg.parse(['1', '9', '5']); // vals2 = [1, 9, 5]
const vals3 = arg.parse();                // vals3 = []
const vals4 = arg.parse(['1', 'hello']);  // CommandError thrown, not a number!
const use = arg.usage(); // use = "[thing_1] [thing_2] ... [thing_n]"

argument.is_async

Directly get and set async mode for this Argument. Setting this has the same effect as calling asynchronous.

Kind: instance property of Argument
Default: false
Category: accessor
See: asynchronous

argument.is_optional

Directly get and set whether or not this Argument is optional. Setting this has the same effect as calling optional.

Kind: instance property of Argument
Default: false
Category: accessor
See: optional

argument.is_varargs

Directly get and set whether or not this Argument is a varargs argument. Setting this has the same effect as calling varargs.

Kind: instance property of Argument
Default: false
Category: accessor
See: varargs

argument.name

Directly get and set the name for this Argument. Setting this has the same effect as calling new Argument().

Kind: instance property of Argument
Category: accessor
See: new Argument()

argument.preprocessor

Directly get and set the Preprocessor function for this Argument. Setting this has the same effect as calling preprocess.

Kind: instance property of Argument
Default: null
Category: accessor
See: preprocess

argument.asynchronous(enabled) ⇒ `Argument`

Enables or disables async mode. In async mode, parse returns a Promise that fulfills based on parse execution, instead of returning or throwing. This setting only applies to this Argument.

An async Argument will have its async setting disabled if it is added to a non-async Command. This is intentional to discourage mixing sync and async elements.

Kind: instance method of Argument
Returns: Argument - instance so we can chain calls.
Category: builder
Throws:

SetupError for non-Boolean values.

Param	Type	Description
enabled	`Boolean`	`true` to enable async, `false` to disable.

argument.optional(enabled) ⇒ `Argument`

Sets this Argument as optional. When an Argument is optional, parse will not throw an error when a value is not provided. NOTE Only the last argument in an argument list may be optional.

Kind: instance method of Argument
Returns: Argument - instance so we can chain calls.
Category: builder
Throws:

SetupError for non-Boolean values.

Param	Type	Description
enabled	`Boolean`	`true` for optional, `false` for required.

argument.preprocess(func) ⇒ `Argument`

Sets up a preprocessor function that will be applied to any value that passes through parse for this Argument. When called in the context of a Command, the return value of this preprocessor will be added to the parsed Args Object. If the preprocessor does not return anything (return value is undefined), the value will be added to Args as-is. Values thrown from this preprocessor will bubble up with additional context.

Kind: instance method of Argument
Returns: Argument - instance so we can chain calls.
Category: builder
Throws:

SetupError for non-Function values.

Param	Type	Description
func	`Preprocessor`	The preprocessor function.

argument.varargs(enabled) ⇒ `Argument`

Enables or disables variable arguments (varargs) for this Argument. A varargs Argument can accept multiple values, and each individual value will be separately subject to the preprocessor (if one is given). The first value of a varargs Argument is required (unless optional is enabled), but all subsequent values are always optional. NOTE A varargs Argument must be the last argument in a set for a Command.

Kind: instance method of Argument
Returns: Argument - instance so we can chain calls.
Category: builder
Throws:

SetupError for non-Boolean values.

Param	Type	Description
enabled	`Boolean`	`true` for enabled, `false` for disabled.

argument.parse(args) ⇒ `any` | `Array.<any>` | `Promise.<any>` | `Promise.<Array.<any>>`

Parses the given argument(s) using the preprocessor function (if set). If no preprocessor function has been set, this function will still perform basic validation on the argument(s), but will return it(them) as-is.

In async mode, this function returns a Promise that fulfills with the processed arguments. Any intermediate Promise is internally resolved, so the final returned Promise will resolve to a processed value. This is particularly useful for varargs.

In varargs mode, the returned (or resolved) value will always be an Array, even if the given argument was a single, non-Array value.

Kind: instance method of Argument
Returns: any | Array.<any> - The processed value (or array of values, in varargs mode).Promise.<any> | Promise.<Array.<any>> - in async mode.
Category: execution
Throws:

CommandError for non-String and non-Array-of-String data.
CommandError for incorrect number of arguments.
CommandError wrapping anything thrown from the preprocessor. Additional context is added where possible, indicating which argument caused the problem and why.

Param	Type	Description
args	`String` \| `?Array.<String>`	Argument strings to parse.

argument.usage() ⇒ `String`

Generates a human-readable string describing this Argument. Useful for building command usage strings from multiple arguments.

Required <example>
Optional [example]
Varargs <example_1> [example_2] ... [example_n]

Kind: instance method of Argument
Returns: String - A human-readable description of this Argument.
Category: execution

Command

A text-based command with positional arguments.

A Command can be given a set of Arguments (or multiple sets of Arguments), parse strings into an object of values (see Args), and pass those values to a function that runs on command execution.

Kind: global class

Command
- new Command()
- instance
  - accessor
    - .argsets
    - .desc
    - .is_async
    - .name
  - builder
    - .addArgSet(argset) ⇒ Command
    - .asynchronous(enabled) ⇒ Command
    - .description(desc) ⇒ Command
    - .error(func) ⇒ Command
    - .handler(func) ⇒ Command
  - execution
    - .execute(parts) ⇒ any | Promise.<?any>
    - .parse(parts) ⇒ Args | Promise.<Args>
    - .usage() ⇒ String
- static
  - .split(string) ⇒ Array.<String>

new Command()

Creates a new Command with the given name.

Throws:

SetupError Missing, empty, or non-String names.

Example

function coerceToNumber(val) {
    if (!Number.isInteger(val)) throw new Error('not a number!');
    return Number.parseInt(val);
}
const command = new Command('example')
    .description('My cool command that adds numbers')
    .addArgSet([
        new Argument('arg1').preprocess(coerceToNumber),
        new Argument('arg2').preprocess(coerceToNumber),
    ])
    .handler((args, arbitrary) => {
        const value = args.arg1 + args.arg2;
        console.log('Value is', value);
        console.log('Also got this from caller:', arbitrary);
        return value;
    });

const use  = command.usage();               // "example <arg1> <arg2>"
const val1 = command.execute('12 34');      // val1 = 46
const val2 = command.execute(['55', '45']); // val2 = 100
const val3 = command.execute('12');       // throws CommandError, missing second argument!
const val4 = command.execute('12 hello'); // throws CommandError, second argument not a number!

command.argsets

Directly access the argument sets for this Command. This is a read-only property.

Kind: instance property of Command
Category: accessor

command.desc

Directly get and set the description for this Command. Setting this has the same effect as calling description.

Kind: instance property of Command
Category: accessor
See: description

command.is_async

Directly get and set asynchronous mode for this Command. Setting this has the same effect as calling asynchronous.

Kind: instance property of Command
Default: false
Category: accessor
See: asynchronous

command.name

Directly get and set the name for this Command. Subject to the same validation as new Command().

Kind: instance property of Command
Category: accessor
See: new Command()

command.addArgSet(argset) ⇒ `Command`

Adds a set of Arguments this Command can accept. Arguments are all positional, so this function enforces several rules to avoid ambiguous command definitions:

A Command cannot have multiple argument sets with the same length.
A Command cannot have multiple argument sets with varargs arguments.
Optional arguments must be the last arguments in an argument set.
A varargs argument must be the last argument in an argument set.
The argument set containing a varargs argument must be the largest set.