Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 308 lines (214 sloc) 7.681 kB
12001ad @harthur argparse -> nomnom
authored
1 # nomnom
914dcba @harthur '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 @harthur initial argparse code plus README and package.json
authored
3
18b15dc @harthur readme prettier
authored
4 ```javascript
3f85d03 @harthur 'opts' -> 'options'
authored
5 var opts = require("nomnom")
ea9dca8 @harthur 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 @harthur fix up readme
authored
21 }
22 })
034e3f3 @harthur 'parseArgs' -> 'parse'
authored
23 .parse();
ebc17be @harthur fix up readme
authored
24
3f85d03 @harthur 'opts' -> 'options'
authored
25 if (opts.debug)
ebc17be @harthur fix up readme
authored
26 // do stuff
18b15dc @harthur readme prettier
authored
27 ```
f1b367b @harthur use getters
authored
28
98697eb @harthur change parser options hash into chainable functions
authored
29 You don't have to specify anything if you don't want to:
80a9cde @harthur readme mistakes
authored
30
18b15dc @harthur readme prettier
authored
31 ```javascript
3f85d03 @harthur 'opts' -> 'options'
authored
32 var opts = require("nomnom").parse();
f1b367b @harthur use getters
authored
33
3f85d03 @harthur '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 @harthur readme prettier
authored
38 ```
12001ad @harthur argparse -> nomnom
authored
39
ecdff84 @harthur move around README sections
authored
40 # Install
41 for [node.js](http://nodejs.org/) and [npm](http://github.com/isaacs/npm):
80a9cde @harthur readme mistakes
authored
42
a06da1a @harthur bump to v0.1.2, update about npm install
authored
43 npm install nomnom
ecdff84 @harthur move around README sections
authored
44
561de3c @harthur 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 @harthur fix up readme
authored
52 "debug": true,
53 "count": 3,
54 "file": "log.txt"
561de3c @harthur option can have a 'choices' list of possible values
authored
55 }
56 ```
57
59d4b91 @harthur add note about commands to readme
authored
58 # Commands
0ab76da @harthur 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 @harthur add note about commands to readme
authored
60
18b15dc @harthur readme prettier
authored
61 ```javascript
62 var parser = require("nomnom");
63
64 parser.command('browser')
ea9dca8 @harthur option() for adding single option spec
authored
65 .callback(function(opts) {
66 runBrowser(opts.url);
67 })
ebc17be @harthur fix up readme
authored
68 .help("run browser tests");
18b15dc @harthur readme prettier
authored
69
70 parser.command('sanity')
ea9dca8 @harthur option() for adding single option spec
authored
71 .option('outfile', {
72 abbr: 'o',
09b1bc4 @harthur some readme formatting
authored
73 help: "file to write results to"
ea9dca8 @harthur option() for adding single option spec
authored
74 })
75 .option('config', {
76 abbr: 'c',
77 default: 'config.json',
09b1bc4 @harthur some readme formatting
authored
78 help: "json manifest of tests to run"
ebc17be @harthur fix up readme
authored
79 })
3f85d03 @harthur 'opts' -> 'options'
authored
80 .callback(function(opts) {
81 runSanity(opts.filename);
ebc17be @harthur fix up readme
authored
82 })
83 .help("run the sanity tests")
18b15dc @harthur readme prettier
authored
84
034e3f3 @harthur 'parseArgs' -> 'parse'
authored
85 parser.parse();
18b15dc @harthur readme prettier
authored
86 ```
87
0ab76da @harthur 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 @harthur add note about commands to readme
authored
89
0ab76da @harthur 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 @harthur readme mistakes
authored
92
18b15dc @harthur readme prettier
authored
93 ```javascript
3f85d03 @harthur 'opts' -> 'options'
authored
94 var opts = require("nomnom")
1b4585c @harthur 'scriptName' -> 'script'
authored
95 .script("runtests")
3f85d03 @harthur 'opts' -> 'options'
authored
96 .options({
ebc17be @harthur 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 @harthur 'parseArgs' -> 'parse'
authored
112 }).parse();
18b15dc @harthur readme prettier
authored
113 ```
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
114
115 ...would look like this:
116
558d23a @harthur use scriptName() in readme usage example
authored
117 usage: runtests <path>... [options]
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
118
b7ab257 @harthur usage a bit prettier
authored
119 path Test file to run
120
121 options:
ebc17be @harthur fix up readme
authored
122 -c FILE, --config FILE Config file with tests to run
b7ab257 @harthur usage a bit prettier
authored
123 -d, --debug Print debugging info
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
124
ea9dca8 @harthur 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 @harthur list all the options for the options hash, parser, and commands
authored
127
914dcba @harthur '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 @harthur list all the options for the options hash, parser, and commands
authored
130
04ddc2a @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored
131 This option matches `-d` and `--debug` on the command line:
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
132
04ddc2a @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored
133 ```javascript
ea9dca8 @harthur option() for adding single option spec
authored
134 nomnom.option('debug', {
ebc17be @harthur fix up readme
authored
135 abbr: 'd'
ea9dca8 @harthur option() for adding single option spec
authored
136 })
04ddc2a @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored
137 ```
138
139 This option matches `-n 3`, `--num-lines 12` on the command line:
140
141 ```javascript
ea9dca8 @harthur option() for adding single option spec
authored
142 nomnom.option('numLines', {
04ddc2a @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored
143 abbr: 'n',
09b1bc4 @harthur some readme formatting
authored
144 full: 'num-lines'
ea9dca8 @harthur option() for adding single option spec
authored
145 })
04ddc2a @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored
146 ```
147
914dcba @harthur '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 @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored
151
152 ```javascript
ea9dca8 @harthur option() for adding single option spec
authored
153 nomnom.option('config', {
914dcba @harthur 'flag' field for option, option expects value by default
authored
154 flag: true
ea9dca8 @harthur option() for adding single option spec
authored
155 })
04ddc2a @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored
156 ```
157
09b1bc4 @harthur 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 @harthur '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 @harthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string'…
authored
164 #### string
165
914dcba @harthur '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 @harthur 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 @harthur an opt can specify a callback
authored
179
18b15dc @harthur readme prettier
authored
180 ```javascript
ea9dca8 @harthur option() for adding single option spec
authored
181 nomnom.option('count', {
ebc17be @harthur fix up readme
authored
182 callback: function(count) {
ea9dca8 @harthur option() for adding single option spec
authored
183 if (count != parseInt(count))
ebc17be @harthur fix up readme
authored
184 return "count must be an integer";
185 }
ea9dca8 @harthur option() for adding single option spec
authored
186 })
18b15dc @harthur readme prettier
authored
187 ```
eeae52a @harthur add usage printing example to readme
authored
188
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
189 #### position
eeae52a @harthur add usage printing example to readme
authored
190
914dcba @harthur '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 @harthur list all the options for the options hash, parser, and commands
authored
192
4950b10 @harthur 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 @harthur "" 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 @harthur add support for appending args and matching multiple positionals
authored
200
0ab76da @harthur 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 @harthur 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 @harthur add 'type' to option specs
authored
209 #### type
210
211 If you don't want the option JSON-parsed, specify type `"string"`.
212
c7dfc58 @harthur 'hidden' to hide option from usage
authored
213 #### hidden
214
215 Option won't be printed in the usage
216
0ab76da @harthur 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 @harthur 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 @harthur some readme formatting
authored
230 })
ea9dca8 @harthur option() for adding single option spec
authored
231 ```
232
3f85d03 @harthur 'opts' -> 'options'
authored
233 #### options
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
234
09b1bc4 @harthur 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 @harthur 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 @harthur 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 @harthur 'scriptName' -> 'script'
authored
258 #### script
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
259
1b4585c @harthur '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 @harthur list all the options for the options hash, parser, and commands
authored
261
c6f39f1 @harthur 'printFunc' -> printer
authored
262 #### printer
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
263
18b15dc @harthur readme prettier
authored
264 Overrides the usage printing function.
98697eb @harthur change parser options hash into chainable functions
authored
265
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
266 #### command
98697eb @harthur change parser options hash into chainable functions
authored
267
0ab76da @harthur 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 @harthur add usage printing example to readme
authored
269
02b62a5 @harthur replace globalOpts() and fallback callback() with nocommand()
authored
270 #### nocommand
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
271
02b62a5 @harthur replace globalOpts() and fallback callback() with nocommand()
authored
272 Gives a command object that will be used when no command is called.
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
273
034e3f3 @harthur 'parseArgs' -> 'parse'
authored
274 #### parse
0ab76da @harthur 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 @harthur readme prettier
authored
278 ```javascript
3f85d03 @harthur 'opts' -> 'options'
authored
279 var opts = nomnom.parse(["-xvf", "--atomic=true"])
18b15dc @harthur readme prettier
authored
280 ```
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
281
09b1bc4 @harthur some readme formatting
authored
282 #### nom
283
284 The same as `parse()`.
285
0ab76da @harthur 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 @harthur option() for adding single option spec
authored
289 #### option
290
291 Add an option specifically for this command.
292
3f85d03 @harthur 'opts' -> 'options'
authored
293 #### options
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
294
ea9dca8 @harthur option() for adding single option spec
authored
295 Add options for this command as a hash of options keyed by name.
0ab76da @harthur 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 @harthur add usage printing example to readme
authored
304
27687f0 @harthur 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.