minargs is an argument parser with minimal configuration & assumptions. Argument parsing can take many shapes but the explicit goals of this library are as follows:
Goals
no usage
no validation
no types or type cohersion
no regular expressions
no strictness
no dependencies
no information loss
minimal assumptions
minimal configuration
consistant results/format
100% test coverage
Mantras
Bring Your Own Usage™️
Bring Your Own Validation™️
Installation
npm install minargs
minargs([argv][, options])
argv (Array)
Default: process.argv
The argument strings to parse
Options
alias (Object)
Default: none
Define shorts & aliases to map to a canonical argument
Note: only single character aliases can be parsed as "shorts" (read more in the F.A.Q. below)
positionalValues (Boolean)
Default: false
Define whether or not to use positionals that follow bare flag definitions as values
recursive (Boolean)
Default: false
Define whether or not to end parsing when a bare -- marker is found
Strictness is a function of usage. By default, minargs does not assume anything about "known" or "unknown" arguments or their intended values (ex. defaults/types). Usage examples above show how you can quickly & easily utilize minargs as the backbone for an application which does enforce strictness/validation & more.
Are shorts supported?
Yes.
Individual (ex. -a) & combined (ex. -aCdeFg) shorts are supported
-a=b will capture & return "b" as a value
-a b will capture & return "b" as a value if positionalValues is true
Are multiples supported?
Yes.
By default multiple definitions of the same argument will get consolidated into a single arg entry with a corresponding Array of String values
Getting the last defined value of an argument is as simple as running .pop() on the Array (ex. args.foo.pop())
What is an alias?
An alias can be any other string that maps to a canonical option; this includes single characters which will map shorts to a long-form (ex. alias: { f: foo } will parse -f as { args: { "foo": [""] } })
Is cmd --foo=bar baz the same as cmd baz --foo=bar?
Sort of.
The returned argvArray will change to reflect the differing positions of the arguments & positionals BUTargs & positionals will remain consistent
Is value validation or type cohersion supported?
No.
Are usage errors supported?
No.
Does --no-foo coerce to --foo=false?
No.
--no-foo will parse to { args: { "no-foo": [""] } } & --foo-false to { args: { "no-foo": ["false"] } } respectively
Is --foo the same as --foo=true?
No.
--foo will parse to { args: { "foo": [""] } } & --foo=true to { args: { "foo": ["true"] } } respectively
Are environment variables supported?
No.
Does -- signal the end of flags/options?
Yes.
Any arguments following a bare -- definition will be returned in remainder.
Is a value stored to represent the existence of --?
No.
The only way to determine if -- was present & there were arguments passed afterward is to check the value of remainder
Are negative numbers supported as positional values?
No.
minargs aligns with the POSIX Argument Syntax here (ie. "Arguments are options if they begin with a hyphen delimiter")
--number -2 will be parsed as { args: { "number": [""], "2": [""] } }
You will have to use explicit value setting to make this association (ex. --number=-2) & may further require validation/type coercion to determine if the value is a Number (as is shown in the usage examples above)