Option definition reference

definition

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

OptionDefinition ⏏

Describes a command-line option. Additionally, you can add description and typeLabel properties and make use of command-line-usage.

Kind: Exported class

option.name : string

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

[
  { name: "file" },
  { name: "verbose" },
  { name: "depth" }
]

In this case, the value of each option will be either a Boolean or string.

#	Command line args	.parse() output
1	--file	{ file: true }
2	--file lib.js --verbose	{ file: "lib.js", verbose: true }
3	--verbose very	{ verbose: "very" }
4	--depth 2	{ depth: "2" }

Unicode option names and aliases are valid, for example:

[
  { 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.

You can use a class, if you like:

const fs = require('fs')

function FileDetails(filename){
  if (!(this instanceof FileDetails)) return new FileDetails(filename)
  this.filename = filename
  this.exists = fs.existsSync(filename)
}

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

#	Command line args	.parse() 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.

#	Command line args	.parse() 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 hypen.

[
  { name: "hot", alias: "h", type: Boolean },
  { name: "discount", alias: "d", type: Boolean },
  { name: "courses", alias: "c" , type: Number }
]

#	Command line	.parse() 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).

[
  { name: "files", type: String, multiple: true }
]

#	Command line	.parse() 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.defaultOption : boolean

Any unclaimed command-line args will be set on this option. This flag is typically set on the most commonly-used option to make for more concise usage (i.e. $ myapp *.js instead of $ myapp --files *.js).

[
  { name: "files", type: String, multiple: true, defaultOption: true }
]

#	Command line	.parse() 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.

[
  { name: "files", type: String, multiple: true, defaultValue: [ "one.js" ] },
  { name: "max", type: Number, defaultValue: 3 }
]

#	Command line	.parse() 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).

[
  { name: "verbose", group: "standard" },
  { name: "help", group: [ "standard", "main" ] },
  { name: "compress", group: [ "server", "main" ] },
  { name: "static", group: "server" },
  { name: "debug" }
]

#	Command Line	.parse() 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