From 3b0127b1906ff268d42640b59f106d283c810710 Mon Sep 17 00:00:00 2001 From: oGsLP <1145234011@qq.com> Date: Thu, 8 Aug 2019 14:26:26 +0800 Subject: [PATCH] update Readme_zh-CN to v3.0.0 and modify some old translation problems --- Readme_zh-CN.md | 238 ++++++++++++++++++++++++++++-------------------- 1 file changed, 141 insertions(+), 97 deletions(-) diff --git a/Readme_zh-CN.md b/Readme_zh-CN.md index 10bbd2ce1..664833cc5 100644 --- a/Readme_zh-CN.md +++ b/Readme_zh-CN.md @@ -1,9 +1,9 @@ # Commander.js - -[![Build Status](https://api.travis-ci.org/tj/commander.js.svg)](http://travis-ci.org/tj/commander.js) +[![Build Status](https://api.travis-ci.org/tj/commander.js.svg?branch=master)](http://travis-ci.org/tj/commander.js) [![NPM Version](http://img.shields.io/npm/v/commander.svg?style=flat)](https://www.npmjs.org/package/commander) -[![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://www.npmjs.org/package/commander) +[![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://npmcharts.com/compare/commander?minimal=true) +[![Install Size](https://packagephobia.now.sh/badge?p=commander)](https://packagephobia.now.sh/result?p=commander) [node.js](http://nodejs.org) 命令行接口的完整解决方案，灵感来自 Ruby 的 [commander](https://github.com/commander-rb/commander)。 @@ -54,7 +54,7 @@ if (program.small) console.log('- small pizza size'); if (program.pizzaType) console.log(`- ${program.pizzaType}`); ``` -``` +```bash $ pizza-options -d { debug: true, small: undefined, pizzaType: undefined } pizza details: @@ -87,7 +87,7 @@ program.parse(process.argv); console.log(`cheese: ${program.cheese}`); ``` -``` +```bash $ pizza-options cheese: blue $ pizza-options --cheese stilton @@ -96,29 +96,37 @@ cheese: stilton ### 其他选项类型，可忽略的布尔值和标志值 -选项的值为 boolean 类型时，可以在其长名字前加`no-`使默认值为true，如果传了这个选项则值为false。 +选项的值为boolean类型时，可以在其长名字前加`no-`规定这个选项值为false。 +单独定义同样使选项默认为真。 + +如果你先定义了`--foo`，再加上`--no-foo`并不会改变它本来的默认值。你可以为一个boolean类型的标识(flag)指定一个默认的布尔值，从命令行里可以重写它的值。 ```js const program = require('commander'); program - .option('-n, --no-sauce', 'Remove sauce') + .option('--no-sauce', 'Remove sauce') + .option('--cheese ', 'cheese flavour', 'mozzarella') + .option('--no-cheese', 'plain with no cheese') .parse(process.argv); -if (program.sauce) console.log('you ordered a pizza with sauce'); -else console.log('you ordered a pizza without sauce'); +const sauceStr = program.sauce ? 'sauce' : 'no sauce'; +const cheeseStr = (program.cheese === false) ? 'no cheese' : `${program.cheese} cheese`; +console.log(`You ordered a pizza with ${sauceStr} and ${cheeseStr}`); ``` ``` -$ pizza-options -you ordered a pizza with sauce +$ pizza-options +You ordered a pizza with sauce and mozzarella cheese $ pizza-options --sauce -error: unknown '--sauce' -$ pizza-options --no-sauce -you ordered a pizza without sauce +error: unknown option '--sauce' +$ pizza-options --cheese=blue +You ordered a pizza with sauce and blue cheese +$ pizza-options --no-sauce --no-cheese +You ordered a pizza with no sauce and no cheese ``` -您可以指定一个用作标志的选项，它可以接受值（使用方括号声明，即传值不是必须的）。 +你可以指定一个用作标志的选项，它可以接受值（使用方括号声明，即传值不是必须的）。 ```js const program = require('commander'); @@ -133,6 +141,15 @@ else if (program.cheese === true) console.log('add cheese'); else console.log(`add cheese type ${program.cheese}`); ``` +```bash +$ pizza-options +no cheese +$ pizza-options --cheese +add cheese +$ pizza-options --cheese mozzarella +add cheese type mozzarella +``` + ## 自定义选项处理 你可以指定一个函数来处理选项的值，接收两个参数：用户传入的值、上一个值(previous value)，它会返回新的选项值。 @@ -178,7 +195,7 @@ if (program.collect.length > 0) console.log(program.collect); if (program.list !== undefined) console.log(program.list); ``` -``` +```bash $ custom -f 1e2 float: 100 $ custom --integer 2 @@ -196,71 +213,76 @@ $ custom --list x,y,z `version`方法会处理显示版本命令，默认选项标识为`-V`和`--version`，当存在时会打印版本号并退出。 ```js - program.version('0.0.1'); +program.version('0.0.1'); ``` -``` - $ ./examples/pizza -V - 0.0.1 +```bash +$ ./examples/pizza -V +0.0.1 ``` -你可以自定义标识，通过给`version`方法再传递一个参数，语法给`option`方法一致。版本标识名字可以是任意的，但是必须要有长名字。 +你可以自定义标识，通过给`version`方法再传递一个参数，语法与`option`方法一致。版本标识名字可以是任意的，但是必须要有长名字。 -``` -program.version('0.0.1', '-v, --version'); +```bash +program.version('0.0.1', '-v, --vers', 'output the current version'); ``` -## 指定命令选项 +## Commands -可以给命令绑定选项。 +你可以使用 `.command` 为你的最高层命令指定子命令。 +这里我们有两种方法可以实现：为命令绑定一个操作处理程序(action handler)，或者将命令单独写成一个可执行文件(稍后我们会详细讨论)。在 `.command` 的第一个参数你可以指定命令的名字以及任何参数。参数可以是 ``(必须的) or `[optional]`(可选的) , 并且最后一个参数也可以是 `variadic...`(可变的). -```js -#!/usr/bin/env node - -var program = require('commander'); +For example: +```js +// 通过绑定操作处理程序实现命令 (这里description的定义和 `.command` 是分开的) +// 返回新生成的命令(即该子命令)以供继续配置 program - .command('rm ') - .option('-r, --recursive', 'Remove recursively') - .action(function (dir, cmd) { - console.log('remove ' + dir + (cmd.recursive ? ' recursively' : '')) - }) + .command('clone [destination]') + .description('clone a repository into a newly created directory') + .action((source, destination) => { + console.log('clone command called'); + }); -program.parse(process.argv) +// 通过单独分离的可执行文件实现命令 (注意这里description是作为 `.command` 的第二个参数) +// 返回最顶层的命令以供继续添加子命令 +program + .command('start ', 'start named service') + .command('stop [service]', 'stop named service, or all if no name supplied'); ``` -使用该命令时，将验证命令的选项。任何未知选项都将报告为错误。但是，如果基于操作的命令没有定义action，则不验证选项。 +### 指定参数语法 -## 正则表达式 +你可以通过使用 `.arguments` 来为最顶级命令指定参数，对于子命令来说参数都包括在 `.command` 调用之中了。尖括号(e.g. ``)意味着必须的输入，而方括号(e.g. `[optional]`)则是代表了可选的输入 ```js +var program = require('commander'); + program .version('0.1.0') - .option('-s --size ', 'Pizza size', /^(large|medium|small)$/i, 'medium') - .option('-d --drink [drink]', 'Drink', /^(coke|pepsi|izze)$/i) - .parse(process.argv); - -console.log(' size: %j', program.size); -console.log(' drink: %j', program.drink); -``` + .arguments(' [env]') + .action(function (cmd, env) { + cmdValue = cmd; + envValue = env; + }); -注：上面代码如果size选项传入的值和正则不匹配，则值为medium(默认值)。drink选项和正则不匹配，值为true。 +program.parse(process.argv); -## 可变参数 +if (typeof cmdValue === 'undefined') { + console.error('no command given!'); + process.exit(1); +} +console.log('command:', cmdValue); +console.log('environment:', envValue || "no environment given"); +``` - 一个命令的最后一个参数可以是可变参数, 并且只有最后一个参数可变。为了使参数可变，你需要在参数名后面追加 `...`。 下面是个示例： +一个命令有且仅有最后一个参数是可变的，你需要在参数名后加上 `...` 来使它可变，例如 ```js -#!/usr/bin/env node - -/** - * Module dependencies. - */ - var program = require('commander'); program - .version('0.0.1') + .version('0.1.0') .command('rmdir [otherDirs...]') .action(function (dir, otherDirs) { console.log('rmdir %s', dir); @@ -273,79 +295,78 @@ program program.parse(process.argv); ``` -可变参数的值以 `数组` 的形式保存。如上所示，在传递给你的 action 的参数和 `program.args` 中的值都是如此。 -## 指定参数的语法 +可变参数的值以 `数组` 的形式传递给操作处理程序。(这点同样适用于 `program.args` ) -```js -#!/usr/bin/env node +### 操作处理程序(Action handler) (子)命令 -var program = require('../'); +你可以使用操作处理程序为一个命令增加选项options。 +操作处理程序会接收每一个你声明的参数的变量，和一个额外的参数——这个命令对象自己。这个命令的参数包括添加的命令特定选项的值。 -program - .version('0.0.1') - .arguments(' [env]') - .action(function (cmd, env) { - cmdValue = cmd; - envValue = env; - }); +```js +var program = require('commander'); -program.parse(process.argv); +program + .command('rm ') + .option('-r, --recursive', 'Remove recursively') + .action(function (dir, cmdObj) { + console.log('remove ' + dir + (cmdObj.recursive ? ' recursively' : '')) + }) -if (typeof cmdValue === 'undefined') { - console.error('no command given!'); - process.exit(1); -} -console.log('command:', cmdValue); -console.log('environment:', envValue || "no environment given"); +program.parse(process.argv) ``` -尖括号（例如 ``）代表必填输入，方括号（例如 `[env]`）代表可选输入。 -## Git 风格的子命令 +当一个命令在命令行上被使用时，它的选项必须是合法的。使用任何未知的选项会报错。然而如果一个基于操作的命令没有定义任何操作，那么这些选项是不合法的。 + +定义配置选项可以随着调用 `.command()` 传递。 +为 `opts.noHelp` 指定 `true` 则该命令不会出现生成的帮助输出里。 + +### Git 风格的子命令 + +当 `.command()` 带有描述参数时，不能采用 `.action(callback)` 来处理子命令，否则会出错。这告诉 commander，你将采用单独的可执行文件作为子命令，就像 `git(1)` 和其他流行的工具一样。 +Commander 将会尝试在入口脚本（例如 `./examples/pm`）的目录中搜索 `program-command` 形式的可执行文件，例如 `pm-install`, `pm-search`。 +你可以使用配置选项 `executableFile` 来指定一个自定义的名字 + +你可以在可执行文件里处理可执行(子)命令的选项，而不必在顶层声明它们 ```js // file: ./examples/pm -var program = require('..'); +var program = require('commander'); program - .version('0.0.1') + .version('0.1.0') .command('install [name]', 'install one or more packages') .command('search [query]', 'search with optional query') + .command('update', 'update installed packages', {executableFile: 'myUpdateSubCommand'}) .command('list', 'list packages installed', {isDefault: true}) .parse(process.argv); ``` -当 `.command()` 带有描述参数时，不能采用 `.action(callback)` 来处理子命令，否则会出错。这告诉 commander，你将采用单独的可执行文件作为子命令，就像 `git(1)` 和其他流行的工具一样。 -Commander 将会尝试在入口脚本（例如 `./examples/pm`）的目录中搜索 `program-command` 形式的可执行文件，例如 `pm-install`, `pm-search`。 +定义配置选项可以随着调用 `.command()` 传递。为 `opts.noHelp` 指定 `true` 则该命令不会出现生成的帮助输出里。指定 `opts.isDefault` 为 `true` 将会在没有其它子命令指定的情况下，执行该子命令。 -你可以在调用 `.command()` 时传递选项。指定 `opts.noHelp` 为 `true` 将从生成的帮助输出中剔除该选项。指定 `opts.isDefault` 为 `true` 将会在没有其它子命令指定的情况下，执行该子命令。 +使用 `executableFile` 指定一个名字会覆盖默认构造的名称 如果你打算全局安装该命令，请确保可执行文件有对应的权限，例如 `755`。 -### `--harmony` - -您可以采用两种方式启用 `--harmony`： -* 在子命令脚本中加上 `#!/usr/bin/env node --harmony`。注意一些系统版本不支持此模式。 -* 在指令调用时加上 `--harmony` 参数，例如 `node --harmony examples/pm publish`。`--harmony` 选项在开启子进程时会被保留。 ## 自动化帮助信息 --help 帮助信息是 commander 基于你的程序自动生成的，下面是 `--help` 生成的帮助信息： -``` +```bash $ ./examples/pizza --help Usage: pizza [options] An application for pizzas ordering Options: - -h, --help output usage information -V, --version output the version number -p, --peppers Add peppers -P, --pineapple Add pineapple -b, --bbq Add bbq sauce - -c, --cheese Add the specified type of cheese [marble] + -c, --cheese Add the specified type of cheese (default: "marble") -C, --no-cheese You do not want any cheese + -h, --help output usage information ``` ## 自定义帮助 @@ -401,7 +422,7 @@ Examples: ## .outputHelp(cb) -不退出输出帮助信息。 +输出帮助信息的同时不退出。 可选的回调可在显示帮助文本后处理。 如果你想显示默认的帮助（例如，如果没有提供命令），你可以使用类似的东西： @@ -410,18 +431,26 @@ var program = require('commander'); var colors = require('colors'); program - .version('0.0.1') + .version('0.1.0') .command('getstream [url]', 'get stream URL') .parse(process.argv); - if (!process.argv.slice(2).length) { - program.outputHelp(make_red); - } +if (!process.argv.slice(2).length) { + program.outputHelp(make_red); +} function make_red(txt) { - return colors.red(txt); // 在控制台上显示红色的帮助文本 + return colors.red(txt); //display the help text in red on the console } ``` +## .helpOption(flags, description) + + 重写覆盖默认的帮助标识和描述 + +```js +program + .helpOption('-e, --HELP', 'read more information'); +``` ## .help(cb) @@ -461,17 +490,27 @@ npm install --save-dev @types/node ```bash node -r ts-node/register pm.ts ``` - +### Node 选项例如 `--harmony` + +你可以采用两种方式启用 `--harmony`： +* 在子命令脚本中加上 `#!/usr/bin/env node --harmony`。注意一些系统版本不支持此模式。 +* 在指令调用时加上 `--harmony` 参数，例如 `node --harmony examples/pm publish`。`--harmony` 选项在开启子进程时会被保留。 + +### Node 调试 + +如果你在使用 node inspector的 `node -inspect` 等命令来[调试](https://nodejs.org/en/docs/guides/debugging-getting-started/) git风格的可执行命令， +对于生成的子命令，inspector端口递增1。 + ## 例子 ```js var program = require('commander'); program - .version('0.0.1') + .version('0.1.0') .option('-C, --chdir ', 'change the working directory') .option('-c, --config ', 'set config path. defaults to ./deploy.conf') - .option('-T, --no-tests', 'ignore test hook') + .option('-T, --no-tests', 'ignore test hook'); program .command('setup [env]') @@ -513,3 +552,8 @@ program.parse(process.argv); [MIT](https://github.com/tj/commander.js/blob/master/LICENSE) +## 支持 + +[专业支持的commander现在已经可用！](https://tidelift.com/subscription/pkg/npm-commander?utm_source=npm-commander&utm_medium=referral&utm_campaign=readme) + +Tidelift为软件开发团队提供了购买和维护其软件的单一来源，并由最了解软件的专家提供专业级保证，同时与现有工具无缝集成。 \ No newline at end of file