commander @ 1.0.0 - Readme.md
1
# Commander.js
2
3
The complete solution for [node.js](http://nodejs.org) command-line interfaces, inspired by Ruby's [commander](https://github.com/visionmedia/commander).
4
5
[![Build Status](https://secure.travis-ci.org/visionmedia/commander.js.png)](http://travis-ci.org/visionmedia/commander.js)
6
7
## Installation
8
9
$ npm install commander
10
11
## Option parsing
12
13
Options with commander are defined with the `.option()` method, also serving as documentation for the options. The example below parses args and options from `process.argv`, leaving remaining args as the `program.args` array which were not consumed by options.
14
15
```js
16
#!/usr/bin/env node
17
18
/**
19
* Module dependencies.
20
*/
21
22
var program = require('commander');
23
24
program
25
.version('0.0.1')
26
.option('-p, --peppers', 'Add peppers')
27
.option('-P, --pineapple', 'Add pineapple')
28
.option('-b, --bbq', 'Add bbq sauce')
29
.option('-c, --cheese [type]', 'Add the specified type of cheese [marble]', 'marble')
30
.parse(process.argv);
31
32
console.log('you ordered a pizza with:');
33
if (program.peppers) console.log(' - peppers');
34
if (program.pineapple) console.log(' - pineappe');
35
if (program.bbq) console.log(' - bbq');
36
console.log(' - %s cheese', program.cheese);
37
```
38
39
Short flags may be passed as a single arg, for example `-abc` is equivalent to `-a -b -c`. Multi-word options such as "--template-engine" are camel-cased, becoming `program.templateEngine` etc.
40
41
## Automated --help
42
43
The help information is auto-generated based on the information commander already knows about your program, so the following `--help` info is for free:
44
45
```
46
$ ./examples/pizza --help
47
48
Usage: pizza [options]
49
50
Options:
51
52
-V, --version output the version number
53
-p, --peppers Add peppers
54
-P, --pineapple Add pineappe
55
-b, --bbq Add bbq sauce
56
-c, --cheese <type> Add the specified type of cheese [marble]
57
-h, --help output usage information
58
59
```
60
61
## Coercion
62
63
```js
64
function range(val) {
65
return val.split('..').map(Number);
66
}
67
68
function list(val) {
69
return val.split(',');
70
}
71
72
program
73
.version('0.0.1')
74
.usage('[options] <file ...>')
75
.option('-i, --integer <n>', 'An integer argument', parseInt)
76
.option('-f, --float <n>', 'A float argument', parseFloat)
77
.option('-r, --range <a>..<b>', 'A range', range)
78
.option('-l, --list <items>', 'A list', list)
79
.option('-o, --optional [value]', 'An optional value')
80
.parse(process.argv);
81
82
console.log(' int: %j', program.integer);
83
console.log(' float: %j', program.float);
84
console.log(' optional: %j', program.optional);
85
program.range = program.range || [];
86
console.log(' range: %j..%j', program.range[0], program.range[1]);
87
console.log(' list: %j', program.list);
88
console.log(' args: %j', program.args);
89
```
90
91
## Custom help
92
93
You can display arbitrary `-h, --help` information
94
by listening for "--help". Commander will automatically
95
exit once you are done so that the remainder of your program
96
does not execute causing undesired behaviours, for example
97
in the following executable "stuff" will not output when
98
`--help` is used.
99
100
```js
101
#!/usr/bin/env node
102
103
/**
104
* Module dependencies.
105
*/
106
107
var program = require('../');
108
109
function list(val) {
110
return val.split(',').map(Number);
111
}
112
113
program
114
.version('0.0.1')
115
.option('-f, --foo', 'enable some foo')
116
.option('-b, --bar', 'enable some bar')
117
.option('-B, --baz', 'enable some baz');
118
119
// must be before .parse() since
120
// node's emit() is immediate
121
122
program.on('--help', function(){
123
console.log(' Examples:');
124
console.log('');
125
console.log(' $ custom-help --help');
126
console.log(' $ custom-help -h');
127
console.log('');
128
});
129
130
program.parse(process.argv);
131
132
console.log('stuff');
133
```
134
135
yielding the following help output:
136
137
```
138
139
Usage: custom-help [options]
140
141
Options:
142
143
-h, --help output usage information
144
-V, --version output the version number
145
-f, --foo enable some foo
146
-b, --bar enable some bar
147
-B, --baz enable some baz
148
149
Examples:
150
151
$ custom-help --help
152
$ custom-help -h
153
154
```
155
156
## .prompt(msg, fn)
157
158
Single-line prompt:
159
160
```js
161
program.prompt('name: ', function(name){
162
console.log('hi %s', name);
163
});
164
```
165
166
Multi-line prompt:
167
168
```js
169
program.prompt('description:', function(name){
170
console.log('hi %s', name);
171
});
172
```
173
174
Coercion:
175
176
```js
177
program.prompt('Age: ', Number, function(age){
178
console.log('age: %j', age);
179
});
180
```
181
182
```js
183
program.prompt('Birthdate: ', Date, function(date){
184
console.log('date: %s', date);
185
});
186
```
187
188
## .password(msg[, mask], fn)
189
190
Prompt for password without echoing:
191
192
```js
193
program.password('Password: ', function(pass){
194
console.log('got "%s"', pass);
195
process.stdin.destroy();
196
});
197
```
198
199
Prompt for password with mask char "*":
200
201
```js
202
program.password('Password: ', '*', function(pass){
203
console.log('got "%s"', pass);
204
process.stdin.destroy();
205
});
206
```
207
208
## .confirm(msg, fn)
209
210
Confirm with the given `msg`:
211
212
```js
213
program.confirm('continue? ', function(ok){
214
console.log(' got %j', ok);
215
});
216
```
217
218
## .choose(list, fn)
219
220
Let the user choose from a `list`:
221
222
```js
223
var list = ['tobi', 'loki', 'jane', 'manny', 'luna'];
224
225
console.log('Choose the coolest pet:');
226
program.choose(list, function(i){
227
console.log('you chose %d "%s"', i, list[i]);
228
});
229
```
230
231
## Links
232
233
- [API documentation](http://visionmedia.github.com/commander.js/)
234
- [ascii tables](https://github.com/LearnBoost/cli-table)
235
- [progress bars](https://github.com/visionmedia/node-progress)
236
- [more progress bars](https://github.com/substack/node-multimeter)
237
- [examples](https://github.com/visionmedia/commander.js/tree/master/examples)
238
239
## License
240
241
(The MIT License)
242
243
Copyright (c) 2011 TJ Holowaychuk &lt;tj@vision-media.ca&gt;
244
245
Permission is hereby granted, free of charge, to any person obtaining
246
a copy of this software and associated documentation files (the
247
'Software'), to deal in the Software without restriction, including
248
without limitation the rights to use, copy, modify, merge, publish,
249
distribute, sublicense, and/or sell copies of the Software, and to
250
permit persons to whom the Software is furnished to do so, subject to
251
the following conditions:
252
253
The above copyright notice and this permission notice shall be
254
included in all copies or substantial portions of the Software.
255
256
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
257
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
258
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
259
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
260
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
261
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
262
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.