/node_modules/jade/node_modules/commander/Readme.md
Markdown | 262 lines | 191 code | 71 blank | 0 comment | 0 complexity | 35ee620e140c71ee841de61d4a481f62 MD5 | raw file
Possible License(s): Apache-2.0, MIT
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 [](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 22var program = require('commander'); 23 24program 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 32console.log('you ordered a pizza with:'); 33if (program.peppers) console.log(' - peppers'); 34if (program.pineapple) console.log(' - pineappe'); 35if (program.bbq) console.log(' - bbq'); 36console.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 64function range(val) { 65 return val.split('..').map(Number); 66} 67 68function list(val) { 69 return val.split(','); 70} 71 72program 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 82console.log(' int: %j', program.integer); 83console.log(' float: %j', program.float); 84console.log(' optional: %j', program.optional); 85program.range = program.range || []; 86console.log(' range: %j..%j', program.range[0], program.range[1]); 87console.log(' list: %j', program.list); 88console.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 107var program = require('../'); 108 109function list(val) { 110 return val.split(',').map(Number); 111} 112 113program 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 122program.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 130program.parse(process.argv); 131 132console.log('stuff'); 133``` 134 135yielding the following help output: 136 137``` 138 139Usage: custom-help [options] 140 141Options: 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 149Examples: 150 151 $ custom-help --help 152 $ custom-help -h 153 154``` 155 156## .prompt(msg, fn) 157 158 Single-line prompt: 159 160```js 161program.prompt('name: ', function(name){ 162 console.log('hi %s', name); 163}); 164``` 165 166 Multi-line prompt: 167 168```js 169program.prompt('description:', function(name){ 170 console.log('hi %s', name); 171}); 172``` 173 174 Coercion: 175 176```js 177program.prompt('Age: ', Number, function(age){ 178 console.log('age: %j', age); 179}); 180``` 181 182```js 183program.prompt('Birthdate: ', Date, function(date){ 184 console.log('date: %s', date); 185}); 186``` 187 188## .password(msg[, mask], fn) 189 190Prompt for password without echoing: 191 192```js 193program.password('Password: ', function(pass){ 194 console.log('got "%s"', pass); 195 process.stdin.destroy(); 196}); 197``` 198 199Prompt for password with mask char "*": 200 201```js 202program.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 213program.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 223var list = ['tobi', 'loki', 'jane', 'manny', 'luna']; 224 225console.log('Choose the coolest pet:'); 226program.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 243Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca> 244 245Permission is hereby granted, free of charge, to any person obtaining 246a copy of this software and associated documentation files (the 247'Software'), to deal in the Software without restriction, including 248without limitation the rights to use, copy, modify, merge, publish, 249distribute, sublicense, and/or sell copies of the Software, and to 250permit persons to whom the Software is furnished to do so, subject to 251the following conditions: 252 253The above copyright notice and this permission notice shall be 254included in all copies or substantial portions of the Software. 255 256THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, 257EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 258MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 259IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 260CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 261TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 262SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.