Skip to content
Newer
Older
100644 282 lines (193 sloc) 7.08 KB
12001ad @harthur argparse -> nomnom
authored Aug 25, 2010
1 # nomnom
914dcba @harthur 'flag' field for option, option expects value by default
authored Aug 6, 2011
2 nomnom is an option parser for node. It noms your args and gives them back to you in a hash.
0a310cc @harthur initial argparse code plus README and package.json
authored Aug 20, 2010
3
18b15dc @harthur readme prettier
authored Jun 13, 2011
4 ```javascript
5 var options = require("nomnom")
ebc17be @harthur fix up readme
authored Aug 6, 2011
6 .opts({
7 debug : {
8 abbr: 'd',
9 flag: true,
10 help: 'Print debugging info'
11 },
12 config: {
13 abbr: 'c',
14 default: 'config.json',
15 help: 'JSON file with tests to run'
16 },
17 version: {
18 flag: true,
19 help: 'print version and exit',
20 callback: function() {
21 return "version 1.2.4";
22 }
23 }
24 })
25 .parseArgs();
26
27 if (options.debug)
28 // do stuff
18b15dc @harthur readme prettier
authored Jun 13, 2011
29 ```
f1b367b @harthur use getters
authored Oct 15, 2010
30
98697eb @harthur change parser options hash into chainable functions
authored Apr 15, 2011
31 You don't have to specify anything if you don't want to:
80a9cde @harthur readme mistakes
authored Apr 15, 2011
32
18b15dc @harthur readme prettier
authored Jun 13, 2011
33 ```javascript
34 var options = require("nomnom").parseArgs();
f1b367b @harthur use getters
authored Oct 15, 2010
35
ebc17be @harthur fix up readme
authored Aug 7, 2011
36 var url = options[0]; // get the first positional arg
37 var file = options.file // see if --file was specified
38 var verbose = options.v // see if -v was specified
39 var extras = options._ // get an array of the unmatched, positional args
18b15dc @harthur readme prettier
authored Jun 13, 2011
40 ```
12001ad @harthur argparse -> nomnom
authored Aug 25, 2010
41
ecdff84 @harthur move around README sections
authored Aug 24, 2010
42 # Install
43 for [node.js](http://nodejs.org/) and [npm](http://github.com/isaacs/npm):
80a9cde @harthur readme mistakes
authored Apr 15, 2011
44
a06da1a @harthur bump to v0.1.2, update about npm install
authored Oct 15, 2010
45 npm install nomnom
ecdff84 @harthur move around README sections
authored Aug 24, 2010
46
561de3c @harthur option can have a 'choices' list of possible values
authored Jun 27, 2011
47 # More Details
48 Nomnom supports args like `-d`, `--debug`, `--no-debug`, `--file=test.txt`, `--file test.txt`, `-f test.txt`, `-xvf`, and positionals. Positionals are arguments that don't fit the `-a` or `--atomic` format and aren't attached to an option.
49
50 Values are JSON parsed, so `--debug=true --count=3 --file=log.txt` would give you:
51
52 ```
53 {
ebc17be @harthur fix up readme
authored Aug 7, 2011
54 "debug": true,
55 "count": 3,
56 "file": "log.txt"
561de3c @harthur option can have a 'choices' list of possible values
authored Jun 27, 2011
57 }
58 ```
59
59d4b91 @harthur add note about commands to readme
authored Apr 15, 2011
60 # Commands
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
61 Nomnom supports command-based interfaces (e.g. with git: `git add -p` and `git rebase -i` where `add` and `rebase` are the commands):
59d4b91 @harthur add note about commands to readme
authored Apr 15, 2011
62
18b15dc @harthur readme prettier
authored Jun 13, 2011
63 ```javascript
64 var parser = require("nomnom");
65
66 parser.command('browser')
ebc17be @harthur fix up readme
authored Aug 7, 2011
67 .callback(runBrowser)
68 .help("run browser tests");
18b15dc @harthur readme prettier
authored Jun 13, 2011
69
70 parser.command('sanity')
ebc17be @harthur fix up readme
authored Aug 7, 2011
71 .opts({
72 outfile: {
73 abbr: 'o',
74 help: 'file to write results to'
75 },
76 config: {
77 abbr: 'c',
78 default: 'config.json',
79 help: 'json manifest of tests to run'
80 }
81 })
82 .callback(function(options) {
83 runSanity(options.filename);
84 })
85 .help("run the sanity tests")
18b15dc @harthur readme prettier
authored Jun 13, 2011
86
87 parser.parseArgs();
88 ```
89
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
90 Each command generates its own usage message when `-h` or `--help` is specified with the command.
59d4b91 @harthur add note about commands to readme
authored Apr 15, 2011
91
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
92 # Usage
93 Nomnom prints out a usage message if `--help` or `-h` is an argument. Usage for these options in `test.js`:
80a9cde @harthur readme mistakes
authored Apr 15, 2011
94
18b15dc @harthur readme prettier
authored Jun 13, 2011
95 ```javascript
558d23a @harthur use scriptName() in readme usage example
authored Jun 19, 2011
96 var options = require("nomnom")
ebc17be @harthur fix up readme
authored Aug 7, 2011
97 .scriptName("runtests")
98 .opts({
99 path: {
100 position: 0,
101 help: "Test file to run",
102 list: true
103 },
104 config: {
105 abbr: 'c',
106 metavar: 'FILE',
107 help: "Config file with tests to run"
108 },
109 debug: {
110 abbr: 'd',
111 flag: true,
112 help: "Print debugging info"
113 }
114 }).parseArgs();
18b15dc @harthur readme prettier
authored Jun 13, 2011
115 ```
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
116
117 ...would look like this:
118
558d23a @harthur use scriptName() in readme usage example
authored Jun 19, 2011
119 usage: runtests <path>... [options]
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
120
b7ab257 @harthur usage a bit prettier
authored Jun 13, 2011
121 path Test file to run
122
123 options:
ebc17be @harthur fix up readme
authored Aug 7, 2011
124 -c FILE, --config FILE Config file with tests to run
b7ab257 @harthur usage a bit prettier
authored Jun 13, 2011
125 -d, --debug Print debugging info
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
126
127 # Options hash
ebc17be @harthur fix up readme
authored Aug 7, 2011
128 The options hash passed to `nomnom.opts()` is a hash keyed on option name. Each option specification can have the following fields:
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
129
914dcba @harthur 'flag' field for option, option expects value by default
authored Aug 6, 2011
130 #### abbr and full
131 `abbr` is the single character string to match to this option, `full` is the full-length string (defaults to the name of the option).
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
132
04ddc2a @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored Jul 17, 2011
133 This option matches `-d` and `--debug` on the command line:
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
134
04ddc2a @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored Jul 18, 2011
135 ```javascript
136 debug: {
ebc17be @harthur fix up readme
authored Aug 7, 2011
137 abbr: 'd'
04ddc2a @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored Jul 18, 2011
138 }
139 ```
140
141 This option matches `-n 3`, `--num-lines 12` on the command line:
142
143 ```javascript
144 numLines: {
145 abbr: 'n',
146 full: 'num-lines',
147 }
148 ```
149
914dcba @harthur 'flag' field for option, option expects value by default
authored Aug 6, 2011
150 #### flag
151
152 If this is set to true, the option acts as a flag and doesn't swallow the next value on the command line. Default is `false`, so normally if you had a command line `--config test.js`, `config` would get a value of `test.js` in the options hash. Whereas if you specify:
04ddc2a @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored Jul 18, 2011
153
154 ```javascript
914dcba @harthur 'flag' field for option, option expects value by default
authored Aug 6, 2011
155 config: {
156 flag: true
04ddc2a @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored Jul 18, 2011
157 }
158 ```
159
914dcba @harthur 'flag' field for option, option expects value by default
authored Aug 6, 2011
160 with a command line of `--config test.js`, `config` would get a value of `true` in the options hash, and `test.js` would be a free positional arg.
161
162 #### metavar
163
164 `metavar` is used in the usage printout e.g. `"PATH"` in `"-f PATH, --file PATH"`.
165
04ddc2a @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored Jul 18, 2011
166 #### string
167
914dcba @harthur 'flag' field for option, option expects value by default
authored Aug 6, 2011
168 A shorthand for `abbr`, `full`, and `metavar`. For example, to attach an option to `-c` and `--config` use a `string: "-c FILE, --config=FILE"`
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
169
170 #### help
171
172 A string description of the option for the usage printout.
173
174 #### default
175
176 The value to give the option if it's not specified in the arguments.
177
178 #### callback
179
180 A callback that will be executed as soon as the option is encountered. If the callback returns a string it will print the string and exit:
8293e17 @harthur an opt can specify a callback
authored Apr 18, 2011
181
18b15dc @harthur readme prettier
authored Jun 13, 2011
182 ```javascript
04ddc2a @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored Jul 18, 2011
183
184 count: {
ebc17be @harthur fix up readme
authored Aug 7, 2011
185 callback: function(count) {
186 if (count != parseInt(count))
187 return "count must be an integer";
188 }
18b15dc @harthur readme prettier
authored Jun 13, 2011
189 }
190 ```
eeae52a @harthur add usage printing example to readme
authored Apr 8, 2011
191
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
192 #### position
eeae52a @harthur add usage printing example to readme
authored Apr 8, 2011
193
914dcba @harthur 'flag' field for option, option expects value by default
authored Aug 6, 2011
194 The position of the option if it's a positional argument. If the option should be matched to the first positional arg use position `0`, etc.
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
195
4950b10 @harthur add support for appending args and matching multiple positionals
authored May 31, 2011
196 #### list
197
198 Specifies that the option is a list. Appending can be achieved by specifying the arg more than once on the command line:
199
200 node test.js --file=test1.js --file=test2.js
201
f9604f8 @harthur "" satisfies required option
authored Jun 3, 2011
202 If the option has a `position` and `list` is `true`, all positional args including and after `position` will be appended to the array.
4950b10 @harthur add support for appending args and matching multiple positionals
authored May 31, 2011
203
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
204 #### required
205
206 If this is set to `true` and the option isn't in the args, a message will be printed and the program will exit.
207
561de3c @harthur option can have a 'choices' list of possible values
authored Jun 27, 2011
208 #### choices
209
210 A list of the possible values for the option (e.g. `['run', 'test', 'open']`). If the parsed value isn't in the list a message will be printed and the program will exit.
211
c2a6080 @harthur add 'type' to option specs
authored Jun 26, 2011
212 #### type
213
214 If you don't want the option JSON-parsed, specify type `"string"`.
215
c7dfc58 @harthur 'hidden' to hide option from usage
authored Jun 4, 2011
216 #### hidden
217
218 Option won't be printed in the usage
219
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
220
221 # Parser interface
222 `require("nomnom")` will give you the option parser. You can also make an instance of a parser with `require("nomnom")()`. You can chain any of these functions off of a parser:
223
224 #### opts
225
226 The options hash.
227
228 #### usage
229
230 The string that will override the default generated usage message.
231
232 #### help
233
234 A string that is appended to the usage.
235
236 #### scriptName
237
ebc17be @harthur fix up readme
authored Aug 7, 2011
238 Nomnom can't detect the alias used to run your script. You can use `scriptName` to provide the correct name for the usage printout instead of e.g. `node test.js`.
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
239
240 #### printFunc
241
18b15dc @harthur readme prettier
authored Jun 13, 2011
242 Overrides the usage printing function.
98697eb @harthur change parser options hash into chainable functions
authored Apr 15, 2011
243
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
244 #### command
98697eb @harthur change parser options hash into chainable functions
authored Apr 15, 2011
245
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
246 Takes a command name and gives you a command object on which you can chain command options.
eeae52a @harthur add usage printing example to readme
authored Apr 8, 2011
247
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
248 #### callback
80a9cde @harthur readme mistakes
authored Apr 15, 2011
249
18b15dc @harthur readme prettier
authored Jun 13, 2011
250 A callback that will be called with the parsed options. If a command is expected, this is the fallback callback when no command is specified.
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
251
252 #### globalOpts
253
254 The global options when commands are specified. Any options in here will be included in the usage string for any command.
255
256 #### parseArgs
257
258 Parses node's `process.argv` and returns the parsed options hash. You can also provide argv:
259
18b15dc @harthur readme prettier
authored Jun 13, 2011
260 ```javascript
261 var options = nomnom.parseArgs(["-xvf", "--atomic=true"])
262 ```
0ab76da @harthur list all the options for the options hash, parser, and commands
authored May 25, 2011
263
264 # Command interface
265 A command is specified with `nomnom.command('name')`. All these functions can be chained on a command:
266
267 #### opts
268
269 The options for this command.
270
271 #### callback
272
273 A callback that will be called with the parsed options when the command is used.
274
275 #### help
276
277 A help string describing the function of this command.
eeae52a @harthur add usage printing example to readme
authored Apr 8, 2011
278
27687f0 @harthur add command.usage() for overriding a command's usage printout
authored Jun 13, 2011
279 #### usage
280
281 Override the default generated usage string for this command.
Something went wrong with that request. Please try again.