vnfmarket/src/main/webapp/vnfmarket/node_modules/optionator/README.md

   1 # Optionator
   2 <a name="optionator" />
   3
   4 Optionator is an option parsing and help generation library.
   5
   6 ## Why?
   7 The  problem with other option parsers, such as `yargs` or `minimist`, is they just accept all input, valid or not.
   8 With Optionator, if you mistype an option, it will give you an error (with a suggestion for what you meant).
   9 If you give the wrong type of argument for an option, it will give you an error rather than supplying the wrong input to your application.
  10
  11     $ cmd --halp
  12     Invalid option '--halp' - perhaps you meant '--help'?
  13
  14     $ cmd --count str
  15     Invalid value for option 'count' - expected type Int, received value: str.
  16
  17 Over helpful features include reformatting the help text based on the size of the console, so that it fits even if the console is narrow, and accepting not just an array (eg. process.argv), but a string or object as well, making things like testing much easier.
  18
  19 ## About
  20 Optionator uses [type-check](https://github.com/gkz/type-check) and [levn](https://github.com/gkz/levn) behind the scenes to cast and verify input according the specified types.
  21
  22 Optionator is used by [Grasp](http://graspjs.com), [eslint](http://eslint.org), [LiveScript](http://livescript.net), [esmangle](https://github.com/estools/esmangle), [escodegen](https://github.com/estools/escodegen), and more.
  23
  24 MIT license. Version 0.5.0
  25
  26     npm install optionator
  27
  28 For updates on Optionator, [follow me on twitter](https://twitter.com/gkzahariev).
  29
  30 ## Usage
  31 `require('optionator');` returns a function. It has one property, `VERSION`, the current version of the library as a string. This function is called with an object specifying your options and other information, see the [settings format section](#settings-format). This in turn returns an object with three properties, `parse`, `generateHelp`, and `generateHelpForOption`, which are all functions.
  32
  33 ```js
  34 var optionator = require('optionator')({
  35   prepend: 'Usage: cmd [options]',
  36   append: 'Version 1.0.0',
  37   options: [{
  38     option: 'help',
  39     alias: 'h',
  40     type: 'Boolean',
  41     description: 'displays help'
  42   }, {
  43     option: 'count',
  44     alias: 'c',
  45     type: 'Int',
  46     description: 'number of things',
  47     example: 'cmd --count 2'
  48   }]
  49 });
  50 ```
  51
  52 ### parse(input, parseOptions)
  53 `parse` processes the `input` according to your settings, and returns an object with the results.
  54
  55 ##### arguments
  56 * input - `[String] | Object | String` - the input you wish to parse
  57 * parseOptions - `{slice: Int}` - all options optional
  58     - `slice` specifies how much to slice away from the beginning if the input is an array or string - by default `0` for string, `2` for array (works with `process.argv`)
  59
  60 ##### returns
  61 `Object` - the parsed options, each key is a camelCase version of the option name (specified in dash-case), and each value is the processed value for that option. Positional values are in an array under the `_` key.
  62
  63 ##### example
  64 ```js
  65 parse(['node', 't.js', '--count', '2', 'positional']); // {count: 2, _: ['positional']}
  66 parse('--count 2 positional');                         // {count: 2, _: ['positional']}
  67 parse({count: 2, _:['positional']});                   // {count: 2, _: ['positional']}
  68 ```
  69
  70 ### generateHelp(helpOptions)
  71 `generateHelp` produces help text based on your settings.
  72
  73 ##### arguments
  74 * helpOptions - `{showHidden: Boolean, interpolate: Object}` - all options optional
  75     - `showHidden` specifies whether to show options with `hidden: true` specified, by default it is `false`
  76     - `interpolate` specify data to be interpolated in `prepend` and `append` text, `{{key}}` is the format - eg. `generateHelp({interpolate:{version: '0.4.2'}})`, will change this `append` text: `Version {{version}}` to `Version 0.4.2`
  77
  78 ##### returns
  79 `String` - the generated help text
  80
  81 ##### example
  82 ```js
  83 generateHelp(); /*
  84 "Usage: cmd [options] positional
  85
  86   -h, --help       displays help
  87   -c, --count Int  number of things
  88
  89 Version  1.0.0
  90 "*/
  91 ```
  92
  93 ### generateHelpForOption(optionName)
  94 `generateHelpForOption` produces expanded help text for the specified with `optionName` option. If an `example` was specified for the option, it will be displayed,  and if a `longDescription` was specified, it will display that instead of the `description`.
  95
  96 ##### arguments
  97 * optionName - `String` - the name of the option to display
  98
  99 ##### returns
 100 `String` - the generated help text for the option
 101
 102 ##### example
 103 ```js
 104 generateHelpForOption('count'); /*
 105 "-c, --count Int
 106 description: number of things
 107 example: cmd --count 2
 108 "*/
 109 ```
 110
 111 ## Settings Format
 112 When your `require('optionator')`, you get a function that takes in a settings object. This object has the type:
 113
 114     {
 115       prepend: Maybe String,
 116       append: Maybe String,
 117       options: [{heading: String} | {
 118         option: String,
 119         alias: Maybe [String] | String,
 120         type: Maybe String,
 121         enum: Maybe [String],
 122         default: Maybe String,
 123         restPositional: Maybe Boolean,
 124         requried: Maybe Boolean,
 125         overrideRequired: Maybe Bookean,
 126         dependsOn: Maybe [String] | String,
 127         description: Maybe String,
 128         longDescription: Maybe String,
 129         example: Maybe [String] | String
 130       }],
 131       helpStyle: Maybe {
 132         aliasSeparator: Maybe String,
 133         typeSeparator: Maybe String,
 134         descriptionSeparator: Maybe String,
 135         initialIndent: Maybe Int,
 136         secondaryIndent: Maybe Int,
 137         maxPadFactor: Maybe Number
 138       },
 139       mutuallyExclusive: Maybe [[String | [String]]],
 140       concatRepeatedArrays: Maybe Boolean,
 141       mergeRepeatedObjects: Maybe Boolean
 142     }
 143
 144 ### Top Level Properties
 145 * `prepend` is an optional string to be placed before the options in the help text
 146 * `append` is an optional string to be placed after the options in the help text
 147 * `options` is a required array specifying your options and headings, the options and headings will be displayed in the order specified
 148 * `helpStyle` is an optional object which enables you to change the default appearance of some aspects of the help text
 149 * `mutuallyExclusive` is an optional array of arrays of either strings or arrays of strings. The top level array is a list of rules, each rule is a list of elements - each element can be either a string (the name of an option), or a list of strings (a group of option names) - there will be an error if more than one element is present
 150 * `concatRepeatedArrays` is an optional boolean (defaults to `false`) - when set to `true` and an option contains an array value and is repeated, the subsequent values for the flag will be appended rather than overwriting the original value - eg. option `g` of type `[String]`: `-g a -g b -g c,d` will result in `['a','b','c','d']`
 151 * `mergeRepeatedObjects` is an optional boolean (defaults to `false`) - when set to `true` and an option contains an object value and is repeated, the subsequent values for the flag will be merged rather than overwriting the original value - eg. option `g` of type `Object`: `-g a:1 -g b:2 -g c:3,d:4` will result in `{a: 1, b: 2, c: 3, d: 4}`
 152
 153 #### Heading Properties
 154 * `heading` a required string, the name of the heading
 155
 156 #### Option Properties
 157 * `option` the required name of the option - use dash-case, without the leading dashes
 158 * `alias` is an optional string or array of strings which specify any aliases for the option
 159 * `type` is a required string in the [type check](https://github.com/gkz/type-check) [format](https://github.com/gkz/type-check#type-format), this will be used to cast the inputted value and validate it
 160 * `enum` is an optional array of strings, each string will be parsed by [levn](https://github.com/gkz/levn) - the argument value must be one of the resulting values - each potential value must validate against the specified `type`
 161 * `default` is a optional string, which will be parsed by [levn](https://github.com/gkz/levn) and used as the default value if none is set - the value must validate against the specified `type`
 162 * `restPositional` is an optional boolean - if set to `true`, everything after the option will be taken to be a positional argument, even if it looks like a named argument
 163 * `required` is an optional boolean - if set to `true`, the option parsing will fail if the option is not defined
 164 * `overrideRequired` is a optional boolean - if set to `true` and the option is used, and there is another option which is required but not set, it will override the need for the required option and there will be no error - this is useful if you have required options and want to use `--help` or `--version` flags
 165 * `dependsOn` is an optional string or array of strings - if simply a string (the name of another option), it will make sure that that other option is set, if an array of strings, depending on whether `'and'` or `'or'` is first, it will either check whether all (`['and', 'option-a', 'option-b']`), or at least one (`['or', 'option-a', 'option-b']`) other options are set
 166 * `description` is an optional string, which will be displayed next to the option in the help text
 167 * `longDescription` is an optional string, it will be displayed instead of the `description` when `generateHelpForOption` is used
 168 * `example` is an optional string or array of strings with example(s) for the option - these will be displayed when `generateHelpForOption` is used
 169
 170 #### Help Style Properties
 171 * `aliasSeparator` is an optional string, separates multiple names from each other - default: ' ,'
 172 * `typeSeparator` is an optional string, separates the type from the names - default: ' '
 173 * `descriptionSeparator` is an optional string , separates the description from the padded name and type - default: '  '
 174 * `initialIndent` is an optional int - the amount of indent for options - default: 2
 175 * `secondaryIndent` is an optional int - the amount of indent if wrapped fully (in addition to the initial indent) - default: 4
 176 * `maxPadFactor` is an optional number - affects the default level of padding for the names/type, it is multiplied by the average of the length of the names/type - default: 1.5
 177
 178 ## Argument Format
 179 At the highest level there are two types of arguments: named, and positional.
 180
 181 Name arguments of any length are prefixed with `--` (eg. `--go`), and those of one character may be prefixed with either `--` or `-` (eg. `-g`).
 182
 183 There are two types of named arguments: boolean flags (eg. `--problemo`, `-p`) which take no value and result in a `true` if they are present, the falsey `undefined` if they are not present, or `false` if present and explicitly prefixed with `no` (eg. `--no-problemo`). Named arguments with values (eg. `--tseries 800`, `-t 800`) are the other type. If the option has a type `Boolean` it will automatically be made into a boolean flag. Any other type results in a named argument that takes a value.
 184
 185 For more information about how to properly set types to get the value you want, take a look at the [type check](https://github.com/gkz/type-check) and [levn](https://github.com/gkz/levn) pages.
 186
 187 You can group single character arguments that use a single `-`, however all except the last must be boolean flags (which take no value). The last may be a boolean flag, or an argument which takes a value - eg. `-ba 2` is equivalent to `-b -a 2`.
 188
 189 Positional arguments are all those values which do not fall under the above - they can be anywhere, not just at the end. For example, in `cmd -b one -a 2 two` where `b` is a boolean flag, and `a` has the type `Number`, there are two positional arguments, `one` and `two`.
 190
 191 Everything after an `--` is positional, even if it looks like a named argument.
 192
 193 You may optionally use `=` to separate option names from values, for example: `--count=2`.
 194
 195 If you specify the option `NUM`, then any argument using a single `-` followed by a number will be valid and will set the value of `NUM`. Eg. `-2` will be parsed into `NUM: 2`.
 196
 197 If duplicate named arguments are present, the last one will be taken.
 198
 199 ## Technical About
 200 `optionator` is written in [LiveScript](http://livescript.net/) - a language that compiles to JavaScript. It uses [levn](https://github.com/gkz/levn) to cast arguments to their specified type, and uses [type-check](https://github.com/gkz/type-check) to validate values. It also uses the [prelude.ls](http://preludels.com/) library.