climan

v1.0.0

Published

3 years ago

argument parsing once more

Downloads

0High
0Medium
0Low

md5crypt

cli command-line parser

CliMan - argument parsing once more

I've been very irritated with CLI argument parsers as a whole. The usually are based on some existing api that poorly interfaces with javascript and have poor typescript support.

After yet another CLI app that I had to quickly write for a customer I noticed that I used most of my time fighting with the argument parsing library (it was commander). I got furious seeing the wasted time, set down with a pen and sketched out my own argument parser.

Is it any better? It's up to you to decide. I know that I will use from now on.

Key features:

no dependencies
compact and lightweight
written in typescript for typescript (but can be used without problems with regular javascript)
entire CLI structure defined in a single JSON
everything documented with no hidden features that you have to search the source code to find

Features in general

git style commands with options hierarchy
default values
mandatory options
fixed position parameters (optional, repeatable)
option / parameter parsers / validators
auto-generated help

Configuration

The library is controlled by a single JSON object defining the entire CLI structure. The main object used in this config is a CliCommand object. There are two types of CliCommand objects:

ActionCommands with fixed position parameter definitions and a single callback function
SubCommands with an array of CliCommand (Sub or Action) objects

A detailed description of the CliCommand object structure and it's child objects can be found in the sections below.

CliCommand object

ActionCommand handler

Command handlers are called with parameter values passed as arguments. An additional argument is added at the end being the options object. The option object is a dictionary with all parsed options. To demonstrate this on an example:

{
	name: "example"
	options: [{name: "optionName"}]
	parameters: [{name: "param1"}, {name: "param2"}]
	handler: (param1: string, param2: string, options: {optionName?: string}) => {
		/* do stuff */
	}
}

CliOption object

When using the library with typescript the mutual field exclusions are checked during compilation time via the type system. There are no runtime checks implemented and an invalid configuration can lead to unexpected behavior.

Command stack

Command stack is passed as the last argument to option handlers. It represents the current parser state and is useful mostly for generating help with CliMan.help. It simply is an array of all commands encountered in the input during parsing.

CliParameter object

No runtime checks are implemented for verifying parameter configuration consistency. An invalid configuration can lead to unexpected behavior.

Naming convention

All command, parameter and option names should be provided in camel case. They will be automatically converted to hyphen-separated names for matching CLI options and for the auto-generated help.

Auto-generated help

The library generates detailed usage help based on the configuration. The help messages are generated per command.

Help structure

usage: {root command name} {sub-command name} {...} {current command name} {parameter definition} {...}

{command help}

{command extended help}

#if SubCommand
Commands:
  {command name} : {parameter definition} {...}
  {...}
#else
Parameters:
  {parameter name}: {parameter help}
  {...}
#endif

Required options:
  {option definition}: {option help}
  {...}

Options:
  {option definition}: {option help}
  {...}

Inherited options ({sub-command name}):
  {option definition}: {option help}
  {...}

{...}

Global options:
  {option definition}: {option help}
  {...}

Note: Required options are combined from all sub-commands in the current path and displayed together

Parameter definitions

The format of the auto-generated parameter definitions has been described below:

| Parameter definition | description | | :--- | :--- | | [{name}={default}] | parameters with a default value | |[{name}] | optional parameter | | [{name}]+ | repeatable optional parameter | | <{name}>+ | repeatable non-optional parameter | | <{name}> | "normal" parameter |

Option definitions

The format of the auto-generated option definitions has been described below:

| Option definition | description | | :--- | :--- | | -{symbol}, --{name} <{valueName}={default}> | option with a default value | | -{symbol}, --{name} <{valueName}> | non boolean option without a default value | | -{symbol}, --{name} | boolean option | | -{symbol}, --{name} <valueName>, + | repeatable option |

Note: valueName when not provided defaults to VALUE

Invoking help

By default help is displayed

After a parse error
When parsing ends on a sub-command

A classic -h / --help can be easily implemented by adding a boolean option to the root command with CliMan.help as its handler.

{
	name: "help",
	symbol: "h",
	help: "display help and exit",
	boolean: true,
	handler: CliMan.help
}

Api

Exported types

CliCommand
CliOption
CliParameter

These types have been described in detail in the Configuration section above.

(Class) CliParseError

Extends standard Error. Error object thrown by the parser after encountering a parsing error. In addition to the error message an additional public member path: CliCommand[] is added to the error object. It contains the command stack and can be used to generate help using CliMan.help.

This error is thrown only from the runNoWrapper CliMan member function. Other run functions automatically catch this error, display the error message and generate help.

(Class) CliMan

The main class of this library.

Static members

run(config[, args])

config: CliCommand configuration JSON (described in on of the sections above)
args?: string[] command argument array. If not provided process.argv.slice(2) is used.

A do-it-all convenience function. Creates a CliMan object and calls the run function.

help(path[, returnAsString])

path: CliCommand[] the command stack to generate the help for
returnAsString?: boolean when true help is returned as a string, otherwise it is displayed using console.info

Generate the help message based on a command stack.

parsers

Some most common data parser functions bundled with the library to use with parameter / options values.

integer accepts decimal integer values, returns number
number accepts any decimal values, returns number
json accepts valid JSON strings, returns the parsed object
range(min: number, max: number, integer?: boolean) accepts decimal values in the <min, max) range, returns number; integer can be set to allow only integer values.
regex(re: RegExp, group?: number) accepts only values matching the provided RegExp object. By default returns the input string, but a chosen regex group can be return by providing the group number.
enum(...values: string[]) accepts only inputs matching one of the provided values, returns the input string

Public members

constructor(config)

config: CliCommand configuration JSON (described in on of the sections above)

run(args)

args: string[] command argument array to use

Runs the parser. After encountering an parse error the error message is displayed and help is printed.

runNoWrapper(args)

args: string[] command argument array to use

Runs the parser. After encountering a parse error CliParseError is thrown.

When parsing ends on a sub-command CliParseError is called with an empty message

Examples

import { CliMan } from "climan"

CliMan.run({
	name: "httpd",
	help: "http server daemon",
	options: [
		{
			name: "help",
			symbol: "h",
			help: "display help and exit",
			boolean: true,
			handler: CliMan.help
		},
		{
			name: "port",
			symbol: "p",
			help: "port to listen on",
			default: "80",
			parser: CliMan.parsers.integer
		},
		{
			name: "interface",
			symbol: "i",
			help: "interface to listen on",
			default: "localhost"
		}
	],
	parameters: [{name: "fsRoot", help: "server filesystem root"}],
	handler: (fsRoot: string, options: {port: number, interface: string}) =>
		console.log(`serving files from ${fsRoot} on ${options.interface}:${options.port}`)
})

Running this example without any arguments results in:

$ node ./example
error: no value provided for required Parameter "fs-root"

usage: httpd <fs-root>

http server daemon

Parameters:
  fs-root : server filesystem root

Options:
  -h, --help                        : display help and exit
  -p, --port <value=80>             : port to listen on
  -i, --interface <value=localhost> : interface to listen on

See examples folder for more examples.