option-definition.md

option-definition

• option-definition
  • OptionDefinition ⏏
    • .name : string
    • .type : function
    • .alias : string
    • .multiple : boolean
    • .lazyMultiple : boolean
    • .defaultOption : boolean
    • .defaultValue : *
    • .group : string | Array.<string>

OptionDefinition ⏏

Describes a command-line option. Additionally, if generating a usage guide with command-line-usage you could optionally add description and typeLabel properties to each definition.

Kind: Exported class

option.name : string

The only required definition property is name, so the simplest working example is

const optionDefinitions = [
  { name: 'file' },
  { name: 'depth' }
]

Where a type property is not specified it will default to String.

#	argv input	commandLineArgs() output
1	--file	{ file: null }
2	--file lib.js	{ file: 'lib.js' }
3	--depth 2	{ depth: '2' }

Unicode option names and aliases are valid, for example:

const optionDefinitions = [
  { name: 'один' },
  { name: '两' },
  { name: 'три', alias: 'т' }
]

Kind: instance property of OptionDefinition

option.type : function

The type value is a setter function (you receive the output from this), enabling you to be specific about the type and value received.

The most common values used are String (the default), Number and Boolean but you can use a custom function, for example:

const fs = require('fs')

class FileDetails {
  constructor (filename) {
    this.filename = filename
    this.exists = fs.existsSync(filename)
  }
}

const cli = commandLineArgs([
  { name: 'file', type: filename => new FileDetails(filename) },
  { name: 'depth', type: Number }
])

#	argv input	commandLineArgs() output
1	--file asdf.txt	{ file: { filename: 'asdf.txt', exists: false } }

The --depth option expects a Number. If no value was set, you will receive null.

#	argv input	commandLineArgs() output
2	--depth	{ depth: null }
3	--depth 2	{ depth: 2 }

Kind: instance property of OptionDefinition
Default: String

option.alias : string

getopt-style short option names. Can be any single character (unicode included) except a digit or hyphen.

const optionDefinitions = [
  { name: 'hot', alias: 'h', type: Boolean },
  { name: 'discount', alias: 'd', type: Boolean },
  { name: 'courses', alias: 'c' , type: Number }
]

#	argv input	commandLineArgs() output
1	-hcd	{ hot: true, courses: null, discount: true }
2	-hdc 3	{ hot: true, discount: true, courses: 3 }

Kind: instance property of OptionDefinition

option.multiple : boolean

Set this flag if the option takes a list of values. You will receive an array of values, each passed through the type function (if specified).

const optionDefinitions = [
  { name: 'files', type: String, multiple: true }
]

Note, examples 1 and 3 below demonstrate "greedy" parsing which can be disabled by using lazyMultiple.

#	argv input	commandLineArgs() output
1	--files one.js two.js	{ files: [ 'one.js', 'two.js' ] }
2	--files one.js --files two.js	{ files: [ 'one.js', 'two.js' ] }
3	--files *	{ files: [ 'one.js', 'two.js' ] }

Kind: instance property of OptionDefinition

option.lazyMultiple : boolean

Identical to multiple but with greedy parsing disabled.

const optionDefinitions = [
  { name: 'files', lazyMultiple: true },
  { name: 'verbose', alias: 'v', type: Boolean, lazyMultiple: true }
]

#	argv input	commandLineArgs() output
1	--files one.js --files two.js	{ files: [ 'one.js', 'two.js' ] }
2	-vvv	{ verbose: [ true, true, true ] }

Kind: instance property of OptionDefinition

option.defaultOption : boolean

Any values unaccounted for by an option definition will be set on the defaultOption. This flag is typically set on the most commonly-used option to make for more concise usage (i.e. $ example *.js instead of $ example --files *.js).

const optionDefinitions = [
  { name: 'files', multiple: true, defaultOption: true }
]

#	argv input	commandLineArgs() output
1	--files one.js two.js	{ files: [ 'one.js', 'two.js' ] }
2	one.js two.js	{ files: [ 'one.js', 'two.js' ] }
3	*	{ files: [ 'one.js', 'two.js' ] }

Kind: instance property of OptionDefinition

option.defaultValue : *

An initial value for the option.

const optionDefinitions = [
  { name: 'files', multiple: true, defaultValue: [ 'one.js' ] },
  { name: 'max', type: Number, defaultValue: 3 }
]

#	argv input	commandLineArgs() output
1		{ files: [ 'one.js' ], max: 3 }
2	--files two.js	{ files: [ 'two.js' ], max: 3 }
3	--max 4	{ files: [ 'one.js' ], max: 4 }

Kind: instance property of OptionDefinition

option.group : string | Array.<string>

When your app has a large amount of options it makes sense to organise them in groups.

There are two automatic groups: _all (contains all options) and _none (contains options without a group specified in their definition).

const optionDefinitions = [
  { name: 'verbose', group: 'standard' },
  { name: 'help', group: [ 'standard', 'main' ] },
  { name: 'compress', group: [ 'server', 'main' ] },
  { name: 'static', group: 'server' },
  { name: 'debug' }
]

#	Command Line	commandLineArgs() output
1	--verbose	{ _all: { verbose: true }, standard: { verbose: true } }
2	--debug	{ _all: { debug: true }, _none: { debug: true } }
3	--verbose --debug --compress	{ _all: { verbose: true, debug: true, compress: true }, standard: { verbose: true }, server: { compress: true }, main: { compress: true }, _none: { debug: true } }
4	--compress	{ _all: { compress: true }, server: { compress: true }, main: { compress: true } }

Kind: instance property of OptionDefinition