ArgParser

MIT dep size Known Vulnerabilities

Secure and reliable Command Line Argument parser for Node.js ! ArgParser was designed to be embedded in a SlimIO agent, most popular library was not matching our expectation (and security needs).

It does not aim to replace (or to be) popular CLI lib like yargs or commander. Please, do not use this package if you do not know what you are doing.

👀 If you do not know what are script arguments, please check the Node.js documentation.

Requirements

Node.js v12 or higher

Why

Secure with 0 external dependencies.
Only ship feature required for SlimIO.
Use and return modern collection (Map over Object).

Non-goals

Performance over maintainability and readability.
Features over security.

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @slimio/arg-parser
# or
$ yarn add @slimio/arg-parser

Usage example

Create the following javascript script:

const { parseArg, argDefinition } = require("@slimio/arg-parser");

const result = parseArg([
    argDefinition("-c --colors [array]", "Array of colors"),
    argDefinition("--verbose", "Enable verbose mode!")
]);

console.log(result);

And then run the following command line:

$ node yourscript --colors red blue --verbose
$ Map { 'colors' => [ 'red', 'blue' ], 'verbose' => true }

👀 More examples can be found here

API

argDefinition(cmd: string, description?: string): Command

Generate a new Command definition. cmd argument is a string pattern that will be matched against the following regex: ```js /^(-{1}(?[a-z]){1})?\s?(-{2}(?[a-z]+)){1}\s?(\[(?number|string|boolean|array)(=(?.*))?\])?$/; ``` Take a look at the root directory `example` for more examples of how to use addCommand ! ```js const { parseArg, argDefinition } = require("@slimio/arg-parser"); const result = parseArg([ argDefinition("--verbose", "Enable verbose mode!"), argDefinition("-a --autoreload [number=500]", "Configuration Autoreload delay in number") ]); ``` A command is described as follow on TypeScript: ```ts interface Command { name: string; type: string; description: string; shortcut?: string; defaultVal?: number | string | boolean | any[]; } ``` Feel free to redefine the wrapper as you want !

parseArg< T >(argDefinitions: Command[], argv?: string[]): Map< keyof T, T[keyof T] >

Parse Argv (or any input `string[]`). Return a ECMAScript6 Map Object. ```js const { parseArg, argDefinition } = require("@slimio/arg-parser"); const argv = parseArg([ argDefinition("--level [number=1]") ], ["--level", "10"]); console.log(argv.get("level")); ``` Under the hood we use TypeScript with the following type ```ts export type ArgvResult = Map; ```

help(argDefinitions: Command[]): void

Display all commands information ```js const cmdDef = [ ArgParser.argDefinition("-p --product [number=10]", "Product number description"), ArgParser.argDefinition("-t --truc [string]"), ArgParser.argDefinition("--bidule") ]; ArgParser.help(cmdDef); // output -> // Usage : // - node file.js // - node file.js // // // -p --product number 10 Product number description // -t --truc string // --bidule boolean true ```

Dependencies

This project have no dependencies.

License

MIT

SlimIO / Arg-parser

readme