Differences

This shows you the differences between two versions of the page.

--- api:shell:zh [2022/08/11 10:46]
fight_xing created
+++ api:shell:zh [2023/12/01 06:07] (current)
hfsr [Shell API]
@@ Line 1: / Line 1: @@
 Shell API
 ========
+此API提供了与shell相关的功能，例如shell的当前工作目录、程序查找路径和别名。
-**本篇文章的部分/全部内容还没有进行翻译。**
-This API provides shell related functionality, such as the current working directory, program search path and aliases for the shell.
 - `shell.getAlias(alias: string): string`
-  Gets the value of a specified alias, if any. If there is no such alias returns `nil`.
+  获取指定别名的值（若存在），若不存在此别名则返回`nil`。
+\\
 - `shell.setAlias(alias: string, value: string or nil)`
-  Defines a new alias or updates an existing one. Pass `nil` as the value to remove an alias. Note that aliases are not limited to program names, you can include parameters as well. For example, `view` is a default alias for `edit -r`.
+  定义一条新别名，或更新一条现存别名。传递`nil`作为参数即可移除一条别名。请注意别名不仅限于程序名，也可以包含参数。例如，默认情况下`view`就是`edit -r`的别名。
+\\
 - `shell.aliases(): function`
-  Returns an iterator over all known aliases.
+  返回一个迭代器，遍历所有已知别名。
+\\
 - `shell.getWorkingDirectory(): string`
-  Gets the path to the current working directory. This is an alias for `os.getenv("PWD")`.
+  获取指向当前工作目录的路径。此函数为`os.getenv("PWD")`的别名。
+\\
 - `shell.setWorkingDirectory(dir: string)`
-  Sets the current working directory. This is a checked version of `os.setenv("PWD", dir)`.
+  设定当前工作目录。此函数为`os.setenv("PWD", dir)`的经校验版本。
+\\
 - `shell.getPath(): string`
-  Gets the search path used by `shell.resolve`. This can contain multiple paths, separated by colons (`:`).
+  获取`shell.resolve`使用的搜索路径。此结果可能包含多条路径，中间用冒号(`:`)隔开。
-  This is an alias for `os.getenv("PATH")`.
+  此函数为 `os.getenv("PATH")` 的别名。
+\\
 - `shell.setPath(value: string)`
-  Sets the search path. Note that this will replace the previous search paths. To add a new path to the search paths, do this:
+  设定搜索路径。请注意此操作将会覆盖当前的搜索路径。要添加新路径，请执行：`shell.setPath(shell.getPath() .. ":/some/path")`
-  `shell.setPath(shell.getPath() .. ":/some/path")`
+  此函数为`os.setenv("PATH", value)`的别名。
-  This is an alias for `os.setenv("PATH", value)`.
+\\
 - `shell.resolve(path: string[, ext: string]): string`
-  Tries to "resolve" a path, optionally also checking for files with the specified extension, in which case `path` would only contain the *name*. This first searches the working directory, then all entries in the search path (see `getPath`/`setPath`).
+  尝试“解析”一条路径，可选是否同时检查带指定后缀的文件，此时`path`中只应当包含**文件名**（不含后缀）。
-  If no file with the exact specified name exists and an extension is provided, it will also check for a file with that name plus the specified extension, i.e. for `path .. "." .. ext`.
+  此函数会首先在工作目录中进行查找，然后查找搜索路径的所有条目（参见 `getPath`/`setPath` ）。
+  若不存在名称与给定值精确匹配的文件，且给出了扩展名，此函数还会检查是否存在名称为给定名称加上给定后缀的文件，即 `path .. "." .. ext`。
+\\
 - `shell.execute(command: string, env: table[, ...]): boolean ...`
-  Runs the specified command. This runs the default shell (see `os.getenv("SHELL")`) and passes the command to it. `env` is the environment table to use for the shell, and thus for the called program, in case you wish to sandbox it or avoid it cluttering the caller's namespace. Additional arguments are passed directly to the first program started based on the command, so you can pass non-string values to programs.
+  运行给定命令。此函数会运行默认shell（参见`os.getenv("SHELL")`）并将命令作为参数传递给它。
-  Returns values similar to `pcall` and `coroutine.resume`: the first returned value is a boolean indicating success or error. In case of errors, the second returned value is a detailed error message. Otherwise the remaining returned values are the values that were returned by the specified program when it terminated.
+  `env`是提供给shell使用的环境表，以备你希望在沙盒环境中运行程序，或者防止程序污染调用者的命名空间。额外参数会被直接传递给基于给定命令启动的第一个程序，因此你可以向程序传递非字符串值。
+  函数的返回值类似于`pcall`和`coroutine.resume`：第一个返回值为布尔值，代表了执行是否成功。当发生错误时，第二个返回值为详细报错信息。其他情况下，第一条之后的返回值均为指定程序结束后返回的结果。
+\\
 - `shell.parse(...): table, table`
-  Utility methods intended for programs to parse their arguments. Will return two tables, the first one containing any "normal" parameters, the second containing "options". Options are indicated by a leading `-`, and all options must only be a single character, since multiple characters following a single `-` will be interpreted as multiple options. Options specified with 2 dashes are not split and can have multiple letters. Also, 2-dash options can be given values by using an equal sign. The following examples all assume the script `program` parses the options using `local args, ops = shell.parse(...)`.
+  让程序用于解析自身参数的实用性方法。它将会返回两个表，第一个表中包含了“普通”参数，第二个表中包含了“选项”。
+  选项的开头有`-`进行标记，所有的选项都只能为单个字母长，因为一个`-`后面跟着多个字母会被认为是多个选项。以两个破折号开头的选项不会被拆分，也就可以有多个字符长。并且，双破折号的选项还可以使用等于号赋值。下列样例均假定脚本`program`使用`local args, ops = shell.parse(...)`解析选项。
-  `program`
+\\
+  例1：`program`
-  # `args` is `{}`
+  # `args`为`{}`
+  # `ops`为`{}`
-  # `ops` is `{}`.
+\\
+  例2：`program -abC -d arg1 arg2`
-  `program -abC -d arg1 arg2`
+  # `args`为`{"arg1", "arg2"}`
+  # `ops`为`{a=true,b=true,C=true,d=true}`
-  # `args` is `{"arg1", "arg2"}`
+\\
+  例3：`program -abC --dog arg1 arg2`
-  # `ops` is `{a=true,b=true,C=true,d=true}`.
+  # `args`为`{"arg1", "arg2"}`
+  # `ops`为`{a=true,b=true,C=true,dog=true}`
-  `program -abC --dog arg1 arg2`
+\\
+  例4：`program -abC --dog=foo arg1 arg2`
-  # `args` is `{"arg1", "arg2"}`
+  # `args`为`{"arg1", "arg2"}`
+  # `ops`为`{a=true,b=true,C=true,dog="foo"}`
-  # `ops` is `{a=true,b=true,C=true,dog=true}`.
+\\
+  在下一个样例中，请注意 `dog` 前面的单破折号。这使得后续所有字符均被解析为单独字符。
-  `program -abC --dog=foo arg1 arg2`
+\\
+  例5：`program -abC -dog=foo arg1 arg2`
-  # `args` is `{"arg1", "arg2"}`
+  # `args`为`{"arg1", "arg2"}`
+  # `ops`为`{a=true,b=true,C=true,d=true,g=true,["="]=true,f=true,o=true}`
-  # `ops` is `{a=true,b=true,C=true,dog="foo"}`.
-  On this next example, notice the single dash before `dog`, this causes all of the token to be parsed as single chars.
-  `program -abC -dog=foo arg1 arg2`
-  # `args` is `{"arg1", "arg2"}`
-  # `ops` is `{a=true,b=true,C=true,d=true,g=true,["="]=true,f=true,o=true}`.