Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 278 lines (191 sloc) 7.04 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
5 var options = require("nomnom")
ebc17be Heather Arthur fix up readme
authored
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 Heather Arthur readme prettier
authored
29 ```
f1b367b Heather Arthur use getters
authored
30
98697eb Heather Arthur change parser options hash into chainable functions
authored
31 You don't have to specify anything if you don't want to:
80a9cde Heather Arthur readme mistakes
authored
32
18b15dc Heather Arthur readme prettier
authored
33 ```javascript
34 var options = require("nomnom").parseArgs();
f1b367b Heather Arthur use getters
authored
35
ebc17be Heather Arthur fix up readme
authored
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 Heather Arthur readme prettier
authored
40 ```
12001ad Heather Arthur argparse -> nomnom
authored
41
ecdff84 Heather Arthur move around README sections
authored
42 # Install
43 for [node.js](http://nodejs.org/) and [npm](http://github.com/isaacs/npm):
80a9cde Heather Arthur readme mistakes
authored
44
a06da1a Heather Arthur bump to v0.1.2, update about npm install
authored
45 npm install nomnom
ecdff84 Heather Arthur move around README sections
authored
46
561de3c Heather Arthur option can have a 'choices' list of possible values
authored
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 Heather Arthur fix up readme
authored
54 "debug": true,
55 "count": 3,
56 "file": "log.txt"
561de3c Heather Arthur option can have a 'choices' list of possible values
authored
57 }
58 ```
59
59d4b91 Heather Arthur add note about commands to readme
authored
60 # Commands
0ab76da Heather Arthur list all the options for the options hash, parser, and commands
authored
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 Heather Arthur add note about commands to readme
authored
62
18b15dc Heather Arthur readme prettier
authored
63 ```javascript
64 var parser = require("nomnom");
65
66 parser.command('browser')
ebc17be Heather Arthur fix up readme
authored
67 .callback(runBrowser)
68 .help("run browser tests");
18b15dc Heather Arthur readme prettier
authored
69
70 parser.command('sanity')
ebc17be Heather Arthur fix up readme
authored
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 Heather Arthur readme prettier
authored
86
87 parser.parseArgs();
88 ```
89
0ab76da Heather Arthur list all the options for the options hash, parser, and commands
authored
90 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
91
0ab76da Heather Arthur list all the options for the options hash, parser, and commands
authored
92 # Usage
93 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
94
18b15dc Heather Arthur readme prettier
authored
95 ```javascript
558d23a Heather Arthur use scriptName() in readme usage example
authored
96 var options = require("nomnom")
ebc17be Heather Arthur fix up readme
authored
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 Heather Arthur readme prettier
authored
115 ```
0ab76da Heather Arthur list all the options for the options hash, parser, and commands
authored
116
117 ...would look like this:
118
558d23a Heather Arthur use scriptName() in readme usage example
authored
119 usage: runtests <path>... [options]
0ab76da Heather Arthur list all the options for the options hash, parser, and commands
authored
120
b7ab257 Heather Arthur usage a bit prettier
authored
121 path Test file to run
122
123 options:
ebc17be Heather Arthur fix up readme
authored
124 -c FILE, --config FILE Config file with tests to run
b7ab257 Heather Arthur usage a bit prettier
authored
125 -d, --debug Print debugging info
0ab76da Heather Arthur list all the options for the options hash, parser, and commands
authored
126
127 # Options hash
ebc17be Heather Arthur fix up readme
authored
128 The options hash passed to `nomnom.opts()` is 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
129
914dcba Heather Arthur 'flag' field for option, option expects value by default
authored
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 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 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
134
04ddc2a Heather Arthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string', f...
authored
135 ```javascript
136 debug: {
ebc17be Heather Arthur fix up readme
authored
137 abbr: 'd'
04ddc2a Heather Arthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string', f...
authored
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 Heather Arthur 'flag' field for option, option expects value by default
authored
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 Heather Arthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string', f...
authored
153
154 ```javascript
914dcba Heather Arthur 'flag' field for option, option expects value by default
authored
155 config: {
156 flag: true
04ddc2a Heather Arthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string', f...
authored
157 }
158 ```
159
914dcba Heather Arthur 'flag' field for option, option expects value by default
authored
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 Heather Arthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string', f...
authored
166 #### string
167
914dcba Heather Arthur 'flag' field for option, option expects value by default
authored
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 Heather Arthur list all the options for the options hash, parser, and commands
authored
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 Heather Arthur an opt can specify a callback
authored
181
18b15dc Heather Arthur readme prettier
authored
182 ```javascript
04ddc2a Heather Arthur highlight 'abbr', 'full', and 'metavar' in readme instead of 'string', f...
authored
183
184 count: {
ebc17be Heather Arthur fix up readme
authored
185 callback: function(count) {
186 if (count != parseInt(count))
187 return "count must be an integer";
188 }
18b15dc Heather Arthur readme prettier
authored
189 }
190 ```
eeae52a Heather Arthur add usage printing example to readme
authored
191
0ab76da Heather Arthur list all the options for the options hash, parser, and commands
authored
192 #### position
eeae52a Heather Arthur add usage printing example to readme
authored
193
914dcba Heather Arthur 'flag' field for option, option expects value by default
authored
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 Heather Arthur list all the options for the options hash, parser, and commands
authored
195
4950b10 Heather Arthur add support for appending args and matching multiple positionals
authored
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 Heather Arthur "" satisfies required option
authored
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 Heather Arthur add support for appending args and matching multiple positionals
authored
203
0ab76da Heather Arthur list all the options for the options hash, parser, and commands
authored
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 Heather Arthur option can have a 'choices' list of possible values
authored
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 Heather Arthur add 'type' to option specs
authored
212 #### type
213
214 If you don't want the option JSON-parsed, specify type `"string"`.
215
c7dfc58 Heather Arthur 'hidden' to hide option from usage
authored
216 #### hidden
217
218 Option won't be printed in the usage
219
0ab76da Heather Arthur list all the options for the options hash, parser, and commands
authored
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 Heather Arthur fix up readme
authored
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 Heather Arthur list all the options for the options hash, parser, and commands
authored
239
c6f39f1 Heather Arthur 'printFunc' -> printer
authored
240 #### printer
0ab76da Heather Arthur list all the options for the options hash, parser, and commands
authored
241
18b15dc Heather Arthur readme prettier
authored
242 Overrides the usage printing function.
98697eb Heather Arthur change parser options hash into chainable functions
authored
243
0ab76da Heather Arthur list all the options for the options hash, parser, and commands
authored
244 #### command
98697eb Heather Arthur change parser options hash into chainable functions
authored
245
0ab76da Heather Arthur list all the options for the options hash, parser, and commands
authored
246 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
247
02b62a5 Heather Arthur replace globalOpts() and fallback callback() with nocommand()
authored
248 #### nocommand
0ab76da Heather Arthur list all the options for the options hash, parser, and commands
authored
249
02b62a5 Heather Arthur replace globalOpts() and fallback callback() with nocommand()
authored
250 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
251
252 #### parseArgs
253
254 Parses node's `process.argv` and returns the parsed options hash. You can also provide argv:
255
18b15dc Heather Arthur readme prettier
authored
256 ```javascript
257 var options = nomnom.parseArgs(["-xvf", "--atomic=true"])
258 ```
0ab76da Heather Arthur list all the options for the options hash, parser, and commands
authored
259
260 # Command interface
261 A command is specified with `nomnom.command('name')`. All these functions can be chained on a command:
262
263 #### opts
264
265 The options for this command.
266
267 #### callback
268
269 A callback that will be called with the parsed options when the command is used.
270
271 #### help
272
273 A help string describing the function of this command.
eeae52a Heather Arthur add usage printing example to readme
authored
274
27687f0 Heather Arthur add command.usage() for overriding a command's usage printout
authored
275 #### usage
276
277 Override the default generated usage string for this command.
Something went wrong with that request. Please try again.