argv-walk

Process command line arguments with complete control over how they are interpreted by defining a function to handle each parsed value.

• Based on minimist
• 100% unit test coverage
• Zero dependencies (124 LOC)
• Supports node 6+

Installation

npm install argv-walk

or

yarn add argv-walk

Usage

const walkArgv = require('argv-walk');

const args = { _: [] };

walkArgv(process.argv.slice(2), {
  onArg: (arg) => {
    if (arg.key) {
      args[arg.key] = arg.value;
    } else {
      args._.push(arg.item);
    }
  }
});

argv-walk is a lower level package than minimist so it has no concept of abstractions like aliases or types other than string and boolean.

This package is most useful when you would like to to provide your own implementations of such abstractions (or don't need them).

API

walkArgv

▸ walkArgv(argv: string[], options: Options): void

Iterate over argv array and call options.onArg for each parsed argument.

Uses minimist parsing conventions with the following differences:

• number-like values are NOT converted to numbers (they remain strings)
• dot separated arguments (ex. --foo.bar) are NOT treated differently than other arguments (when processing the preceding example, the argument key would be "foo.bar")

Returns: void

Options Properties

boolean

▸ boolean?: true | string | string[]

Optional: Key or array of keys to always treat as booleans, or true

If true, all double hyphenated arguments without equal signs are treated as boolean (e.g. affects --foo, not -f or --foo=bar).

onArg

▸ onArg(arg: Arg): boolean | undefined | void

Called with each argument

Returns: If false is returned, the walk will stop (no further args will be processed)

Arg Properties

item

▸ item: string

Current argv item

index

▸ index: number

Current argv index

indexOffset

▸ indexOffset: number

1 if value is based on the next argv item, otherwise 0

compoundIndex

▸ compoundIndex: number | undefined

Current compound index if argument is a compound argument (ex. -abc), otherwise undefined

Example: When processing -abc, a would have compoundIndex 0, b would have compoundIndex 1 and so on. The index value for all three keys would be the same (in this case 0).

isShort

▸ isShort: boolean

true if argument used short syntax (ex. -k or -abc), otherwise false

isStrict

▸ isStrict: boolean

true if argument used strict syntax (ex. --key=value or -k=value), otherwise false

key

▸ key: null | string

Parsed argument name

• null for positional arguments
• "--" for all arguments after -- is encountered

value

▸ value: boolean | string

Parsed value for key

Development

Requirements

• git
• node 8+ (argv-walk supports node 6+, but 8+ is required to run all package scripts except test)
• yarn

Setup

git clone https://github.com/adamjarret/argv-walk.git
cd argv-walk
yarn

If you use VS Code, see .vscode/settings.sample.json for recommended project settings.

Run Tests

yarn test

Package Scripts

yarn fix

Runs all the scripts required to format and check the module.

yarn lint

Runs eslint (see eslint) on all javascript files not ignored in the .eslintignore file.

See .eslintrc.js for configuration.

yarn pretty

Runs prettier (see prettier) to check source code file format. Files with the extensions ts, js, json or md that are not ignored in the .eslintignore file are processed.

See .prettierrc.js for configuration.

yarn spell

Runs cspell (see cspell) to spell-check source code files.

See .vscode/cSpell.json for configuration.

Note: This configuration path is used so the settings can also be honored by the Code Spell Checker plugin for VS Code.

yarn ncu

Runs ncu (see npm-check-updates) to check for dependency updates.

Use the -u flag to update version numbers in package.json file.

Any additional arguments will be passed to the ncu command.

yarn test

Runs all unit tests with spooning.

yarn cover

Same as yarn test but also collects and outputs test coverage information.

License

MIT

Author

Adam Jarret