@thaerious/parseargs

Node Argument Parser

A simple no-dependency NodeJS module for parsing command line arguments. Unlike the built-in argument parser, this does not require tracked arguments to be declared in advance. Additionally, it allows for counting argument occurances.

Features:

• Parses single hyphen (-) and double hyphen (--) arguments.
• Permits but does not require custom configuration.
• Count flag occurances.

Installation

npm i @thaerious/parseargs

Default Behaviour

import ParseArgs from "../src/ParseArgs.js";
const parseArgs = new ParseArgs();

Command line arguments which are prefixed by a single '-', or double '--' dash are considered 'flags'. All other arguments are considered 'parameters'.

• A flag followed immediately by a parameter will be assigned that parameters string value.
• A flag with no parameter will be assigned boolean 'true'.
• Single dash flags consist of a single character and can be chained.
• The -- flag without text ends parsing.
• Flag names are case sensitive.

see /demo/default.js for examples

Double Dash Flags

Flags starting with two dashes take the name of the string after the dashes. If it is followed by a parameter the flag will be assigned that value, otherwise it is assigned boolean 'true'.

Single Dash Flags

Flags starting with a single dash can be chained. Single dash flags consist of a single character. Only the last flag in the chain will be assigned a parameter value.

Example

$> node demo/default.js --path . --no-copy -abc all

{
  path: '.',
  'no-copy': true,
  a: true,
  b: true,
  c: 'all',
  '$': [
    '/opt/node/19.3.0/bin/node',
    '/home/user/parser/demo/default.js'
  ]
}

Escape Processing

All arguments found after a lone '--' are not processed and will be appended to the '$' field.

$> node demo/default.js --input filename --output -- not_processed

{
  input: 'filename',
  output: true,
  '$': [
    '/opt/node/19.3.0/bin/node',
    '/home/user/parser/demo/default.js',
    'not_processed'
  ]
}

The ParseArgs object

To access a flag's value on the 'ParseArgs' object, treat the flag like a normal POJO value. For example to access the alpha flag use: parseArgs.alpha or parseArgs["alpha"].

To access the remaining unprocessed arguments use: parseArgs.$.

Custom Behaviour

Custom behaviour is defined by passing a definition object to the ParseArgs constructor. This allows you to define a short form flag, the type of flag, and it's default value.

import ParseArgs from "../src/ParseArgs.js";
const parseArgs = new ParseArgs(definitions);

The definitions object must contain a 'flags' field which contains an array of flag-definition objects.

const definitions = {    
    flags: [
        {
            long: "pack",
            short: "p",
            default: "a.json",
            type: "string",
        },
        {
            long: "verbose",
            short: "v",
            type: "count",
        }  
    ]
};

• Flags must have a long form name.
• Flags may have a short form name.
• The default value will be used if no parameter is available on the command line.
• String flags with no default will be assigned the empty string as it's default.
• Boolean and Count flags will not consume a parameter.
• Short forms for a flag will share all values with it's long form.
• Flags with a short form will only have the long form name in the resulting object.
• Flags with an env field will that their value added to process.env in the specified field.

Flags (non-boolean) can be assigned a default value. These flags will take on the default value if none is provided. Count flags have a default value of 0 if not otherwise specified; they will start counting at their default value.

Default Flags (no type)

• The default value of default flags is boolean false.
• Default flags that are present and did not consume an argument will be assigned the value boolean 'true', unless the default otherwise specified.
• Default flags that are present and consumed an argument will be assigned the consumed arguments value.

String Flags

• The default value of string flags is a zero-length string unless otherwise specified.
• String flags that are present and did not consume a parameter will be assigned the default value.
• They consume the next parameter if available and use that for their value.

definition

const definitions = {    
    flags: [
        {
            long: "pack",
            short: "p",
            default: "a.json",
            type: "string",
        }
    ]
}

result ^[1]

$ /index.js
{ pack : 'a.json' }

$ /index.js --pack file.tar
{ pack : 'file.tar' }

Boolean Flags

• The value of boolean flags is true if they are present, otherwise false.
• Boolean flags do not have default values.
• They do not consume parameters.

definition

const definitions = {    
    flags: [
        {
            long: "condense",
            short: "c",
            type: "boolean",
        }
    ]
}

result ^[1]

$ /index.js
{ condense : false } # default value

$ /index.js --condense file.tar # last argument ignored
{ condense : true }

$ /index.js -c file.tar # short form flag
{ condense : true }

Count Flags

• The value of count flags is the number of times the flag appears.
• If not present the default value is 0.
• Counting start at the devault value.
• They do not consume parameters.

definition

const definitions = {    
    flags: [
        {
            long: "verbose",
            short: "v",
            type: "count",
        }
    ]
}

result ^[1]

$ /index.js
{ verbose : 0 }

$ /index.js -v 
{ verbose : 1 }

$ /index.js -vv
{ verbose : 2 }

Notes

[1] Unprocessed arguments ($) excluded for brevity.