From 0b0389f2c3d8b5b3d966728d9f7944d24bc56dcc Mon Sep 17 00:00:00 2001 From: Justin Ma Date: Sat, 9 Apr 2022 21:28:54 +0800 Subject: [PATCH] Translate custom commands and aliases to zh-CN from commit: 218f600a9 (#384) * Translate custom commands and aliases to zh-CN from commit: 218f600a9 * Some proofreading and retouching * Change locale name * Add aliases translation --- .vuepress/config.js | 26 +- book/aliases.md | 2 +- book/custom_commands.md | 2 +- {zh-cn => zh-CN}/README.md | 0 {zh-cn => zh-CN}/book/README.md | 0 zh-CN/book/aliases.md | 27 ++ {zh-cn => zh-CN}/book/command_reference.md | 0 {zh-cn => zh-CN}/book/configuration.md | 0 zh-CN/book/custom_commands.md | 353 ++++++++++++++++++ {zh-cn => zh-CN}/book/environment.md | 0 {zh-cn => zh-CN}/book/installation.md | 0 {zh-cn => zh-CN}/book/introduction.md | 0 {zh-cn => zh-CN}/book/loading_data.md | 0 {zh-cn => zh-CN}/book/math.md | 0 {zh-cn => zh-CN}/book/metadata.md | 0 {zh-cn => zh-CN}/book/moving_around.md | 0 {zh-cn => zh-CN}/book/pipeline.md | 10 +- {zh-cn => zh-CN}/book/table_of_contents.md | 0 {zh-cn => zh-CN}/book/thinking_in_nushell.md | 0 {zh-cn => zh-CN}/book/types_of_data.md | 0 {zh-cn => zh-CN}/book/working_with_lists.md | 0 {zh-cn => zh-CN}/book/working_with_strings.md | 0 {zh-cn => zh-CN}/book/working_with_tables.md | 2 +- zh-cn/book/aliases.md | 50 --- 24 files changed, 404 insertions(+), 68 deletions(-) rename {zh-cn => zh-CN}/README.md (100%) rename {zh-cn => zh-CN}/book/README.md (100%) create mode 100644 zh-CN/book/aliases.md rename {zh-cn => zh-CN}/book/command_reference.md (100%) rename {zh-cn => zh-CN}/book/configuration.md (100%) create mode 100644 zh-CN/book/custom_commands.md rename {zh-cn => zh-CN}/book/environment.md (100%) rename {zh-cn => zh-CN}/book/installation.md (100%) rename {zh-cn => zh-CN}/book/introduction.md (100%) rename {zh-cn => zh-CN}/book/loading_data.md (100%) rename {zh-cn => zh-CN}/book/math.md (100%) rename {zh-cn => zh-CN}/book/metadata.md (100%) rename {zh-cn => zh-CN}/book/moving_around.md (100%) rename {zh-cn => zh-CN}/book/pipeline.md (79%) rename {zh-cn => zh-CN}/book/table_of_contents.md (100%) rename {zh-cn => zh-CN}/book/thinking_in_nushell.md (100%) rename {zh-cn => zh-CN}/book/types_of_data.md (100%) rename {zh-cn => zh-CN}/book/working_with_lists.md (100%) rename {zh-cn => zh-CN}/book/working_with_strings.md (100%) rename {zh-cn => zh-CN}/book/working_with_tables.md (99%) delete mode 100644 zh-cn/book/aliases.md diff --git a/.vuepress/config.js b/.vuepress/config.js index 03206baf7e6..cf9ea3e285c 100755 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -25,8 +25,8 @@ module.exports = { title: 'Nushell', description: 'Um novo tipo de shell.', }, - '/zh-cn/': { - lang: 'zh-cn', + '/zh-CN/': { + lang: 'zh-CN', title: 'Nushell', description: '一种新型的外壳。.', }, @@ -382,18 +382,18 @@ module.exports = { // ], }, }, - '/zh-cn/': { + '/zh-CN/': { selectText: '语言', label: '中文', editLinkText: '在GitHub上编辑此页面', nav: [ - { text: '书', link: '/zh-cn/book/' }, + { text: '书', link: '/zh-CN/book/' }, // { text: "Contributor Book", link: "/contributor-book/" }, { text: 'Cookbook', link: '/cookbook/' }, { text: 'Blog', link: '/blog/' }, ], sidebar: { - '/zh-cn/book/': [ + '/zh-CN/book/': [ { title: '入门篇', collapsable: false, @@ -418,16 +418,22 @@ module.exports = { ], }, { - title: '待续', + title: 'Nushell 编程', collapsable: false, children: [ - 'configuration', + 'custom_commands', 'aliases', - 'math', - 'environment', - 'metadata', + // 'operators', + // 'variables_and_subexpressions', + // 'scripts', + // 'modules', ], }, + { + title: '待续', + collapsable: false, + children: ['configuration', 'math', 'environment', 'metadata'], + }, ], }, }, diff --git a/book/aliases.md b/book/aliases.md index e6b91505277..f05c73f5a39 100644 --- a/book/aliases.md +++ b/book/aliases.md @@ -24,4 +24,4 @@ And get the equivalent to having typed `ls -l -a`. ## Persisting -For information about how to persist aliases so that they're visible when you start up Nushell, see the [configuration chapter](configuration.md#startup-commands). +For information about how to persist aliases so that they're visible when you start up Nushell, see the [configuration chapter](configuration.md). diff --git a/book/custom_commands.md b/book/custom_commands.md index 5b3aa673f72..decc8777dc7 100644 --- a/book/custom_commands.md +++ b/book/custom_commands.md @@ -350,4 +350,4 @@ Now, if we call the above command later in a pipeline, we can see what it does w ## Persisting -For information about how to persist custom commands so that they're visible when you start up Nushell, see the [configuration chapter](configuration.md#startup-commands) and add your startup script. +For information about how to persist custom commands so that they're visible when you start up Nushell, see the [configuration chapter](configuration.md) and add your startup script. diff --git a/zh-cn/README.md b/zh-CN/README.md similarity index 100% rename from zh-cn/README.md rename to zh-CN/README.md diff --git a/zh-cn/book/README.md b/zh-CN/book/README.md similarity index 100% rename from zh-cn/book/README.md rename to zh-CN/book/README.md diff --git a/zh-CN/book/aliases.md b/zh-CN/book/aliases.md new file mode 100644 index 00000000000..8a4e24c570f --- /dev/null +++ b/zh-CN/book/aliases.md @@ -0,0 +1,27 @@ +# 别名 + +Nushell 中的别名提供了一种简单的文本替换方式，这允许你为一个较长的命令创建一个简写名称，包括其默认参数。 + +例如，让我们创建一个名为 `ll` 的别名，它将展开为 `ls -l`。 + +```bash +> alias ll = ls -l +``` + +我们可以通过别名来调用它： + +```bash +> ll +``` + +一旦我们这样做了，就如同我们输入了 `ls -l` 一样。这也允许我们传入标志或位置参数。例如，我们现在也可以这样写： + +``` +> ll -a +``` + +可得到与输入了`ls -l -a`一样的结果。 + +## 持久化 + +关于如何持久化别名，以便在你启动 Nushell 时它们是可用的，请参考[配置章节](configuration.md)。 diff --git a/zh-cn/book/command_reference.md b/zh-CN/book/command_reference.md similarity index 100% rename from zh-cn/book/command_reference.md rename to zh-CN/book/command_reference.md diff --git a/zh-cn/book/configuration.md b/zh-CN/book/configuration.md similarity index 100% rename from zh-cn/book/configuration.md rename to zh-CN/book/configuration.md diff --git a/zh-CN/book/custom_commands.md b/zh-CN/book/custom_commands.md new file mode 100644 index 00000000000..e5565baeb68 --- /dev/null +++ b/zh-CN/book/custom_commands.md @@ -0,0 +1,353 @@ +# 自定义命令 + +Nu 具备组合长管道的能力使你对数据和系统有很强的控制力，但它的代价是需要大量的键盘输入。不过理想情况下，你可以保存精心设计的管道以便反复使用。 + +这就是自定义命令(custom commands)的作用。 + +下面看一个自定义命令的例子： + +```bash +def greet [name] { + echo "hello" $name +} +``` + +在这个定义中，我们定义了`greet`命令，它需要一个参数`name`。在这个参数后面是自定义命令运行时将执行的代码块。当被调用时，自定义命令将把传递给`name`的值设置为`$name`变量，该变量在块内是可用的。 + +要运行上述命令，我们可以像调用内置命令一样调用它： + +```bash +> greet "world" +``` + +当我们这样做的时候，就会得到输出，如同我们使用内置命令一样： + +``` +───┬─────── + 0 │ hello + 1 │ world +───┴─────── +``` + +## 命令名称 + +在 Nushell 中，命令名是一串字符或一个带引号的字符串。下面是一些有效命令名的例子：`greet`, `get-size`, `mycommand123`, `"mycommand"`, `😊`, 和`123`。 + +_注意：在 Nushell 中，通常的做法是用`-`来分隔命令的多个单词，以提高可读性。_ 例如，使用 `get-size` 而不是 `getsize` 或者 `get_size`。 + +## 子命令 + +你也可以使用空格来定义命令的子命令(subcommand)。例如，如果我们想给`str`添加一个新的子命令，可以通过命名我们的子命令以 "str "开头来做到。比如： + +```bash +def "str mycommand" [] { + echo hello +} +``` + +现在我们可以像调用`str`的内置子命令一样调用我们的自定义命令： + +```bash +> str mycommand +``` + +## 参数类型 + +在定义自定义命令时，你可以为每个参数命名并选择性地设置其类型。例如，你可以把上面的内容写成： + +```bash +def greet [name: string] { + echo "hello" $name +} +``` + +参数的类型是可选的。Nushell 支持不添加类型，此时会把参数类型当作`any`。如果你在参数上标注了一个类型，Nushell 将在你调用函数的时候检查该类型。 + +例如，假设你需要输入一个`int`类型： + +```bash +def greet [name: int] { + echo "hello" $name +} + +greet world +``` + +如果我们尝试运行上述内容，Nushell 会告诉我们，类型不匹配： + +``` +error: Type Error + ┌─ shell:6:7 + │ +5 │ greet world + │ ^^^^^ Expected int, found world +``` + +这可以帮助指导你的用户只使用支持的类型来调用你所定义的命令。 + +目前可以支持的类型是（从 0.59.0 版本开始）： + +- `any` +- `block` +- `cell-path` +- `duration` +- `path` +- `expr` +- `filesize` +- `glob` +- `int` +- `math` +- `number` +- `operator` +- `range` +- `cond` +- `bool` +- `signature` +- `string` +- `variable` + +## 可选位置参数 + +默认情况下，位置参数(positional parameters)是必须的。如果没有传递位置参数，我们将遇到一个报错： + +``` + × Missing required positional argument. + ╭─[entry #23:1:1] + 1 │ greet + · ▲ + · ╰── missing name + ╰──── + help: Usage: greet +``` + +我们可以在一个位置参数的名字后面加上一个问号（`?`），将其标记为可选参数。比如： + +```bash +def greet [name?: string] { + echo "hello" $name +} + +greet +``` + +使一个位置参数成为可选参数并不改变它在命令体中被访问的名称。如上例所示，尽管参数列表中有`?`的后缀，但它仍然以`$name`的形式被访问。 + +当一个可选参数没有被传递，它在命令体中的值等于`null`和`$nothing`。我们可以利用这一点来对没有传递参数的情况进行处理： + +```bash +def greet [name?: string] { + if ($name == null) { + echo "hello, I don't know your name!" + } else { + echo "hello" $name + } +} + +greet +``` + +如果必需的和可选的位置参数一起使用，那么必需的参数必须先出现在定义中。 + +## 标志 + +除了传递位置参数之外, 你还可以通过为自定义命令定义标志(flags)来传递命名参数。 + +比如： + +```bash +def greet [ + name: string + --age: int +] { + echo $name $age +} +``` + +在上面的`greet`定义中，我们定义了`name`位置参数以及`age`标志。这允许`greet`的调用者也可以选择传递`age`参数。 + +你可以用以下方法调用上述内容： + +```bash +> greet world --age 10 +``` + +或者： + +```bash +> greet --age 10 world +``` + +或者甚至完全不使用标志： + +``` +> greet world +``` + +标志也可以指定一个缩写版本，这允许你传递一个更简单的标志，如同传递一个更容易阅读的全写标志那样。 + +让我们扩展前面的例子，为`age`添加一个缩写标志： + +```bash +def greet [ + name: string + --age (-a): int +] { + echo $name $age +} +``` + +_注意：_ 标志是以其全称命名的，所以上面的例子的命令体内需要使用`$age`而不是`$a`。 + +现在，我们可以使用缩写标志来调用这个新的定义： + +``` +> greet -a 10 hello +``` + +## 剩余参数 + +在某些情况下, 你可能想定义一个需要任意数量的位置参数的命令。我们可以用一个剩余参数(rest parameter)来实现这一点，通过下面的`...`语法： + +```bash +def greet [...name: string] { + echo "hello all:" + for $n in $name { + echo $n + } +} + +greet earth mars jupiter venus +``` + +我们可以使用任意数量的参数来调用上述`greet`命令的定义，包括完全没有参数，所有的参数都将被收集到`$name`列表中。 + +剩余参数可以和位置参数一起使用： + +```bash +def greet [vip: string, ...name: string] { + echo "hello to our VIP" $vip + echo "and hello to everybody else:" + for $n in $name { + echo $n + } +} + +# $vip $name +# ---- ------------------------ +greet moon earth mars jupiter venus +``` + +## 为命令添加文档 + +为了更好地帮助用户使用你的自定义命令，也可以为其添加额外的命令和参数描述。 + +以我们之前的例子为例： + +```bash +def greet [ + name: string + --age (-a): int +] { + echo $name $age +} +``` + +一旦定义完毕，我们可以运行`help greet`来获得该命令的帮助信息： + +``` +Usage: + > greet {flags} + +Parameters: + + +Flags: + -h, --help: Display this help message + -a, --age +``` + +你可以看到我们定义的参数和标志，以及所有命令都会得到的`-h`帮助标志。 + +为了改进这个帮助，我们可以在定义中加入描述，这些描述将在帮助中显示出来： + +```bash +# A greeting command that can greet the caller +def greet [ + name: string # The name of the person to greet + --age (-a): int # The age of the person +] { + echo $name $age +} +``` + +我们给定义和参数添加的注释会作为描述出现在命令的`help`中。 + +现在，如果我们运行`help greet`，就会得到一些更友好的帮助文本： + +``` +A greeting command that can greet the caller + +Usage: + > greet {flags} + +Parameters: + The name of the person to greet + +Flags: + -h, --help: Display this help message + -a, --age : The age of the person +``` + +## 管道输出 + +自定义命令会像内置命令一样流式输出。例如，假设我们想重构这个管道： + +```bash +> ls | get name +``` + +让我们把[`ls`](/book/commands/ls.md)移到我们编写的命令中： + +```bash +def my-ls [] { ls } +``` + +我们就可以像使用[`ls`](/book/commands/ls.md)一样使用这个命令的输出： + +``` +> my-ls | get name +───┬─────────────────────── + 0 │ myscript.nu + 1 │ myscript2.nu + 2 │ welcome_to_nushell.md +───┴─────────────────────── +``` + +这让我们可以很容易地创建自定义命令并处理它们的输出。注意，我们不像其他语言那样使用返回语句，取而代之的是我们创建管道，而其输出数据流可以连接到其他管道。 + +## 管道输入 + +如同其他命令一样，自定义命令也可以从管道中获取输入，这个输入会自动传递给自定义命令所使用的代码块。 + +让我们创建一个把所有接收值都加倍的命令： + +```bash +def double [] { + each { |it| 2 * $it } +} +``` + +现在，如果我们在一个管道中调用上述命令，就可以看到它对输入的处理结果： + +``` +> [1 2 3] | double +───┬───── + 0 │ 2 + 1 │ 4 + 2 │ 6 +───┴───── +``` + +## 持久化 + +关于如何持久化自定义命令，以便在你启动 Nushell 时它们是可用的，请参阅[配置章节](configuration.md)并添加你的启动脚本。 diff --git a/zh-cn/book/environment.md b/zh-CN/book/environment.md similarity index 100% rename from zh-cn/book/environment.md rename to zh-CN/book/environment.md diff --git a/zh-cn/book/installation.md b/zh-CN/book/installation.md similarity index 100% rename from zh-cn/book/installation.md rename to zh-CN/book/installation.md diff --git a/zh-cn/book/introduction.md b/zh-CN/book/introduction.md similarity index 100% rename from zh-cn/book/introduction.md rename to zh-CN/book/introduction.md diff --git a/zh-cn/book/loading_data.md b/zh-CN/book/loading_data.md similarity index 100% rename from zh-cn/book/loading_data.md rename to zh-CN/book/loading_data.md diff --git a/zh-cn/book/math.md b/zh-CN/book/math.md similarity index 100% rename from zh-cn/book/math.md rename to zh-CN/book/math.md diff --git a/zh-cn/book/metadata.md b/zh-CN/book/metadata.md similarity index 100% rename from zh-cn/book/metadata.md rename to zh-CN/book/metadata.md diff --git a/zh-cn/book/moving_around.md b/zh-CN/book/moving_around.md similarity index 100% rename from zh-cn/book/moving_around.md rename to zh-CN/book/moving_around.md diff --git a/zh-cn/book/pipeline.md b/zh-CN/book/pipeline.md similarity index 79% rename from zh-cn/book/pipeline.md rename to zh-CN/book/pipeline.md index a457cf24a8d..7bac6f57bc8 100644 --- a/zh-cn/book/pipeline.md +++ b/zh-CN/book/pipeline.md @@ -1,6 +1,6 @@ # 管道 -Nu 的核心设计之一是管道，这个设计思想可以追溯到几十年前 Unix 背后的一些原始理念。正如 Nu 拓展了 Unix 的单一字符串数据类型一样，Nu 也扩展了管道的概念，使其不仅仅包括文本。 +Nu 的核心设计之一是管道，这个设计思想可以追溯到几十年前 Unix 背后的一些原始理念。正如 Nu 拓展了 Unix 的单一字符串数据类型一样，Nu 也扩展了管道的概念，使其不仅仅包含文本。 ## 基础 @@ -10,9 +10,9 @@ Nu 的核心设计之一是管道，这个设计思想可以追溯到几十年 > open "Cargo.toml" | inc package.version --minor | save "Cargo_new.toml" ``` -第一条命令：`open "Cargo.toml"` 是一个输入（有时也称为 "源"或 "生产者"），它创建或加载数据，并将其送入管道。管道待处理的值正是来自于输入。像[`ls`](/book/commands/ls.md)这样的命令也是输入，因为它们从文件系统中获取数据，并通过管道发送以便能被后续使用。 +第一条命令：`open "Cargo.toml"` 是一个输入（有时也称为 "源"或 "生产者"），它创建或加载数据，并将其送入管道。管道待处理的值正是来自于此输入。像[`ls`](/book/commands/ls.md)这样的命令也是输入，因为它们从文件系统中获取数据，并通过管道发送以便能被后续使用。 -第二个命令：`inc package.version --minor` 是一个过滤器。过滤器获取所给的数据并对其进行处理。它们可能会改变它（如我们例子中的[`inc`](/book/commands/inc.md)命令），或者在数值通过时对其做其他操作，如记录。 +第二个命令：`inc package.version --minor` 是一个过滤器。过滤器获取所给的数据并对其进行处理。它们可能会修改它（如我们例子中的[`inc`](/book/commands/inc.md)命令），或者在数值通过时对其做其他操作，如记录。 最后一条命令：`save "Cargo_new.toml"` 是一个输出（有时称为 "接收者"）。输出从管道中获取输入，并对其进行一些最终操作。在我们的例子中，我们在最后一步把通过管道的内容保存到一个文件中。还有一些其他类型的输出命令可以获取数值并供用户查看。 @@ -48,7 +48,7 @@ Nu 在两个外部命令之间以与其他 shell 相同的方式处理数据管 ## 幕后解说 -你可能想知道，既然[`ls`](/book/commands/ls.md)是一个输入而不是一个输出，我们为何看到一个表格？其实 Nu 使用了另一个叫做[`table`](/book/commands/table.md)的命令为我们自动添加了这个输出。[`table`](/book/commands/table.md)命令被附加到任何没有输出的管道上，这使得我们可以看到结果。 +你可能想知道，既然[`ls`](/book/commands/ls.md)是一个输入而不是一个输出，我们为何能看到一个表格？其实 Nu 使用了另一个叫做[`table`](/book/commands/table.md)的命令为我们自动添加了这个输出。[`table`](/book/commands/table.md)命令被附加到任何没有输出的管道上，这使得我们可以看到结果。 实际上，该命令： @@ -56,7 +56,7 @@ Nu 在两个外部命令之间以与其他 shell 相同的方式处理数据管 > ls ``` -还有管道： +和以下管道： ``` > ls | table diff --git a/zh-cn/book/table_of_contents.md b/zh-CN/book/table_of_contents.md similarity index 100% rename from zh-cn/book/table_of_contents.md rename to zh-CN/book/table_of_contents.md diff --git a/zh-cn/book/thinking_in_nushell.md b/zh-CN/book/thinking_in_nushell.md similarity index 100% rename from zh-cn/book/thinking_in_nushell.md rename to zh-CN/book/thinking_in_nushell.md diff --git a/zh-cn/book/types_of_data.md b/zh-CN/book/types_of_data.md similarity index 100% rename from zh-cn/book/types_of_data.md rename to zh-CN/book/types_of_data.md diff --git a/zh-cn/book/working_with_lists.md b/zh-CN/book/working_with_lists.md similarity index 100% rename from zh-cn/book/working_with_lists.md rename to zh-CN/book/working_with_lists.md diff --git a/zh-cn/book/working_with_strings.md b/zh-CN/book/working_with_strings.md similarity index 100% rename from zh-cn/book/working_with_strings.md rename to zh-CN/book/working_with_strings.md diff --git a/zh-cn/book/working_with_tables.md b/zh-CN/book/working_with_tables.md similarity index 99% rename from zh-cn/book/working_with_tables.md rename to zh-CN/book/working_with_tables.md index e3e8a0cec8d..74a5d0bb07e 100644 --- a/zh-cn/book/working_with_tables.md +++ b/zh-CN/book/working_with_tables.md @@ -1,6 +1,6 @@ # 处理表格 -在 Nu 中查看数据的一种常见方式是通过表格。Nu 提供了许多处理表格的命令以方便找到你想要的东西以及将数据缩小到你需要的范围。 +在 Nu 中查看数据的一种常见方式是通过表格。Nu 提供了许多处理表格的命令以方便找到你想要的内容以及将数据缩小到你需要的范围。 首先，让我们获得一个可用的表： diff --git a/zh-cn/book/aliases.md b/zh-cn/book/aliases.md deleted file mode 100644 index f41d831d1b0..00000000000 --- a/zh-cn/book/aliases.md +++ /dev/null @@ -1,50 +0,0 @@ -# 别名 - -Nu 编写长管道的能力可以让你对数据和系统进行大量控制，但这需要打很多字。在预想中，你可以保存写好的管道并重复使用。 - -这就是别名要做的事情。 - -一个别名让你为一个命令块创建一个较短的名字。当别名被执行时，它就表现得像你输入了完整的命令块一样。 - -例如： - -``` -> alias ls-names [] { ls | select name } -> ls-names -────┬──────────────────── - # │ name -────┼──────────────────── - 0 │ 404.html - 1 │ CONTRIBUTING.md - 2 │ Gemfile - 3 │ Gemfile.lock - 4 │ LICENSE -``` - -## 参数 - -别名同样可以使用传递给命令块的可选参数。它们中的每一个在块中都是新的变量。 - -``` -> alias e [msg] { echo $msg } -> e "hello world" -hello world -``` - -可以有任意数量的参数。当用户未提供值时，块中的变量将会作为 Nothing 并被移除。 - -## 持久化 - -默认情况下，别名只在当前会话中可用。这对临时性地帮助和测试新别名有用，单如果别名已经能真正地工作了，它们就需要被持久化。要做到它，用 `--save` （或 `-s` 的短形式）来调用 alias 指令。例如： - -``` -alias e --save [msg] { echo $msg } -``` - -别名将被存储在启动配置文件中，你可以使用 `config get startup` 来查看它们。如果你得到一个错误，则是 `startup` 配置文件还不存在。 - -你同样可以直接在 config.toml 文件中编辑别名，例如使用 `vi`： - -``` -config path | vi $it -```