Socket
Socket
Sign inDemoInstall

commander

Package Overview
Dependencies
0
Maintainers
6
Versions
114
Alerts
File Explorer

Advanced tools

npm Scripts

Install Socket

Detect and block malicious and high-risk dependencies

Install

Comparing version 9.0.0-0 to 9.0.0-1

14

lib/argument.js

@@ -52,3 +52,3 @@ const { InvalidArgumentError } = require('./error.js');

return this._name;
};
}

@@ -79,3 +79,3 @@ /**

return this;
};
}

@@ -92,3 +92,3 @@ /**

return this;
};
}

@@ -103,6 +103,6 @@ /**

choices(values) {
this.argChoices = values;
this.argChoices = values.slice();
this.parseArg = (arg, previous) => {
if (!values.includes(arg)) {
throw new InvalidArgumentError(`Allowed choices are ${values.join(', ')}.`);
if (!this.argChoices.includes(arg)) {
throw new InvalidArgumentError(`Allowed choices are ${this.argChoices.join(', ')}.`);
}

@@ -115,3 +115,3 @@ if (this.variadic) {

return this;
};
}

@@ -118,0 +118,0 @@ /**

14

lib/help.js

@@ -101,3 +101,3 @@ const { humanReadableArgName } = require('./argument.js');

return cmd._args;
};
}
return [];

@@ -156,3 +156,3 @@ }

}, 0);
};
}

@@ -171,3 +171,3 @@ /**

}, 0);
};
}

@@ -186,3 +186,3 @@ /**

}, 0);
};
}

@@ -269,3 +269,3 @@ /**

return option.description;
};
}

@@ -318,3 +318,3 @@ /**

return term;
};
}
function formatList(textArray) {

@@ -374,3 +374,3 @@ return textArray.join('\n').replace(/^/gm, ' '.repeat(itemIndentWidth));

);
};
}

@@ -377,0 +377,0 @@ /**

28

lib/option.js

@@ -50,3 +50,3 @@ const { InvalidArgumentError } = require('./error.js');

return this;
};
}

@@ -68,3 +68,3 @@ /**

return this;
};
}

@@ -82,3 +82,3 @@ /**

return this;
};
}

@@ -95,3 +95,3 @@ /**

return this;
};
}

@@ -108,3 +108,3 @@ /**

return this;
};
}

@@ -121,3 +121,3 @@ /**

return this;
};
}

@@ -144,6 +144,6 @@ /**

choices(values) {
this.argChoices = values;
this.argChoices = values.slice();
this.parseArg = (arg, previous) => {
if (!values.includes(arg)) {
throw new InvalidArgumentError(`Allowed choices are ${values.join(', ')}.`);
if (!this.argChoices.includes(arg)) {
throw new InvalidArgumentError(`Allowed choices are ${this.argChoices.join(', ')}.`);
}

@@ -156,3 +156,3 @@ if (this.variadic) {

return this;
};
}

@@ -170,3 +170,3 @@ /**

return this.short.replace(/^-/, '');
};
}

@@ -183,3 +183,3 @@ /**

return camelcase(this.name().replace(/^no-/, ''));
};
}

@@ -196,3 +196,3 @@ /**

return this.short === arg || this.long === arg;
};
}

@@ -210,3 +210,3 @@ /**

return !this.required && !this.optional && !this.negate;
};
}
}

@@ -213,0 +213,0 @@

16

package.json
{
"name": "commander",
"version": "9.0.0-0",
"version": "9.0.0-1",
"description": "the complete solution for node.js command-line programs",

@@ -22,4 +22,5 @@ "keywords": [

"scripts": {
"lint": "eslint index.js esm.mjs \"lib/*.js\" \"tests/**/*.js\"",
"typescript-lint": "eslint typings/*.ts tests/*.ts",
"lint": "npm run lint:javascript && npm run lint:typescript",
"lint:javascript": "eslint index.js esm.mjs \"lib/*.js\" \"tests/**/*.js\"",
"lint:typescript": "eslint typings/*.ts tests/*.ts",
"test": "jest && npm run test-typings",

@@ -29,3 +30,3 @@ "test-esm": "node --experimental-modules ./tests/esm-imports-test.mjs",

"typescript-checkJS": "tsc --allowJS --checkJS index.js lib/*.js --noEmit",
"test-all": "npm run test && npm run lint && npm run typescript-lint && npm run typescript-checkJS && npm run test-esm"
"test-all": "npm run test && npm run lint && npm run typescript-checkJS && npm run test-esm"
},

@@ -51,9 +52,12 @@ "files": [

"@types/node": "^16.11.15",
"@typescript-eslint/eslint-plugin": "^4.27.0",
"@typescript-eslint/eslint-plugin": "^4.33.0",
"@typescript-eslint/parser": "^4.27.0",
"eslint": "^7.29.0",
"eslint-config-standard": "^16.0.3",
"eslint-config-standard-with-typescript": "^21.0.1",
"eslint-plugin-import": "^2.25.3",
"eslint-plugin-jest": "^24.3.6",
"eslint-plugin-node": "^11.1.0",
"eslint-plugin-promise": "^5.2.0",
"jest": "^27.0.4",
"standard": "^16.0.3",
"ts-jest": "^27.0.3",

@@ -60,0 +64,0 @@ "tsd": "^0.17.0",

182

Readme.md

@@ -14,2 +14,3 @@ # Commander.js

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Declaring _program_ variable](#declaring-program-variable)

@@ -50,5 +51,5 @@ - [Options](#options)

- [Debugging stand-alone executable subcommands](#debugging-stand-alone-executable-subcommands)
- [Display error](#display-error)
- [Override exit and output handling](#override-exit-and-output-handling)
- [Additional documentation](#additional-documentation)
- [Examples](#examples)
- [Support](#support)

@@ -65,2 +66,81 @@ - [Commander for enterprise](#commander-for-enterprise)

## Quick Start
You write code to describe your command line interface.
Commander looks after parsing the arguments into options and command-arguments,
displays usage errors for problems, and implements a help system.
Commander is strict and displays an error for unrecognised options.
The two most used option types are a boolean option, and an option which takes its value from the following argument.
Example file: [split.js](./examples/split.js)
```js
const { program } = require('commander');
program
.option('--first')
.option('-s, --separator <char>');
program.parse();
const options = program.opts();
const limit = options.first ? 1 : undefined;
console.log(program.args[0].split(options.separator, limit));
```
```sh
$ node split.js -s / --fits a/b/c
error: unknown option '--fits'
(Did you mean --first?)
$ node split.js -s / --first a/b/c
[ 'a' ]
```
Here is a more complete program using a subcommand and with descriptions for the help. In a multi-command program, you have an action handler for each command (or stand-alone executables for the commands).
Example file: [string-util.js](./examples/string-util.js)
```js
const { Command } = require('commander');
const program = new Command();
program
.name('string-util')
.description('CLI to some JavaScript string utilities')
.version('0.8.0');
program.command('split')
.description('Split a string into substrings and display as an array')
.argument('<string>', 'string to split')
.option('--first', 'display just the first substring')
.option('-s, --separator <char>', 'separator character', ',')
.action((str, options) => {
const limit = options.first ? 1 : undefined;
console.log(str.split(options.separator, limit));
});
program.parse();
```
```sh
$ node string-util.js help split
Usage: string-util split [options] <string>
Split a string into substrings and display as an array.
Arguments:
string string to split
Options:
--first display just the first substring
-s, --separator <char> separator character (default: ",")
-h, --help display help for command
$ node string-util.js split --separator=/ a/b/c
[ 'a', 'b', 'c' ]
```
More samples can be found in the [examples](https://github.com/tj/commander.js/tree/master/examples) directory.
## Declaring _program_ variable

@@ -101,4 +181,2 @@

The parsed options can be accessed by calling `.opts()` on a `Command` object, and are passed to the action handler.
(You can also use `.getOptionValue()` and `.setOptionValue()` to work with a single option value,
and `.getOptionValueSource()` and `.setOptionValueWithSource()` when it matters where the option value came from.)

@@ -114,2 +192,8 @@ Multi-word options such as "--template-engine" are camel-cased, becoming `program.opts().templateEngine` etc.

There are additional related routines for when `.opts()` is not enough:
- `.optsWithGlobals()` returns merged local and global option values
- `.getOptionValue()` and `.setOptionValue()` work with a single option value
- `.getOptionValueSource()` and `.setOptionValueWithSource()` include where the option value came from
### Common option types, boolean and value

@@ -543,2 +627,16 @@

If you prefer, you can work with the command directly and skip declaring the parameters for the action handler. The `this` keyword is set to the running command and can be used from a function expression (but not from an arrow function).
Example file: [action-this.js](./examples/action-this.js)
```js
program
.command('serve')
.argument('<script>')
.option('-p, --port <number>', 'port number', 80)
.action(function() {
console.error('Run script %s on port %s', this.args[0], this.opts().port);
});
```
You may supply an `async` action handler, in which case you call `.parseAsync` rather than `.parse`.

@@ -915,2 +1013,14 @@

### Display error
This routine is available to invoke the Commander error handling for your own error conditions. (See also the next section about exit handling.)
As well as the error message, you can optionally specify the `exitCode` (used with `process.exit`)
and `code` (used with `CommanderError`).
```js
program.exit('Password must be longer than four characters');
program.exit('Custom processing has failed', { exitCode: 2, code: 'my.custom.error' });
```
### Override exit and output handling

@@ -962,68 +1072,2 @@

## Examples
In a single command program, you might not need an action handler.
Example file: [pizza](./examples/pizza)
```js
const { program } = require('commander');
program
.description('An application for pizza ordering')
.option('-p, --peppers', 'Add peppers')
.option('-c, --cheese <type>', 'Add the specified type of cheese', 'marble')
.option('-C, --no-cheese', 'You do not want any cheese');
program.parse();
const options = program.opts();
console.log('you ordered a pizza with:');
if (options.peppers) console.log(' - peppers');
const cheese = !options.cheese ? 'no' : options.cheese;
console.log(' - %s cheese', cheese);
```
In a multi-command program, you will have action handlers for each command (or stand-alone executables for the commands).
Example file: [deploy](./examples/deploy)
```js
const { Command } = require('commander');
const program = new Command();
program
.name('deploy')
.version('0.0.1')
.option('-c, --config <path>', 'set config path', './deploy.conf');
program
.command('setup [env]')
.description('run setup commands for all envs')
.option('-s, --setup_mode <mode>', 'Which setup mode to use', 'normal')
.action((env, options) => {
env = env || 'all';
console.log('read config from %s', program.opts().config);
console.log('setup for %s env(s) with %s mode', env, options.setup_mode);
});
program
.command('exec <script>')
.alias('ex')
.description('execute the given remote cmd')
.option('-e, --exec_mode <mode>', 'Which exec mode to use', 'fast')
.action((script, options) => {
console.log('read config from %s', program.opts().config);
console.log('exec "%s" using %s mode and config %s', script, options.exec_mode, program.opts().config);
}).addHelpText('after', `
Examples:
$ deploy exec sequential
$ deploy exec async`
);
program.parse(process.argv);
```
More samples can be found in the [examples](https://github.com/tj/commander.js/tree/master/examples) directory.
## Support

@@ -1030,0 +1074,0 @@

46

typings/index.d.ts

@@ -34,2 +34,9 @@ // Type definitions for commander

export interface ErrorOptions { // optional parameter for error()
/** an id string representing the error */
code?: string;
/** suggested exit code which could be used with process.exit */
exitCode?: number;
}
export class Argument {

@@ -65,3 +72,3 @@ description: string;

*/
choices(values: string[]): this;
choices(values: readonly string[]): this;

@@ -77,3 +84,3 @@ /**

argOptional(): this;
}
}

@@ -115,3 +122,3 @@ export class Option {

*/
preset(arg: unknown): this;
preset(arg: unknown): this;

@@ -147,3 +154,3 @@ /**

*/
choices(values: string[]): this;
choices(values: readonly string[]): this;

@@ -166,4 +173,3 @@ /**

*/
isBoolean(): boolean;
isBoolean(): boolean;
}

@@ -349,4 +355,4 @@

*/
argument<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
argument(name: string, description?: string, defaultValue?: unknown): this;
argument<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
argument(name: string, description?: string, defaultValue?: unknown): this;

@@ -399,2 +405,7 @@ /**

/**
* Display error message and exit (or call exitOverride).
*/
error(message: string, errorOptions?: ErrorOptions): never;
/**
* You can customise the help with a subclass of Help by overriding createHelp,

@@ -450,3 +461,3 @@ * or by overriding Help properties using configureHelp().

/**
/**
* Register callback `fn` for the command.

@@ -574,3 +585,3 @@ *

/**
/**
* Alter parsing of short flags with optional values.

@@ -639,3 +650,3 @@ *

*/
parse(argv?: string[], options?: ParseOptions): this;
parse(argv?: readonly string[], options?: ParseOptions): this;

@@ -659,3 +670,3 @@ /**

*/
parseAsync(argv?: string[], options?: ParseOptions): Promise<this>;
parseAsync(argv?: readonly string[], options?: ParseOptions): Promise<this>;

@@ -675,3 +686,3 @@ /**

/**
* Return an object containing options as key-value pairs
* Return an object containing local option values as key-value pairs
*/

@@ -681,2 +692,7 @@ opts<T extends OptionValues>(): T;

/**
* Return an object containing merged local and global option values as key-value pairs.
*/
optsWithGlobals<T extends OptionValues>(): T;
/**
* Set the description.

@@ -715,3 +731,3 @@ *

*/
aliases(aliases: string[]): this;
aliases(aliases: readonly string[]): this;
/**

@@ -777,3 +793,3 @@ * Get aliases for the command.

/**
/**
* Output help information for this command.

@@ -780,0 +796,0 @@ *

lib/command.js

Sorry, the diff of this file is too big to display

SocketSocket SOC 2 Logo

Product

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

About

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc