Differential D22653 Diff 62759 node_modules/argparse/README.md

Changeset View

Standalone View

View Options

node_modules/argparse/README.md

  • This file was added.
1​argparse
2​========
3​
4​[![Build Status](https://secure.travis-ci.org/nodeca/argparse.svg?branch=master)](http://travis-ci.org/nodeca/argparse)
5​[![NPM version](https://img.shields.io/npm/v/argparse.svg)](https://www.npmjs.org/package/argparse)
6​
7​CLI arguments parser for node.js. Javascript port of python's
8​[argparse](http://docs.python.org/dev/library/argparse.html) module
9​(original version 3.2). That's a full port, except some very rare options,
10​recorded in issue tracker.
11​
12​**NB. Difference with original.**
13​
14​- Method names changed to camelCase. See [generated docs](http://nodeca.github.com/argparse/).
15​- Use `defaultValue` instead of `default`.
16​- Use `argparse.Const.REMAINDER` instead of `argparse.REMAINDER`, and
17​ similarly for constant values `OPTIONAL`, `ZERO_OR_MORE`, and `ONE_OR_MORE`
18​ (aliases for `nargs` values `'?'`, `'*'`, `'+'`, respectively), and
19​ `SUPPRESS`.
20​
21​
22​Example
23​=======
24​
25​test.js file:
26​
27​```javascript
28​#!/usr/bin/env node
29​'use strict';
30​
31​var ArgumentParser = require('../lib/argparse').ArgumentParser;
32​var parser = new ArgumentParser({
33​ version: '0.0.1',
34​ addHelp:true,
35​ description: 'Argparse example'
36​});
37​parser.addArgument(
38​ [ '-f', '--foo' ],
39​ {
40​ help: 'foo bar'
41​ }
42​);
43​parser.addArgument(
44​ [ '-b', '--bar' ],
45​ {
46​ help: 'bar foo'
47​ }
48​);
49​parser.addArgument(
50​ '--baz',
51​ {
52​ help: 'baz bar'
53​ }
54​);
55​var args = parser.parseArgs();
56​console.dir(args);
57​```
58​
59​Display help:
60​
61​```
62​$ ./test.js -h
63​usage: example.js [-h] [-v] [-f FOO] [-b BAR] [--baz BAZ]
64​
65​Argparse example
66​
67​Optional arguments:
68​ -h, --help Show this help message and exit.
69​ -v, --version Show program's version number and exit.
70​ -f FOO, --foo FOO foo bar
71​ -b BAR, --bar BAR bar foo
72​ --baz BAZ baz bar
73​```
74​
75​Parse arguments:
76​
77​```
78​$ ./test.js -f=3 --bar=4 --baz 5
79​{ foo: '3', bar: '4', baz: '5' }
80​```
81​
82​More [examples](https://github.com/nodeca/argparse/tree/master/examples).
83​
84​
85​ArgumentParser objects
86​======================
87​
88​```
89​new ArgumentParser({parameters hash});
90​```
91​
92​Creates a new ArgumentParser object.
93​
94​**Supported params:**
95​
96​- ```description``` - Text to display before the argument help.
97​- ```epilog``` - Text to display after the argument help.
98​- ```addHelp``` - Add a -h/–help option to the parser. (default: true)
99​- ```argumentDefault``` - Set the global default value for arguments. (default: null)
100​- ```parents``` - A list of ArgumentParser objects whose arguments should also be included.
101​- ```prefixChars``` - The set of characters that prefix optional arguments. (default: ‘-‘)
102​- ```formatterClass``` - A class for customizing the help output.
103​- ```prog``` - The name of the program (default: `path.basename(process.argv[1])`)
104​- ```usage``` - The string describing the program usage (default: generated)
105​- ```conflictHandler``` - Usually unnecessary, defines strategy for resolving conflicting optionals.
106​
107​**Not supported yet**
108​
109​- ```fromfilePrefixChars``` - The set of characters that prefix files from which additional arguments should be read.
110​
111​
112​Details in [original ArgumentParser guide](http://docs.python.org/dev/library/argparse.html#argumentparser-objects)
113​
114​
115​addArgument() method
116​====================
117​
118​```
119​ArgumentParser.addArgument(name or flag or [name] or [flags...], {options})
120​```
121​
122​Defines how a single command-line argument should be parsed.
123​
124​- ```name or flag or [name] or [flags...]``` - Either a positional name
125​ (e.g., `'foo'`), a single option (e.g., `'-f'` or `'--foo'`), an array
126​ of a single positional name (e.g., `['foo']`), or an array of options
127​ (e.g., `['-f', '--foo']`).
128​
129​Options:
130​
131​- ```action``` - The basic type of action to be taken when this argument is encountered at the command line.
132​- ```nargs```- The number of command-line arguments that should be consumed.
133​- ```constant``` - A constant value required by some action and nargs selections.
134​- ```defaultValue``` - The value produced if the argument is absent from the command line.
135​- ```type``` - The type to which the command-line argument should be converted.
136​- ```choices``` - A container of the allowable values for the argument.
137​- ```required``` - Whether or not the command-line option may be omitted (optionals only).
138​- ```help``` - A brief description of what the argument does.
139​- ```metavar``` - A name for the argument in usage messages.
140​- ```dest``` - The name of the attribute to be added to the object returned by parseArgs().
141​
142​Details in [original add_argument guide](http://docs.python.org/dev/library/argparse.html#the-add-argument-method)
143​
144​
145​Action (some details)
146​================
147​
148​ArgumentParser objects associate command-line arguments with actions.
149​These actions can do just about anything with the command-line arguments associated
150​with them, though most actions simply add an attribute to the object returned by
151​parseArgs(). The action keyword argument specifies how the command-line arguments
152​should be handled. The supported actions are:
153​
154​- ```store``` - Just stores the argument’s value. This is the default action.
155​- ```storeConst``` - Stores value, specified by the const keyword argument.
156​ (Note that the const keyword argument defaults to the rather unhelpful None.)
157​ The 'storeConst' action is most commonly used with optional arguments, that
158​ specify some sort of flag.
159​- ```storeTrue``` and ```storeFalse``` - Stores values True and False
160​ respectively. These are special cases of 'storeConst'.
161​- ```append``` - Stores a list, and appends each argument value to the list.
162​ This is useful to allow an option to be specified multiple times.
163​- ```appendConst``` - Stores a list, and appends value, specified by the
164​ const keyword argument to the list. (Note, that the const keyword argument defaults
165​ is None.) The 'appendConst' action is typically used when multiple arguments need
166​ to store constants to the same list.
167​- ```count``` - Counts the number of times a keyword argument occurs. For example,
168​ used for increasing verbosity levels.
169​- ```help``` - Prints a complete help message for all the options in the current
170​ parser and then exits. By default a help action is automatically added to the parser.
171​ See ArgumentParser for details of how the output is created.
172​- ```version``` - Prints version information and exit. Expects a `version=`
173​ keyword argument in the addArgument() call.
174​
175​Details in [original action guide](http://docs.python.org/dev/library/argparse.html#action)
176​
177​
178​Sub-commands
179​============
180​
181​ArgumentParser.addSubparsers()
182​
183​Many programs split their functionality into a number of sub-commands, for
184​example, the svn program can invoke sub-commands like `svn checkout`, `svn update`,
185​and `svn commit`. Splitting up functionality this way can be a particularly good
186​idea when a program performs several different functions which require different
187​kinds of command-line arguments. `ArgumentParser` supports creation of such
188​sub-commands with `addSubparsers()` method. The `addSubparsers()` method is
189​normally called with no arguments and returns an special action object.
190​This object has a single method `addParser()`, which takes a command name and
191​any `ArgumentParser` constructor arguments, and returns an `ArgumentParser` object
192​that can be modified as usual.
193​
194​Example:
195​
196​sub_commands.js
197​```javascript
198​#!/usr/bin/env node
199​'use strict';
200​
201​var ArgumentParser = require('../lib/argparse').ArgumentParser;
202​var parser = new ArgumentParser({
203​ version: '0.0.1',
204​ addHelp:true,
205​ description: 'Argparse examples: sub-commands',
206​});
207​
208​var subparsers = parser.addSubparsers({
209​ title:'subcommands',
210​ dest:"subcommand_name"
211​});
212​
213​var bar = subparsers.addParser('c1', {addHelp:true});
214​bar.addArgument(
215​ [ '-f', '--foo' ],
216​ {
217​ action: 'store',
218​ help: 'foo3 bar3'
219​ }
220​);
221​var bar = subparsers.addParser(
222​ 'c2',
223​ {aliases:['co'], addHelp:true}
224​);
225​bar.addArgument(
226​ [ '-b', '--bar' ],
227​ {
228​ action: 'store',
229​ type: 'int',
230​ help: 'foo3 bar3'
231​ }
232​);
233​
234​var args = parser.parseArgs();
235​console.dir(args);
236​
237​```
238​
239​Details in [original sub-commands guide](http://docs.python.org/dev/library/argparse.html#sub-commands)
240​
241​
242​Contributors
243​============
244​
245​- [Eugene Shkuropat](https://github.com/shkuropat)
246​- [Paul Jacobson](https://github.com/hpaulj)
247​
248​[others](https://github.com/nodeca/argparse/graphs/contributors)
249​
250​License
251​=======
252​
253​Copyright (c) 2012 [Vitaly Puzrin](https://github.com/puzrin).
254​Released under the MIT license. See
255​[LICENSE](https://github.com/nodeca/argparse/blob/master/LICENSE) for details.
256​
257​