Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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