Permalink
Browse files

better docs for cli.option()

  • Loading branch information...
1 parent 7ef1b27 commit 7c962e3a9882a724775e561ac6ad5319fa3aa94a @jxson committed Mar 17, 2012
Showing with 59 additions and 16 deletions.
  1. +3 −0 doc/index.md
  2. +56 −16 doc/option.md
View
@@ -0,0 +1,3 @@
+# comman-router
+
+## Events
View
@@ -3,44 +3,84 @@ command-router option() -- Define options for your CLI
## SYNOPSIS
- cli.option(name, params)
+ cli.option(params)
## Description
-Provides an entry point to define options for the CLI instance which will get parsed on the `start` event.
+Provides an entry point to define options for the `CLI` instance.
-The `name` argument **is required** and specifies a string that will map to a command line flag.
+* `params`
-The `params` object is optional, use it to override defaults.
+ declares specific attributes of the option.
-## `params` Argument
+### params
-The `params` object allows additional information to be set about the option being defined. There are three properties:
+* `name`: The name of the option that will map to a command line
+* `alias`: Allows a shorthand to be defined.
+* `type`: Define the type for this flag. **Defaults to `Boolean`**
+* `default`: The default value for the option being defined. **Defaults to `false`**
-* `params.alias`: Allows a shorthand to be defined, if you want your option '--config' to also map to '-c' this is where you set that up.
-* `params.type`: Define the type for this flag, [nopt][nopt] is used for parsing the options internally and this type option will need to be one of the types defined in `nopt.typeDefs`
-* `params.default`: The default value for the option being defined
+#### Types
-### `params` Defaults
+[nopt][nopt] is used for parsing the options internally. `params.type` will need to be one of the types defined in `nopt.typeDefs`:
-If a `params` object is not passed in the option will be defined as a `Boolean` value defaulting to false without an alias:
+* String: A normal string. No parsing is done.
+* path: A file system path. Gets resolved against cwd if not absolute.
+* url: A url. If it doesn't parse, it isn't accepted.
+* Number: Must be numeric.
+* Date: Must parse as a date. If it does, and `Date` is one of the options,
+ then it will return a Date object, not a string.
+* Boolean: Must be either `true` or `false`. If an option is a boolean,
+ then it does not need a value, and its presence will imply `true` as
+ the value. To negate boolean flags, do `--no-whatever` or `--whatever
+ false`
+* NaN: Means that the option is strictly not allowed. Any value will
+ fail.
+* Stream: An object matching the "Stream" class in node. Valuable
+ for use when validating programmatically. (npm uses this to let you
+ supply any WriteStream on the `outfd` and `logfd` config options.)
+* Array: If `Array` is specified as one of the types, then the value
+ will be parsed as a list of options. This means that multiple values
+ can be specified, and that the value will always be an array.
- cli.option('verbose')
+See the [nopt][nopt] documentation for more details.
+
+## Defaults
+
+If the `params` object is missing keys for `type` and `default` the option will be defined as a `Boolean` type defaulting to `false` without an alias:
-Is the equivalent to:
+ cli.option({ name: 'verbose' })
+
+ // Is the equivalent to:
cli.option({ name: 'verbose'
, type: Boolean
, default: false
- });
+ })
+
+ // And can be simplifed to
+
+ cli.option('verbose')
## Examples
To set an option for something like a `path` to a config file:
- cli.option('config', { alias: 'c'
+ var path = require('path')
+ ;
+
+ cli.option({ name: 'config'
+ , alias: 'c'
, default: '.haiku/config.js'
, type: path
});
-[nopt]: https://github.com/isaacs/nopt
+More complex examples for defining options can be found in the [examples directory][examples]
+
+## See Also
+
+* [Examples of defining options][examples]
+* [nopt][nopt]
+
+[nopt]: https://github.com/isaacs/nopt
+[examples]: #

0 comments on commit 7c962e3

Please sign in to comment.