From d38dfbd7dd0701591c7b275a2ce7811b0d152746 Mon Sep 17 00:00:00 2001 From: Lloyd Brookes Date: Wed, 1 Feb 2017 10:24:10 +0000 Subject: [PATCH] docs --- README.md | 31 ++++++++++++++++++++++++++++++- example/mocha.js | 4 ++-- jsdoc2md/README.hbs | 29 +++++++++++++++++++++++++++++ lib/command-line-args.js | 2 +- 4 files changed, 62 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 8494f45..c40426f 100644 --- a/README.md +++ b/README.md @@ -86,6 +86,35 @@ We have an issue here: command-line-args will assume we are setting two options $ grep-tool --search=-f ``` +### Partial parsing + +By default, if the user sets an option without a valid [definition](#exp_module_definition--OptionDefinition) an `UNKNOWN_OPTION` exception is thrown. However, in some cases you may only be interested in a subset of the options wishing to pass the remainder to another library. See [here](https://github.com/75lb/command-line-args/blob/master/example/mocha.js) for a example showing where this might be necessary. + +To enable partial parsing, set `partial: true` in the method options: + +```js +const optionDefinitions = [ + { name: 'value', type: Number } +] +const options = commandLineArgs(optionDefinitions, { partial: true }) +``` + +Now, should any unknown args be passed at the command line: + +``` +$ example --milk --value 2 --bread cheese +``` + +They will be returned in the `_unknown` property of the `commandLineArgs` output with no exceptions thrown: + +```js +{ + value: 2, + _unknown: [ '--milk', '--bread', 'cheese'] +} +``` + + ## Install ```sh @@ -98,7 +127,7 @@ $ npm install command-line-args --save ### commandLineArgs(optionDefinitions, [options]) ⇒ object ⏏ Returns an object containing all options set on the command line. By default it parses the global [`process.argv`](https://nodejs.org/api/process.html#process_process_argv) array. -By default, an exception is thrown if the user sets an unknown option (one without a valid [definition](#exp_module_definition--OptionDefinition)). To enable __partial parsing__, invoke `commandLineArgs` with the `partial` option - all unknown arguments will be returned in the additional `_unknown` property of the output. +By default, an exception is thrown if the user sets an unknown option (one without a valid [definition](#exp_module_definition--OptionDefinition)). To enable __partial parsing__, invoke `commandLineArgs` with the `partial` option - all unknown arguments will be returned in the `_unknown` property. **Kind**: Exported function **Throws**: diff --git a/example/mocha.js b/example/mocha.js index feda9cc..36356a8 100644 --- a/example/mocha.js +++ b/example/mocha.js @@ -6,8 +6,8 @@ const assert = require('assert') const commandLineArgs = require('../') /* -enable partial parsing to prevent exceptions being thrown -if the user sets undefined, mocha-specific options (e.g. --no-colors) +enable partial parsing to prevent `UNKNOWN_OPTION` exceptions being thrown +if the user sets mocha-specific options (e.g. --no-colors) */ const options = commandLineArgs({ name: 'value', type: Number }, { partial: true }) diff --git a/jsdoc2md/README.hbs b/jsdoc2md/README.hbs index c7f220d..d9d89f6 100644 --- a/jsdoc2md/README.hbs +++ b/jsdoc2md/README.hbs @@ -86,6 +86,35 @@ We have an issue here: command-line-args will assume we are setting two options $ grep-tool --search=-f ``` +### Partial parsing + +By default, if the user sets an option without a valid [definition](#exp_module_definition--OptionDefinition) an `UNKNOWN_OPTION` exception is thrown. However, in some cases you may only be interested in a subset of the options wishing to pass the remainder to another library. See [here](https://github.com/75lb/command-line-args/blob/master/example/mocha.js) for a example showing where this might be necessary. + +To enable partial parsing, set `partial: true` in the method options: + +```js +const optionDefinitions = [ + { name: 'value', type: Number } +] +const options = commandLineArgs(optionDefinitions, { partial: true }) +``` + +Now, should any unknown args be passed at the command line: + +``` +$ example --milk --value 2 --bread cheese +``` + +They will be returned in the `_unknown` property of the `commandLineArgs` output with no exceptions thrown: + +```js +{ + value: 2, + _unknown: [ '--milk', '--bread', 'cheese'] +} +``` + + ## Install ```sh diff --git a/lib/command-line-args.js b/lib/command-line-args.js index ef7262b..d02647f 100644 --- a/lib/command-line-args.js +++ b/lib/command-line-args.js @@ -8,7 +8,7 @@ module.exports = commandLineArgs /** * Returns an object containing all options set on the command line. By default it parses the global [`process.argv`](https://nodejs.org/api/process.html#process_process_argv) array. * - * By default, an exception is thrown if the user sets an unknown option (one without a valid [definition](#exp_module_definition--OptionDefinition)). To enable __partial parsing__, invoke `commandLineArgs` with the `partial` option - all unknown arguments will be returned in the additional `_unknown` property of the output. + * By default, an exception is thrown if the user sets an unknown option (one without a valid [definition](#exp_module_definition--OptionDefinition)). To enable __partial parsing__, invoke `commandLineArgs` with the `partial` option - all unknown arguments will be returned in the `_unknown` property. * * * @param {module:definition[]} - An array of [OptionDefinition](#exp_module_definition--OptionDefinition) objects