Socket
Socket
Sign inDemoInstall

command-line-args

Package Overview
Dependencies
Maintainers
1
Versions
74
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

command-line-args - npm Package Compare versions

Comparing version 5.0.0-alpha.0 to 5.0.0-alpha.1

lib/option-definition.js

11

doc/API.md

@@ -9,3 +9,3 @@ <a name="module_command-line-args"></a>

Parsing is strict by default, an exception is thrown if the user sets either an unknown option (one without a valid [definition](https://github.com/75lb/command-line-args/blob/next/doc/option-definition.md)) or value. To enable [partial parsing](https://github.com/75lb/command-line-args/wiki/Partial-mode-example), invoke `commandLineArgs` with the `partial` option - all unknown arguments will be returned in the `_unknown` property.
Parsing is strict by default - an exception is thrown if the user sets an unknown value or option (one without a valid [definition](https://github.com/75lb/command-line-args/blob/next/doc/option-definition.md)). To be more permissive, enabling [partial mode](https://github.com/75lb/command-line-args/wiki/Partial-mode-example) will return known options as usual and return unknown arguments in a separate `_unknown` property.

@@ -15,3 +15,5 @@ **Kind**: Exported function

- `UNKNOWN_OPTION` if `options.partial` is false and the user set an undefined option (stored at `err.optionName`)
- `UNKNOWN_OPTION` If `options.partial` is false and the user set an undefined option. The unknown option name is stored at `err.optionName`.
- `UNKNOWN_VALUE` If `options.partial` is false and the user set a value unaccounted for by an option.
- `ALREADY_SET` If a user sets a singular, non-multiple option more than once.
- `INVALID_DEFINITIONS`

@@ -24,2 +26,3 @@ - If an option definition is missing the required `name` property

- If more than one option definition has `defaultOption: true`
- If a `Boolean` option is also set as the `defaultOption`.

@@ -33,4 +36,4 @@

| [options.partial] | <code>boolean</code> | If `true`, an array of unknown arguments is returned in the `_unknown` property of the output. |
| [options.stopAtFirstUnknown] | <code>boolean</code> | If `true`, the parsing will stop at the first unknown argument and the remaining arguments will be put in `_unknown`. |
| [options.camelCase] | <code>boolean</code> | If set, options with hypenated names (e.g. `move-to`) will be returned in camel-case (e.g. `moveTo`). |
| [options.stopAtFirstUnknown] | <code>boolean</code> | If `true`, parsing will stop at the first unknown argument and the remaining arguments returned in `_unknown`. When set, `partial: true` is also implied. |
| [options.camelCase] | <code>boolean</code> | If `true`, options with hypenated names (e.g. `move-to`) will be returned in camel-case (e.g. `moveTo`). |

@@ -1,23 +0,23 @@

<a name="module_definition"></a>
<a name="module_option-definition"></a>
## definition
## option-definition
* [definition](#module_definition)
* [OptionDefinition](#exp_module_definition--OptionDefinition) ⏏
* [.name](#module_definition--OptionDefinition.OptionDefinition+name) : <code>string</code>
* [.type](#module_definition--OptionDefinition.OptionDefinition+type) : <code>function</code>
* [.alias](#module_definition--OptionDefinition.OptionDefinition+alias) : <code>string</code>
* [.multiple](#module_definition--OptionDefinition.OptionDefinition+multiple) : <code>boolean</code>
* [.lazyMultiple](#module_definition--OptionDefinition.OptionDefinition+lazyMultiple) : <code>boolean</code>
* [.defaultOption](#module_definition--OptionDefinition.OptionDefinition+defaultOption) : <code>boolean</code>
* [.defaultValue](#module_definition--OptionDefinition.OptionDefinition+defaultValue) : <code>\*</code>
* [.group](#module_definition--OptionDefinition.OptionDefinition+group) : <code>string</code> \| <code>Array.&lt;string&gt;</code>
* [option-definition](#module_option-definition)
* [OptionDefinition](#exp_module_option-definition--OptionDefinition) ⏏
* [.name](#module_option-definition--OptionDefinition.OptionDefinition+name) : <code>string</code>
* [.type](#module_option-definition--OptionDefinition.OptionDefinition+type) : <code>function</code>
* [.alias](#module_option-definition--OptionDefinition.OptionDefinition+alias) : <code>string</code>
* [.multiple](#module_option-definition--OptionDefinition.OptionDefinition+multiple) : <code>boolean</code>
* [.lazyMultiple](#module_option-definition--OptionDefinition.OptionDefinition+lazyMultiple) : <code>boolean</code>
* [.defaultOption](#module_option-definition--OptionDefinition.OptionDefinition+defaultOption) : <code>boolean</code>
* [.defaultValue](#module_option-definition--OptionDefinition.OptionDefinition+defaultValue) : <code>\*</code>
* [.group](#module_option-definition--OptionDefinition.OptionDefinition+group) : <code>string</code> \| <code>Array.&lt;string&gt;</code>
<a name="exp_module_definition--OptionDefinition"></a>
<a name="exp_module_option-definition--OptionDefinition"></a>
### OptionDefinition ⏏
Describes a command-line option. Additionally, you can add `description` and `typeLabel` properties and make use of [command-line-usage](https://github.com/75lb/command-line-usage).
Describes a command-line option. Additionally, if generating a usage guide with [command-line-usage](https://github.com/75lb/command-line-usage) you could optionally add `description` and `typeLabel` properties to each definition.
**Kind**: Exported class
<a name="module_definition--OptionDefinition.OptionDefinition+name"></a>
<a name="module_option-definition--OptionDefinition.OptionDefinition+name"></a>

@@ -27,21 +27,19 @@ #### option.name : <code>string</code>

```js
[
{ name: "file" },
{ name: "verbose" },
{ name: "depth" }
const optionDefinitions = [
{ name: 'file' },
{ name: 'depth' }
]
```
In this case, the value of each option will be either a Boolean or string.
Where a `type` property is not specified it will default to `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" }` |
| 2 | `--file` | `{ file: null }` |
| 2 | `--file lib.js` | `{ file: 'lib.js' }` |
| 4 | `--depth 2` | `{ depth: '2' }` |
Unicode option names and aliases are valid, for example:
```js
[
const optionDefinitions = [
{ name: 'один' },

@@ -53,4 +51,4 @@ { name: '两' },

**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_definition--OptionDefinition)
<a name="module_definition--OptionDefinition.OptionDefinition+type"></a>
**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_option-definition--OptionDefinition)
<a name="module_option-definition--OptionDefinition.OptionDefinition+type"></a>

@@ -60,3 +58,3 @@ #### option.type : <code>function</code>

You can use a class, if you like:
The most common values used are `String`, `Number` and `Boolean` but you can use a custom function, if you like:

@@ -66,10 +64,12 @@ ```js

function FileDetails(filename){
if (!(this instanceof FileDetails)) return new FileDetails(filename)
this.filename = filename
this.exists = fs.existsSync(filename)
class FileDetails {
constructor (filename) {
const fs = require('fs')
this.filename = filename
this.exists = fs.existsSync(filename)
}
}
const cli = commandLineArgs([
{ name: 'file', type: FileDetails },
{ name: 'file', type: filename => new FileDetails(filename) },
{ name: 'depth', type: Number }

@@ -90,5 +90,5 @@ ])

**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_definition--OptionDefinition)
**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_option-definition--OptionDefinition)
**Default**: <code>String</code>
<a name="module_definition--OptionDefinition.OptionDefinition+alias"></a>
<a name="module_option-definition--OptionDefinition.OptionDefinition+alias"></a>

@@ -99,6 +99,6 @@ #### option.alias : <code>string</code>

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

@@ -112,4 +112,4 @@ ```

**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_definition--OptionDefinition)
<a name="module_definition--OptionDefinition.OptionDefinition+multiple"></a>
**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_option-definition--OptionDefinition)
<a name="module_option-definition--OptionDefinition.OptionDefinition+multiple"></a>

@@ -120,7 +120,9 @@ #### option.multiple : <code>boolean</code>

```js
[
{ name: "files", type: String, multiple: true }
const optionDefinitions = [
{ name: 'files', type: String, multiple: true }
]
```
Note, examples 1 and 3 below demonstrate "greedy" parsing which can be disabled by using `lazyMultiple`.
| # | Command line | .parse() output |

@@ -132,4 +134,4 @@ | --- | ------------ | ------------ |

**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_definition--OptionDefinition)
<a name="module_definition--OptionDefinition.OptionDefinition+lazyMultiple"></a>
**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_option-definition--OptionDefinition)
<a name="module_option-definition--OptionDefinition.OptionDefinition+lazyMultiple"></a>

@@ -139,11 +141,21 @@ #### option.lazyMultiple : <code>boolean</code>

**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_definition--OptionDefinition)
<a name="module_definition--OptionDefinition.OptionDefinition+defaultOption"></a>
```js
const optionDefinitions = [
{ name: 'files', type: String, lazyMultiple: true }
]
```
| # | Command line | .parse() output |
| --- | ------------ | ------------ |
| 1 | `--files one.js --files two.js` | `{ files: [ 'one.js', 'two.js' ] }` |
**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_option-definition--OptionDefinition)
<a name="module_option-definition--OptionDefinition.OptionDefinition+defaultOption"></a>
#### option.defaultOption : <code>boolean</code>
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`).
Any values unaccounted for by an option definition 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. `$ example *.js` instead of `$ example --files *.js`).
```js
[
{ name: "files", type: String, multiple: true, defaultOption: true }
const optionDefinitions = [
{ name: 'files', type: String, multiple: true, defaultOption: true }
]

@@ -158,4 +170,4 @@ ```

**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_definition--OptionDefinition)
<a name="module_definition--OptionDefinition.OptionDefinition+defaultValue"></a>
**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_option-definition--OptionDefinition)
<a name="module_option-definition--OptionDefinition.OptionDefinition+defaultValue"></a>

@@ -166,5 +178,5 @@ #### option.defaultValue : <code>\*</code>

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

@@ -179,4 +191,4 @@ ```

**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_definition--OptionDefinition)
<a name="module_definition--OptionDefinition.OptionDefinition+group"></a>
**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_option-definition--OptionDefinition)
<a name="module_option-definition--OptionDefinition.OptionDefinition+group"></a>

@@ -189,8 +201,8 @@ #### option.group : <code>string</code> \| <code>Array.&lt;string&gt;</code>

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

@@ -245,2 +257,2 @@ ```

**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_definition--OptionDefinition)
**Kind**: instance property of [<code>OptionDefinition</code>](#exp_module_option-definition--OptionDefinition)

@@ -11,5 +11,4 @@ 'use strict'

*
* Parsing is strict by default, an exception is thrown if the user sets either an unknown option (one without a valid [definition](https://github.com/75lb/command-line-args/blob/next/doc/option-definition.md)) or value. To enable [partial parsing](https://github.com/75lb/command-line-args/wiki/Partial-mode-example), invoke `commandLineArgs` with the `partial` option - all unknown arguments will be returned in the `_unknown` property.
* Parsing is strict by default - an exception is thrown if the user sets an unknown value or option (one without a valid [definition](https://github.com/75lb/command-line-args/blob/next/doc/option-definition.md)). To be more permissive, enabling [partial mode](https://github.com/75lb/command-line-args/wiki/Partial-mode-example) will return known options as usual and return unknown arguments in a separate `_unknown` property.
*
*
* @param {module:definition[]} - An array of [OptionDefinition](https://github.com/75lb/command-line-args/blob/next/doc/option-definition.md) objects

@@ -19,6 +18,8 @@ * @param {object} [options] - Options.

* @param {boolean} [options.partial] - If `true`, an array of unknown arguments is returned in the `_unknown` property of the output.
* @param {boolean} [options.stopAtFirstUnknown] - If `true`, the parsing will stop at the first unknown argument and the remaining arguments will be put in `_unknown`.
* @param {boolean} [options.camelCase] - If set, options with hypenated names (e.g. `move-to`) will be returned in camel-case (e.g. `moveTo`).
* @param {boolean} [options.stopAtFirstUnknown] - If `true`, parsing will stop at the first unknown argument and the remaining arguments returned in `_unknown`. When set, `partial: true` is also implied.
* @param {boolean} [options.camelCase] - If `true`, options with hypenated names (e.g. `move-to`) will be returned in camel-case (e.g. `moveTo`).
* @returns {object}
* @throws `UNKNOWN_OPTION` if `options.partial` is false and the user set an undefined option (stored at `err.optionName`)
* @throws `UNKNOWN_OPTION` If `options.partial` is false and the user set an undefined option. The unknown option name is stored at `err.optionName`.
* @throws `UNKNOWN_VALUE` If `options.partial` is false and the user set a value unaccounted for by an option.
* @throws `ALREADY_SET` If a user sets a singular, non-multiple option more than once.
* @throws `INVALID_DEFINITIONS`

@@ -31,2 +32,3 @@ * - If an option definition is missing the required `name` property

* - If more than one option definition has `defaultOption: true`
* - If a `Boolean` option is also set as the `defaultOption`.
* @alias module:command-line-args

@@ -37,3 +39,3 @@ */

if (options.stopAtFirstUnknown) options.partial = true
const Definitions = require('./lib/definitions')
const Definitions = require('./lib/option-definitions')
optionDefinitions = Definitions.from(optionDefinitions)

@@ -40,0 +42,0 @@

@@ -17,3 +17,3 @@ 'use strict'

this.options = options || {}
const Definitions = require('./definitions')
const Definitions = require('./option-definitions')
/**

@@ -20,0 +20,0 @@ * Option Definitions

@@ -5,3 +5,3 @@ 'use strict'

const t = require('typical')
const Definition = require('./definition')
const Definition = require('./option-definition')

@@ -28,3 +28,3 @@ /**

const def = this.definition
if (def.multiple || def.lazyMultiple) {
if (def.isMultiple()) {
/* don't add null or undefined to a multiple */

@@ -39,4 +39,4 @@ if (val !== null && val !== undefined) {

/* throw if already set on a singlar defaultOption */
if (def.defaultOption && !def.multiple && this.state === 'set') {
const err = new Error('Singular defaultOption already set with: ' + this.get())
if (!def.isMultiple() && this.state === 'set') {
const err = new Error(`Singular option already set [${this.definition.name}=${this.get()}]`)
err.name = 'ALREADY_SET'

@@ -47,6 +47,6 @@ err.value = val

_value.set(this, val)
/* required to make 'partial: defaultOption with value equal to defaultValue 2' pass */
if (!(def.defaultOption && !def.multiple)) {
this.state = state
}
// /* required to make 'partial: defaultOption with value equal to defaultValue 2' pass */
// if (!(def.defaultOption && !def.isMultiple())) {
// this.state = state
// }
} else {

@@ -53,0 +53,0 @@ _value.set(this, def.type(val))

@@ -10,3 +10,3 @@ 'use strict'

super()
const Definitions = require('./definitions')
const Definitions = require('./option-definitions')
/**

@@ -13,0 +13,0 @@ * @type {OptionDefinitions}

{
"name": "command-line-args",
"version": "5.0.0-alpha.0",
"version": "5.0.0-alpha.1",
"description": "A mature, feature-complete library to parse command-line options.",

@@ -8,4 +8,4 @@ "repository": "https://github.com/75lb/command-line-args.git",

"test": "test-runner test/*.js test/internals/*.js",
"docs": "jsdoc2md index.js > doc/API.md && jsdoc2md lib/definition.js > doc/option-definition.md",
"cover": "istanbul cover ./node_modules/.bin/test-runner test/internal/*.js test/external/*.js && cat coverage/lcov.info | ./node_modules/.bin/coveralls #&& rm -rf coverage; echo"
"docs": "jsdoc2md index.js > doc/API.md && jsdoc2md lib/option-definition.js > doc/option-definition.md",
"cover": "istanbul cover ./node_modules/.bin/test-runner test/*.js test/internals/*.js && cat coverage/lcov.info | ./node_modules/.bin/coveralls #&& rm -rf coverage; echo"
},

@@ -12,0 +12,0 @@ "keywords": [

@@ -65,3 +65,3 @@ [![view on npm](https://img.shields.io/npm/v/command-line-args.svg)](https://www.npmjs.org/package/command-line-args)

There is plenty more to learn, please see [the wiki](https://github.com/75lb/command-line-args/wiki) for further examples and documentation.
There is plenty more to learn, please see [the wiki](https://github.com/75lb/command-line-args/wiki) for examples and documentation.

@@ -68,0 +68,0 @@ ## Install

@@ -9,3 +9,2 @@ 'use strict'

runner.test('camel-case', function () {
const argv = [ '--one-two', '1', '--three' ]
const optionDefinitions = [

@@ -15,2 +14,3 @@ { name: 'one-two' },

]
const argv = [ '--one-two', '1', '--three' ]
const result = commandLineArgs(optionDefinitions, { argv, camelCase: true })

@@ -17,0 +17,0 @@ a.deepStrictEqual(result, {

'use strict'
const TestRunner = require('test-runner')
const a = require('assert')
const Definitions = require('../../lib/definitions')
const Definitions = require('../../lib/option-definitions')

@@ -6,0 +6,0 @@ const runner = new TestRunner()

@@ -8,3 +8,3 @@ 'use strict'

runner.test('type-boolean: different values', function () {
runner.test('type-boolean: single set', function () {
const option = new FlagOption({ name: 'one', type: Boolean })

@@ -14,8 +14,20 @@

a.strictEqual(option.get(), true)
})
runner.test('type-boolean: single set 2', function () {
const option = new FlagOption({ name: 'one', type: Boolean })
option.set('true')
a.strictEqual(option.get(), true)
option.set('false')
})
runner.test('type-boolean: set twice', function () {
const option = new FlagOption({ name: 'one', type: Boolean })
option.set(undefined)
a.strictEqual(option.get(), true)
option.set('sdsdf')
a.strictEqual(option.get(), true)
a.throws(
() => option.set('true'),
err => err.name === 'ALREADY_SET'
)
})

@@ -33,10 +45,4 @@

option.set(undefined)
option.set()
a.strictEqual(option.get(), true)
option.set('true')
a.strictEqual(option.get(), true)
option.set('false')
a.strictEqual(option.get(), true)
option.set('sdsdf')
a.strictEqual(option.get(), true)
})

@@ -43,0 +49,0 @@

@@ -15,5 +15,2 @@ 'use strict'

a.strictEqual(option.state, 'set')
option.set('drei')
a.strictEqual(option.get(), 'drei')
a.strictEqual(option.state, 'set')
})

@@ -28,5 +25,28 @@

a.strictEqual(option.state, 'set')
})
runner.test('option.set(): simple set string twice', function () {
const option = Option.create({ name: 'two' })
a.strictEqual(option.get(), null)
a.strictEqual(option.state, 'default')
option.set('zwei')
a.strictEqual(option.get(), 'zwei')
a.strictEqual(option.state, 'set')
a.throws(
() => option.set('drei'),
err => err.name === 'ALREADY_SET'
)
})
runner.test('option.set(): simple set boolean twice', function () {
const option = Option.create({ name: 'two', type: Boolean })
a.strictEqual(option.get(), null)
a.strictEqual(option.state, 'default')
option.set()
a.strictEqual(option.get(), true)
a.strictEqual(option.state, 'set')
a.throws(
() => option.set(),
err => err.name === 'ALREADY_SET'
)
})

@@ -57,1 +77,25 @@

})
runner.test('option.set(): string multiple defaultOption', function () {
const option = Option.create({ name: 'two', multiple: true, defaultOption: true })
a.deepStrictEqual(option.get(), [])
a.strictEqual(option.state, 'default')
option.set('1')
a.deepStrictEqual(option.get(), [ '1' ])
a.strictEqual(option.state, 'set')
option.set('2')
a.deepStrictEqual(option.get(), [ '1', '2' ])
a.strictEqual(option.state, 'set')
})
runner.test('option.set: lazyMultiple defaultOption', function () {
const option = Option.create({ name: 'one', lazyMultiple: true, defaultOption: true })
a.deepStrictEqual(option.get(), [])
a.strictEqual(option.state, 'default')
option.set('1')
a.deepStrictEqual(option.get(), [ '1' ])
a.strictEqual(option.state, 'set')
option.set('2')
a.deepStrictEqual(option.get(), [ '1', '2' ])
a.strictEqual(option.state, 'set')
})
SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc