Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 253 lines (172 sloc) 6.793 kb
12001ad @harthur argparse -> nomnom
authored
1 # nomnom
98697eb @harthur change parser options hash into chainable functions
authored
2 nomnom is an option parser for node and CommonJS. 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
5 var options = require("nomnom")
6 .opts({
7 version: {
8 string: '--version',
9 help: 'print version and exit',
10 callback: function() {
11 return "version 1.2.4";
12 }
13 },
14 debug : {
15 string: '-d, --debug',
16 help: 'Print debugging info'
17 },
18 config: {
19 string: '-c PATH, --config=PATH',
20 default: 'config.json',
21 help: 'JSON file with tests to run'
22 }
23 })
24 .parseArgs();
25
26 if(options.debug)
27 // do stuff
28 ```
f1b367b @harthur use getters
authored
29
98697eb @harthur change parser options hash into chainable functions
authored
30 You don't have to specify anything if you don't want to:
80a9cde @harthur readme mistakes
authored
31
18b15dc @harthur readme prettier
authored
32 ```javascript
33 var options = require("nomnom").parseArgs();
f1b367b @harthur use getters
authored
34
18b15dc @harthur readme prettier
authored
35 var url = options[0]; // get the first positional arg
36 var debug = options.debug // see if --debug was specified
37 var verbose = options.v // see if -v was specified
b25fde2 @harthur export an array of the positionals for more flexibility, like optimist
authored
38 var extras = options._ // get an array of the unmatched, positional args
18b15dc @harthur readme prettier
authored
39 ```
12001ad @harthur argparse -> nomnom
authored
40
ecdff84 @harthur move around README sections
authored
41 # Install
42 for [node.js](http://nodejs.org/) and [npm](http://github.com/isaacs/npm):
80a9cde @harthur readme mistakes
authored
43
a06da1a @harthur bump to v0.1.2, update about npm install
authored
44 npm install nomnom
ecdff84 @harthur move around README sections
authored
45
561de3c @harthur option can have a 'choices' list of possible values
authored
46 # More Details
47 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.
48
49 Values are JSON parsed, so `--debug=true --count=3 --file=log.txt` would give you:
50
51 ```
52 {
53 "debug": true,
54 "count": 3,
55 "file": "log.txt"
56 }
57 ```
58
59d4b91 @harthur add note about commands to readme
authored
59 # Commands
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
60 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
61
18b15dc @harthur readme prettier
authored
62 ```javascript
63 var parser = require("nomnom");
64
65 parser.command('browser')
66 .callback(runBrowser)
67 .help("run browser tests");
68
69 parser.command('sanity')
70 .opts({
71 filename: {
72 position: 1,
73 help: 'test file to run'
74 },
75 config: {
76 string: '-c FILE, --config=FILE',
77 default: 'config.json',
78 help: 'json file with tests to run'
79 }
80 })
81 .callback(function(options) {
82 runSanity(options.filename);
83 })
84 .help("run the sanity tests")
85
86 parser.parseArgs();
87 ```
88
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
89 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
90
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
91 # Usage
92 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
93
18b15dc @harthur readme prettier
authored
94 ```javascript
558d23a @harthur use scriptName() in readme usage example
authored
95 var options = require("nomnom")
96 .scriptName("runtests")
97 .opts({
98 path: {
99 position: 0,
100 help: "Test file to run",
101 list: true
102 },
103 config: {
104 string: '-c FILE, --config=FILE',
105 help: "Config file with tests to run",
106 },
107 debug: {
108 string: '-d, --debug',
109 help: "Print debugging info"
110 }
111 }).parseArgs();
18b15dc @harthur readme prettier
authored
112 ```
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
113
114 ...would look like this:
115
558d23a @harthur use scriptName() in readme usage example
authored
116 usage: runtests <path>... [options]
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
117
b7ab257 @harthur usage a bit prettier
authored
118 path Test file to run
119
120 options:
121 -c FILE, --config=FILE Config file with tests to run
122 -d, --debug Print debugging info
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
123
124 # Options hash
4950b10 @harthur add support for appending args and matching multiple positionals
authored
125 The options hash that is 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
126
127 #### string
128
129 specifies what command line arguments to match on and wether the option takes an argument.
130
131 To attach an option to `--version` use `"--version"`
132
133 To attach to `-v` or `--version` use `"-v, --version"`
134
135 To attach to `-c` and `--config` and require an argument use `"-c FILE, --config=FILE"`
136
137 The metavar (e.g. `"FILE"`) is just a guide and can be any string. Note that `string` will be used when printing the usage for this option.
138
139 #### help
140
141 A string description of the option for the usage printout.
142
143 #### default
144
145 The value to give the option if it's not specified in the arguments.
146
147 #### callback
148
149 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
150
18b15dc @harthur readme prettier
authored
151 ```javascript
152 var opts = {
153 count: {
154 string: '-n COUNT',
155 callback: function(count) {
156 if(count != parseInt(count))
157 return "count must be an integer";
158 }
159 }
160 }
161 ```
eeae52a @harthur add usage printing example to readme
authored
162
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
163 #### position
eeae52a @harthur add usage printing example to readme
authored
164
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
165 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`
166
4950b10 @harthur add support for appending args and matching multiple positionals
authored
167 #### list
168
169 Specifies that the option is a list. Appending can be achieved by specifying the arg more than once on the command line:
170
171 node test.js --file=test1.js --file=test2.js
172
f9604f8 @harthur "" satisfies required option
authored
173 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
174
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
175 #### required
176
177 If this is set to `true` and the option isn't in the args, a message will be printed and the program will exit.
178
561de3c @harthur option can have a 'choices' list of possible values
authored
179 #### choices
180
181 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.
182
c2a6080 @harthur add 'type' to option specs
authored
183 #### type
184
185 If you don't want the option JSON-parsed, specify type `"string"`.
186
c7dfc58 @harthur 'hidden' to hide option from usage
authored
187 #### hidden
188
189 Option won't be printed in the usage
190
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
191
192 # Parser interface
193 `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:
194
195 #### opts
196
197 The options hash.
198
199 #### usage
200
201 The string that will override the default generated usage message.
202
203 #### help
204
205 A string that is appended to the usage.
206
207 #### scriptName
208
209 Nomnom can't detect the alias used to run your script. You can use `scriptName` to provide the correct name instead of e.g. `node test.js`.
210
211 #### printFunc
212
18b15dc @harthur readme prettier
authored
213 Overrides the usage printing function.
98697eb @harthur change parser options hash into chainable functions
authored
214
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
215 #### command
98697eb @harthur change parser options hash into chainable functions
authored
216
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
217 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
218
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
219 #### callback
80a9cde @harthur readme mistakes
authored
220
18b15dc @harthur readme prettier
authored
221 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
222
223 #### globalOpts
224
225 The global options when commands are specified. Any options in here will be included in the usage string for any command.
226
227 #### parseArgs
228
229 Parses node's `process.argv` and returns the parsed options hash. You can also provide argv:
230
18b15dc @harthur readme prettier
authored
231 ```javascript
232 var options = nomnom.parseArgs(["-xvf", "--atomic=true"])
233 ```
0ab76da @harthur list all the options for the options hash, parser, and commands
authored
234
235 # Command interface
236 A command is specified with `nomnom.command('name')`. All these functions can be chained on a command:
237
238 #### opts
239
240 The options for this command.
241
242 #### callback
243
244 A callback that will be called with the parsed options when the command is used.
245
246 #### help
247
248 A help string describing the function of this command.
eeae52a @harthur add usage printing example to readme
authored
249
27687f0 @harthur add command.usage() for overriding a command's usage printout
authored
250 #### usage
251
252 Override the default generated usage string for this command.
Something went wrong with that request. Please try again.