filter-argv
v1.0.2
Published
Mid-level process.argv filtering utils that make CLI arg extraction a breeze.
Downloads
5
Maintainers
Readme
filter-argv
Utilities for filtering raw process.argv content (i.e. arguments passed via the CLI). Easily extract or exclude flag arguments (e.g. -v, --debug), assignment arguments (e.g. name=meeka, --age=14), standard args (e.g. create-component, load, repl), lonely dashes ('-', '--'), and any combination of argument types.
##Quick examples
input:
npm run my-script -- create-component HelloWorld --verbose --debug name=meeka --type=puppy
in my-script:
const { filterArgv } = require('filter-argv');
filterArgv();
// => ['my-script', 'create-component', 'HelloWorld', 'name=meeka', '--type=puppy']
filterArgv(process.argv);
// => ['my-script', 'create-component', 'HelloWorld', 'name=meeka', '--type=puppy']
filterArgv({ keepLonelyDashes: true });
// => ['my-script', '--', 'create-component', 'HelloWorld', 'name=meeka', '--type=puppy']
filterArgv({ keepLonelyDashes: true, assignments: 'none' });
// => ['my-script', '--', 'create-component', 'HelloWorld']
filterArgv({ assignments: 'noflag' });
// => ['my-script', 'create-component', 'HelloWorld', 'name=meeka']
filterArgv({ standardArgs: false, assignments: 'all' });
// => ['name=meeka', '--type=puppy']
filterArgv({ flags: true, standardArgs: false });
// => ['--verbose', '--debug', 'name=meeka', '--type=puppy']
filterArgv({ flags: true, standardArgs: false, assignments: 'noflag' });
// => ['--verbose', '--debug', 'name=meeka']
filterArgv({ flags: true, standardArgs: false, assignments: 'noflag', keepLonelyDashes: true });
// => ['--', --verbose', '--debug', 'name=meeka']
##Type signatures
filterArgv: (processArg?: Array<String>, opts?: Options) => Array<String>
processArg: optional parameter containing a string array, presumably process.argv or a modified form of it. However, any array of strings can be used - it is not limited to process.argv
- by default, returns a duplicate of the array with all flag arguments removed.
- if no value is passed, defaults to the current value of process.argv
- note: if you're parsing process.argv, for convenience you can simply pass in the Options object at this argument. The module will detect it, assign options correctly, & automatically parse the contents of process.argv.
opts: (type Options): Provides options for filtering the process arguments. By default, excludes flag CLI args (e.g. -a, --gbr), excepting those used for assignment (e.g. it keeps args like --name=meeka, -type=puppy).
- opts.flags: true | false
- Default: false
- if true, keep flags in the returned process.argv object
- opts.standardArgs: true | false
- Default: true
- if true, keep standard (non-flag, non-assignment) arguments in the output (e.g. meeka, puppy)
- opts.assignments: 'all' | 'none' | 'no-flags
- Default: all
- 'all': keep all assignment args (e.g. --name=meeka, age=43, --etc=ok)
- 'none': exclude all assignment args
- 'no-flags': exclude assignment args that are also flags (e.g. --name=meeka)
- opts.keepLonelyDashes: true | false
- Default: false
- if true, keep isolated dashes ('-', '--', '---') in the output
- opts.flags: true | false
Examples
//my-script.js
const { filterArgv } = require('filter-argv');
const contentArgsOnly = filterArgv();
console.log(contentArgsOnly);
The output of the above example will vary based on how the script was run (from the terminal). e.g.:
input: node my-script.js --verbose
output: ["node", "my-script.js"]
input: node my-script.js
output: ["node", "my-script.js"]
input: my-script.js --verbose create-component SidebarGrid
output: ["my-script.js", "create-component", "SidebarGrid"]
input: my-script.js --verbose create-component SidebarGrid --debug
output: ["my-script.js", "create-component", "SidebarGrid"]
input: my-script.js --verbose create-component --name=SidebarGrid --debug
output: ["my-script.js", "create-component", "--name=SidebarGrid"]
Other filterArgv examples :
const contentArgsOnly = filterArgv(process.argv); // mainly for explicitness
const contentArgsOnly = filterArgv(['hello', '--flag', 'custom', 'array', 'example']);
const contentArgsOnly = filterArgv({
assignments: 'noflag',
flags: true,
standardArgs: false,
keepLonelyDashes: true
});
getStandardFlags: (argv?: Array) => Array
Convenience function to return a list of the flags in an arguments list. e.g.
getStandardFlags(['--verbose', 'reth', '--asdf=fghj', '--debug', 'boo']);
// => ['--verbose', '--debug']
getAssignmentArgsOnly: (argv?: Array) => Array
Convenience function to return a list of the assignment args in an arguments list. e.g.
getAssignmentArgsOnly(['--verbose', 'reth', '--asdf=fghj', '--debug', 'boo', 'type=Bear']);
// => ['--asdf=fghj', 'type=Bear']