X-Git-Url: https://gerrit.simantics.org/r/gitweb?a=blobdiff_plain;f=org.simantics.maps.server%2Fnode%2Fnode-v4.8.0-win-x64%2Fnode_modules%2Fnpm%2Fnode_modules%2Frequest%2Fnode_modules%2Fhttp-signature%2Fnode_modules%2Fsshpk%2Fnode_modules%2Fdashdash%2FREADME.md;fp=org.simantics.maps.server%2Fnode%2Fnode-v4.8.0-win-x64%2Fnode_modules%2Fnpm%2Fnode_modules%2Frequest%2Fnode_modules%2Fhttp-signature%2Fnode_modules%2Fsshpk%2Fnode_modules%2Fdashdash%2FREADME.md;h=e47b106e637d21d7d078a3806c9286906ee3208b;hb=2529be6d456deeb07c128603ce4971f1dc29b695;hp=0000000000000000000000000000000000000000;hpb=2636fc31c16c23711cf2b06a4ae8537bba9c1d35;p=simantics%2Fdistrict.git diff --git a/org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/node_modules/request/node_modules/http-signature/node_modules/sshpk/node_modules/dashdash/README.md b/org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/node_modules/request/node_modules/http-signature/node_modules/sshpk/node_modules/dashdash/README.md new file mode 100644 index 00000000..e47b106e --- /dev/null +++ b/org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/node_modules/request/node_modules/http-signature/node_modules/sshpk/node_modules/dashdash/README.md @@ -0,0 +1,574 @@ +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 @trentmick +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 ' 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 `.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: '', + 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.