3h-cli 中文文档教程
3h-cli
一个 cli 程序库。
Example
npm i 3h-cli
/* my-cli.js */
#!/usr/bin/env node
const { Program } = require('3h-cli');
const program = new Program('my-cli');
program
.action({
name: 'foo',
help: 'action foo'
})
.action({
name: 'bar',
help: 'action bar'
})
.option({
name: '--baz',
alias: '-b',
value: '<val>',
help: 'option baz'
})
.option({
name: '--help',
alias: '-h',
help: 'show help info\nlike this'
})
.rest({
value: '[args...]',
help: 'other args'
})
.parse(process.argv)
.then(args => {
console.log('received actions:', args.actions);
console.log('received options:', args.options);
console.log('other args:', args.rest);
if (args.options.has('--help')) {
return program.help();
}
}, err => {
console.error(err);
process.exit(1);
})
$ ./my-cli.js --help
received actions: []
received options: Map { '--help' => [] }
other args: []
Usage:
my-cli <action> [options] -- [args...]
actions:
foo action foo
bar action bar
Options:
--baz, -b <val> option baz
--help, -h show help info
like this
-- [args...] other args
API Reference
API 参考以 TypeScript 风格编写。
class Args {
constructor(
actions: string[],
options: Map<string, string[]>,
rest: string[]
);
readonly actions: string[];
readonly options: Map<string, string[]>;
readonly rest: string[];
/**
* A utility method that returns
* the specific option if it exists
* or an empty array otherwise
*/
getOption(name: string): string[];
}
interface Args {
actions: string[];
options: Map<string, string[]>;
rest: string[];
}
/**
* Parse arguments from the given array of strings
* @example
* ```js
* const rawArgs = ['foo', '--bar', '-ac', '666', '--', '10', '11'],
* optionAliases = new Map([['-a', '--baz']]);
*
* console.log(parse(rawArgs, optionAliases));
* // {
* // actions: ['foo'],
* // options: Map {
* // '--bar' => [],
* // '--baz' => [],
* // '-c' => ['666']
* // },
* // rest: ['10', '11']
* // }
* ```
*/
function parse(
rawArgs: string[],
optionAliases?: Map<string, string>
): Args;
interface ActionDefinition {
name: string;
help?: string;
}
interface OptionDefinition {
name: string;
alias?: string | null;
value?: string;
help?: string;
}
interface RestDefinition {
value?: string;
help?: string;
}
type ProgramOptions = Partial<{
title: string;
helpInfoIndent: number;
helpInfoGap: number;
ignoreUnknownActions: boolean;
ignoreUnknownOptions: boolean;
}>;
class Program {
constructor(name: string, options?: Readonly<ProgramOptions>);
/**
* The name/title of the program
* (displayed in built-in help info)
*/
readonly name: string;
title: string;
/**
* Style parameters of built-in help info
*/
helpInfoIndent: number;
helpInfoGap: number;
/**
* Whether to ignore undefined actions/options
* (By default, undefined options will
* cause the parsing promise to be rejected
* but unknown actions won't)
*/
ignoreUnknownActions: boolean;
ignoreUnknownOptions: boolean;
/**
* Register a action, an option or rest options
*/
action(definition: ActionDefinition): this;
option(definition: OptionDefinition): this;
rest(description: RestDefinition | null): this;
/**
* Parse the arguments
* @returns a promise solved with parsed args on success
* or rejected on unknown actions/options
*/
parse(rawArgs: string[]): Promise<Args>;
/**
* Display built-in help info
* (the help info is generated from action and
* option definitions; you can append other help
* info after this like the example below)
* @example
* ```js
* program.parse(process.argv)
* .then(args => {
* if (args.options.has('--help')) {
* program.help();
* console.log('\nExamples');
* console.log(' my-cli foo --bar');
* } else {
* // ...
* }
* }, err => {
* // ...
* });
* ```
*/
help(): void;
}
3h-cli
A cli program lib.
Example
npm i 3h-cli
/* my-cli.js */
#!/usr/bin/env node
const { Program } = require('3h-cli');
const program = new Program('my-cli');
program
.action({
name: 'foo',
help: 'action foo'
})
.action({
name: 'bar',
help: 'action bar'
})
.option({
name: '--baz',
alias: '-b',
value: '<val>',
help: 'option baz'
})
.option({
name: '--help',
alias: '-h',
help: 'show help info\nlike this'
})
.rest({
value: '[args...]',
help: 'other args'
})
.parse(process.argv)
.then(args => {
console.log('received actions:', args.actions);
console.log('received options:', args.options);
console.log('other args:', args.rest);
if (args.options.has('--help')) {
return program.help();
}
}, err => {
console.error(err);
process.exit(1);
})
$ ./my-cli.js --help
received actions: []
received options: Map { '--help' => [] }
other args: []
Usage:
my-cli <action> [options] -- [args...]
actions:
foo action foo
bar action bar
Options:
--baz, -b <val> option baz
--help, -h show help info
like this
-- [args...] other args
API Reference
The API reference is written in TypeScript style.
class Args {
constructor(
actions: string[],
options: Map<string, string[]>,
rest: string[]
);
readonly actions: string[];
readonly options: Map<string, string[]>;
readonly rest: string[];
/**
* A utility method that returns
* the specific option if it exists
* or an empty array otherwise
*/
getOption(name: string): string[];
}
interface Args {
actions: string[];
options: Map<string, string[]>;
rest: string[];
}
/**
* Parse arguments from the given array of strings
* @example
* ```js
* const rawArgs = ['foo', '--bar', '-ac', '666', '--', '10', '11'],
* optionAliases = new Map([['-a', '--baz']]);
*
* console.log(parse(rawArgs, optionAliases));
* // {
* // actions: ['foo'],
* // options: Map {
* // '--bar' => [],
* // '--baz' => [],
* // '-c' => ['666']
* // },
* // rest: ['10', '11']
* // }
* ```
*/
function parse(
rawArgs: string[],
optionAliases?: Map<string, string>
): Args;
interface ActionDefinition {
name: string;
help?: string;
}
interface OptionDefinition {
name: string;
alias?: string | null;
value?: string;
help?: string;
}
interface RestDefinition {
value?: string;
help?: string;
}
type ProgramOptions = Partial<{
title: string;
helpInfoIndent: number;
helpInfoGap: number;
ignoreUnknownActions: boolean;
ignoreUnknownOptions: boolean;
}>;
class Program {
constructor(name: string, options?: Readonly<ProgramOptions>);
/**
* The name/title of the program
* (displayed in built-in help info)
*/
readonly name: string;
title: string;
/**
* Style parameters of built-in help info
*/
helpInfoIndent: number;
helpInfoGap: number;
/**
* Whether to ignore undefined actions/options
* (By default, undefined options will
* cause the parsing promise to be rejected
* but unknown actions won't)
*/
ignoreUnknownActions: boolean;
ignoreUnknownOptions: boolean;
/**
* Register a action, an option or rest options
*/
action(definition: ActionDefinition): this;
option(definition: OptionDefinition): this;
rest(description: RestDefinition | null): this;
/**
* Parse the arguments
* @returns a promise solved with parsed args on success
* or rejected on unknown actions/options
*/
parse(rawArgs: string[]): Promise<Args>;
/**
* Display built-in help info
* (the help info is generated from action and
* option definitions; you can append other help
* info after this like the example below)
* @example
* ```js
* program.parse(process.argv)
* .then(args => {
* if (args.options.has('--help')) {
* program.help();
* console.log('\nExamples');
* console.log(' my-cli foo --bar');
* } else {
* // ...
* }
* }, err => {
* // ...
* });
* ```
*/
help(): void;
}