diff options
Diffstat (limited to 'node_modules/dashdash/README.md')
| -rw-r--r-- | node_modules/dashdash/README.md | 574 |
1 files changed, 0 insertions, 574 deletions
diff --git a/node_modules/dashdash/README.md b/node_modules/dashdash/README.md deleted file mode 100644 index e47b106..0000000 --- a/node_modules/dashdash/README.md +++ /dev/null @@ -1,574 +0,0 @@ -A light, featureful and explicit option parsing library for node.js. - -[Why another one? See below](#why). tl;dr: The others I've tried are one of -too loosey goosey (not explicit), too big/too many deps, or ill specified. -YMMV. - -Follow <a href="https://twitter.com/intent/user?screen_name=trentmick" target="_blank">@trentmick</a> -for updates to node-dashdash. - -# Install - - npm install dashdash - - -# Usage - -```javascript -var dashdash = require('dashdash'); - -// Specify the options. Minimally `name` (or `names`) and `type` -// must be given for each. -var options = [ - { - // `names` or a single `name`. First element is the `opts.KEY`. - names: ['help', 'h'], - // See "Option specs" below for types. - type: 'bool', - help: 'Print this help and exit.' - } -]; - -// Shortcut form. As called it infers `process.argv`. See below for -// the longer form to use methods like `.help()` on the Parser object. -var opts = dashdash.parse({options: options}); - -console.log("opts:", opts); -console.log("args:", opts._args); -``` - - -# Longer Example - -A more realistic [starter script "foo.js"](./examples/foo.js) is as follows. -This also shows using `parser.help()` for formatted option help. - -```javascript -var dashdash = require('./lib/dashdash'); - -var options = [ - { - name: 'version', - type: 'bool', - help: 'Print tool version and exit.' - }, - { - names: ['help', 'h'], - type: 'bool', - help: 'Print this help and exit.' - }, - { - names: ['verbose', 'v'], - type: 'arrayOfBool', - help: 'Verbose output. Use multiple times for more verbose.' - }, - { - names: ['file', 'f'], - type: 'string', - help: 'File to process', - helpArg: 'FILE' - } -]; - -var parser = dashdash.createParser({options: options}); -try { - var opts = parser.parse(process.argv); -} catch (e) { - console.error('foo: error: %s', e.message); - process.exit(1); -} - -console.log("# opts:", opts); -console.log("# args:", opts._args); - -// Use `parser.help()` for formatted options help. -if (opts.help) { - var help = parser.help({includeEnv: true}).trimRight(); - console.log('usage: node foo.js [OPTIONS]\n' - + 'options:\n' - + help); - process.exit(0); -} - -// ... -``` - - -Some example output from this script (foo.js): - -``` -$ node foo.js -h -# opts: { help: true, - _order: [ { name: 'help', value: true, from: 'argv' } ], - _args: [] } -# args: [] -usage: node foo.js [OPTIONS] -options: - --version Print tool version and exit. - -h, --help Print this help and exit. - -v, --verbose Verbose output. Use multiple times for more verbose. - -f FILE, --file=FILE File to process - -$ node foo.js -v -# opts: { verbose: [ true ], - _order: [ { name: 'verbose', value: true, from: 'argv' } ], - _args: [] } -# args: [] - -$ node foo.js --version arg1 -# opts: { version: true, - _order: [ { name: 'version', value: true, from: 'argv' } ], - _args: [ 'arg1' ] } -# args: [ 'arg1' ] - -$ node foo.js -f bar.txt -# opts: { file: 'bar.txt', - _order: [ { name: 'file', value: 'bar.txt', from: 'argv' } ], - _args: [] } -# args: [] - -$ node foo.js -vvv --file=blah -# opts: { verbose: [ true, true, true ], - file: 'blah', - _order: - [ { name: 'verbose', value: true, from: 'argv' }, - { name: 'verbose', value: true, from: 'argv' }, - { name: 'verbose', value: true, from: 'argv' }, - { name: 'file', value: 'blah', from: 'argv' } ], - _args: [] } -# args: [] -``` - - -See the ["examples"](examples/) dir for a number of starter examples using -some of dashdash's features. - - -# Environment variable integration - -If you want to allow environment variables to specify options to your tool, -dashdash makes this easy. We can change the 'verbose' option in the example -above to include an 'env' field: - -```javascript - { - names: ['verbose', 'v'], - type: 'arrayOfBool', - env: 'FOO_VERBOSE', // <--- add this line - help: 'Verbose output. Use multiple times for more verbose.' - }, -``` - -then the **"FOO_VERBOSE" environment variable** can be used to set this -option: - -```shell -$ FOO_VERBOSE=1 node foo.js -# opts: { verbose: [ true ], - _order: [ { name: 'verbose', value: true, from: 'env' } ], - _args: [] } -# args: [] -``` - -Boolean options will interpret the empty string as unset, '0' as false -and anything else as true. - -```shell -$ FOO_VERBOSE= node examples/foo.js # not set -# opts: { _order: [], _args: [] } -# args: [] - -$ FOO_VERBOSE=0 node examples/foo.js # '0' is false -# opts: { verbose: [ false ], - _order: [ { key: 'verbose', value: false, from: 'env' } ], - _args: [] } -# args: [] - -$ FOO_VERBOSE=1 node examples/foo.js # true -# opts: { verbose: [ true ], - _order: [ { key: 'verbose', value: true, from: 'env' } ], - _args: [] } -# args: [] - -$ FOO_VERBOSE=boogabooga node examples/foo.js # true -# opts: { verbose: [ true ], - _order: [ { key: 'verbose', value: true, from: 'env' } ], - _args: [] } -# args: [] -``` - -Non-booleans can be used as well. Strings: - -```shell -$ FOO_FILE=data.txt node examples/foo.js -# opts: { file: 'data.txt', - _order: [ { key: 'file', value: 'data.txt', from: 'env' } ], - _args: [] } -# args: [] -``` - -Numbers: - -```shell -$ FOO_TIMEOUT=5000 node examples/foo.js -# opts: { timeout: 5000, - _order: [ { key: 'timeout', value: 5000, from: 'env' } ], - _args: [] } -# args: [] - -$ FOO_TIMEOUT=blarg node examples/foo.js -foo: error: arg for "FOO_TIMEOUT" is not a positive integer: "blarg" -``` - -With the `includeEnv: true` config to `parser.help()` the environment -variable can also be included in **help output**: - - usage: node foo.js [OPTIONS] - options: - --version Print tool version and exit. - -h, --help Print this help and exit. - -v, --verbose Verbose output. Use multiple times for more verbose. - Environment: FOO_VERBOSE=1 - -f FILE, --file=FILE File to process - - -# Bash completion - -Dashdash provides a simple way to create a Bash completion file that you -can place in your "bash_completion.d" directory -- sometimes that is -"/usr/local/etc/bash_completion.d/"). Features: - -- Support for short and long opts -- Support for knowing which options take arguments -- Support for subcommands (e.g. 'git log <TAB>' to show just options for the - log subcommand). See - [node-cmdln](https://github.com/trentm/node-cmdln#bash-completion) for - how to integrate that. -- Does the right thing with "--" to stop options. -- Custom optarg and arg types for custom completions. - -Dashdash will return bash completion file content given a parser instance: - - var parser = dashdash.createParser({options: options}); - console.log( parser.bashCompletion({name: 'mycli'}) ); - -or directly from a `options` array of options specs: - - var code = dashdash.bashCompletionFromOptions({ - name: 'mycli', - options: OPTIONS - }); - -Write that content to "/usr/local/etc/bash_completion.d/mycli" and you will -have Bash completions for `mycli`. Alternatively you can write it to -any file (e.g. "~/.bashrc") and source it. - -You could add a `--completion` hidden option to your tool that emits the -completion content and document for your users to call that to install -Bash completions. - -See [examples/ddcompletion.js](examples/ddcompletion.js) for a complete -example, including how one can define bash functions for completion of custom -option types. Also see [node-cmdln](https://github.com/trentm/node-cmdln) for -how it uses this for Bash completion for full multi-subcommand tools. - -- TODO: document specExtra -- TODO: document includeHidden -- TODO: document custom types, `function complete\_FOO` guide, completionType -- TODO: document argtypes - - -# Parser config - -Parser construction (i.e. `dashdash.createParser(CONFIG)`) takes the -following fields: - -- `options` (Array of option specs). Required. See the - [Option specs](#option-specs) section below. - -- `interspersed` (Boolean). Optional. Default is true. If true this allows - interspersed arguments and options. I.e.: - - node ./tool.js -v arg1 arg2 -h # '-h' is after interspersed args - - Set it to false to have '-h' **not** get parsed as an option in the above - example. - -- `allowUnknown` (Boolean). Optional. Default is false. If false, this causes - unknown arguments to throw an error. I.e.: - - node ./tool.js -v arg1 --afe8asefksjefhas - - Set it to true to treat the unknown option as a positional - argument. - - **Caveat**: When a shortopt group, such as `-xaz` contains a mix of - known and unknown options, the *entire* group is passed through - unmolested as a positional argument. - - Consider if you have a known short option `-a`, and parse the - following command line: - - node ./tool.js -xaz - - where `-x` and `-z` are unknown. There are multiple ways to - interpret this: - - 1. `-x` takes a value: `{x: 'az'}` - 2. `-x` and `-z` are both booleans: `{x:true,a:true,z:true}` - - Since dashdash does not know what `-x` and `-z` are, it can't know - if you'd prefer to receive `{a:true,_args:['-x','-z']}` or - `{x:'az'}`, or `{_args:['-xaz']}`. Leaving the positional arg unprocessed - is the easiest mistake for the user to recover from. - - -# Option specs - -Example using all fields (required fields are noted): - -```javascript -{ - names: ['file', 'f'], // Required (one of `names` or `name`). - type: 'string', // Required. - completionType: 'filename', - env: 'MYTOOL_FILE', - help: 'Config file to load before running "mytool"', - helpArg: 'PATH', - helpWrap: false, - default: path.resolve(process.env.HOME, '.mytoolrc') -} -``` - -Each option spec in the `options` array must/can have the following fields: - -- `name` (String) or `names` (Array). Required. These give the option name - and aliases. The first name (if more than one given) is the key for the - parsed `opts` object. - -- `type` (String). Required. One of: - - - bool - - string - - number - - integer - - positiveInteger - - date (epoch seconds, e.g. 1396031701, or ISO 8601 format - `YYYY-MM-DD[THH:MM:SS[.sss][Z]]`, e.g. "2014-03-28T18:35:01.489Z") - - arrayOfBool - - arrayOfString - - arrayOfNumber - - arrayOfInteger - - arrayOfPositiveInteger - - arrayOfDate - - FWIW, these names attempt to match with asserts on - [assert-plus](https://github.com/mcavage/node-assert-plus). - You can add your own custom option types with `dashdash.addOptionType`. - See below. - -- `completionType` (String). Optional. This is used for [Bash - completion](#bash-completion) for an option argument. If not specified, - then the value of `type` is used. Any string may be specified, but only the - following values have meaning: - - - `none`: Provide no completions. - - `file`: Bash's default completion (i.e. `complete -o default`), which - includes filenames. - - *Any string FOO for which a `function complete_FOO` Bash function is - defined.* This is for custom completions for a given tool. Typically - these custom functions are provided in the `specExtra` argument to - `dashdash.bashCompletionFromOptions()`. See - ["examples/ddcompletion.js"](examples/ddcompletion.js) for an example. - -- `env` (String or Array of String). Optional. An environment variable name - (or names) that can be used as a fallback for this option. For example, - given a "foo.js" like this: - - var options = [{names: ['dry-run', 'n'], env: 'FOO_DRY_RUN'}]; - var opts = dashdash.parse({options: options}); - - Both `node foo.js --dry-run` and `FOO_DRY_RUN=1 node foo.js` would result - in `opts.dry_run = true`. - - An environment variable is only used as a fallback, i.e. it is ignored if - the associated option is given in `argv`. - -- `help` (String). Optional. Used for `parser.help()` output. - -- `helpArg` (String). Optional. Used in help output as the placeholder for - the option argument, e.g. the "PATH" in: - - ... - -f PATH, --file=PATH File to process - ... - -- `helpWrap` (Boolean). Optional, default true. Set this to `false` to have - that option's `help` *not* be text wrapped in `<parser>.help()` output. - -- `default`. Optional. A default value used for this option, if the - option isn't specified in argv. - -- `hidden` (Boolean). Optional, default false. If true, help output will not - include this option. See also the `includeHidden` option to - `bashCompletionFromOptions()` for [Bash completion](#bash-completion). - - -# Option group headings - -You can add headings between option specs in the `options` array. To do so, -simply add an object with only a `group` property -- the string to print as -the heading for the subsequent options in the array. For example: - -```javascript -var options = [ - { - group: 'Armament Options' - }, - { - names: [ 'weapon', 'w' ], - type: 'string' - }, - { - group: 'General Options' - }, - { - names: [ 'help', 'h' ], - type: 'bool' - } -]; -... -``` - -Note: You can use an empty string, `{group: ''}`, to get a blank line in help -output between groups of options. - - -# Help config - -The `parser.help(...)` function is configurable as follows: - - Options: - Armament Options: - ^^ -w WEAPON, --weapon=WEAPON Weapon with which to crush. One of: | - / sword, spear, maul | - / General Options: | - / -h, --help Print this help and exit. | - / ^^^^ ^ | - \ `-- indent `-- helpCol maxCol ---' - `-- headingIndent - -- `indent` (Number or String). Default 4. Set to a number (for that many - spaces) or a string for the literal indent. -- `headingIndent` (Number or String). Default half length of `indent`. Set to - a number (for that many spaces) or a string for the literal indent. This - indent applies to group heading lines, between normal option lines. -- `nameSort` (String). Default is 'length'. By default the names are - sorted to put the short opts first (i.e. '-h, --help' preferred - to '--help, -h'). Set to 'none' to not do this sorting. -- `maxCol` (Number). Default 80. Note that reflow is just done on whitespace - so a long token in the option help can overflow maxCol. -- `helpCol` (Number). If not set a reasonable value will be determined - between `minHelpCol` and `maxHelpCol`. -- `minHelpCol` (Number). Default 20. -- `maxHelpCol` (Number). Default 40. -- `helpWrap` (Boolean). Default true. Set to `false` to have option `help` - strings *not* be textwrapped to the helpCol..maxCol range. -- `includeEnv` (Boolean). Default false. If the option has associated - environment variables (via the `env` option spec attribute), then - append mentioned of those envvars to the help string. -- `includeDefault` (Boolean). Default false. If the option has a default value - (via the `default` option spec attribute, or a default on the option's type), - then a "Default: VALUE" string will be appended to the help string. - - -# Custom option types - -Dashdash includes a good starter set of option types that it will parse for -you. However, you can add your own via: - - var dashdash = require('dashdash'); - dashdash.addOptionType({ - name: '...', - takesArg: true, - helpArg: '...', - parseArg: function (option, optstr, arg) { - ... - }, - array: false, // optional - arrayFlatten: false, // optional - default: ..., // optional - completionType: ... // optional - }); - -For example, a simple option type that accepts 'yes', 'y', 'no' or 'n' as -a boolean argument would look like: - - var dashdash = require('dashdash'); - - function parseYesNo(option, optstr, arg) { - var argLower = arg.toLowerCase() - if (~['yes', 'y'].indexOf(argLower)) { - return true; - } else if (~['no', 'n'].indexOf(argLower)) { - return false; - } else { - throw new Error(format( - 'arg for "%s" is not "yes" or "no": "%s"', - optstr, arg)); - } - } - - dashdash.addOptionType({ - name: 'yesno' - takesArg: true, - helpArg: '<yes|no>', - parseArg: parseYesNo - }); - - var options = { - {names: ['answer', 'a'], type: 'yesno'} - }; - var opts = dashdash.parse({options: options}); - -See "examples/custom-option-\*.js" for other examples. -See the `addOptionType` block comment in "lib/dashdash.js" for more details. -Please let me know [with an -issue](https://github.com/trentm/node-dashdash/issues/new) if you write a -generally useful one. - - - -# Why - -Why another node.js option parsing lib? - -- `nopt` really is just for "tools like npm". Implicit opts (e.g. '--no-foo' - works for every '--foo'). Can't disable abbreviated opts. Can't do multiple - usages of same opt, e.g. '-vvv' (I think). Can't do grouped short opts. - -- `optimist` has surprise interpretation of options (at least to me). - Implicit opts mean ambiguities and poor error handling for fat-fingering. - `process.exit` calls makes it hard to use as a libary. - -- `optparse` Incomplete docs. Is this an attempted clone of Python's `optparse`. - Not clear. Some divergence. `parser.on("name", ...)` API is weird. - -- `argparse` Dep on underscore. No thanks just for option processing. - `find lib | wc -l` -> `26`. Overkill. - Argparse is a bit different anyway. Not sure I want that. - -- `posix-getopt` No type validation. Though that isn't a killer. AFAIK can't - have a long opt without a short alias. I.e. no `getopt_long` semantics. - Also, no whizbang features like generated help output. - -- ["commander.js"](https://github.com/visionmedia/commander.js): I wrote - [a critique](http://trentm.com/2014/01/a-critique-of-commander-for-nodejs.html) - a while back. It seems fine, but last I checked had - [an outstanding bug](https://github.com/visionmedia/commander.js/pull/121) - that would prevent me from using it. - - -# License - -MIT. See LICENSE.txt. |