vnfmarket/src/main/webapp/vnfmarket/node_modules/commander/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('  - pineapple');
  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 pineapple
  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 ## .outputHelp()
 157
 158   Output help information without exiting.
 159
 160 ## .help()
 161
 162   Output help information and exit immediately.
 163
 164 ## Links
 165
 166  - [API documentation](http://visionmedia.github.com/commander.js/)
 167  - [ascii tables](https://github.com/LearnBoost/cli-table)
 168  - [progress bars](https://github.com/visionmedia/node-progress)
 169  - [more progress bars](https://github.com/substack/node-multimeter)
 170  - [examples](https://github.com/visionmedia/commander.js/tree/master/examples)
 171
 172 ## License
 173
 174 (The MIT License)
 175
 176 Copyright (c) 2011 TJ Holowaychuk &lt;tj@vision-media.ca&gt;
 177
 178 Permission is hereby granted, free of charge, to any person obtaining
 179 a copy of this software and associated documentation files (the
 180 'Software'), to deal in the Software without restriction, including
 181 without limitation the rights to use, copy, modify, merge, publish,
 182 distribute, sublicense, and/or sell copies of the Software, and to
 183 permit persons to whom the Software is furnished to do so, subject to
 184 the following conditions:
 185
 186 The above copyright notice and this permission notice shall be
 187 included in all copies or substantial portions of the Software.
 188
 189 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
 190 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 191 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 192 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 193 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 194 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 195 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.