Differences

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

--- api:shell:zh [2023/10/20 06:32]
hfsr [Shell API]
+++ api:shell:zh [2023/12/01 06:07] (current)
hfsr [Shell API]
@@ Line 1: / Line 1: @@
 Shell API
 ========
-此API提供了与shell相关的功能，例如shell的当前工作目录、程序查找目录和别名。
+此API提供了与shell相关的功能，例如shell的当前工作目录、程序查找路径和别名。
 - `shell.getAlias(alias: string): string`
-  获取指定别名的值（存在的话），若不存在此别名则返回 `nil`。
+  获取指定别名的值（若存在），若不存在此别名则返回`nil`。
+\\
 - `shell.setAlias(alias: string, value: string or nil)`
-  定义一条新别名，或更新一条现存别名。传递`nil`作为参数以移除一条别名。请注意别名不仅限于程序名，也可以包含参数。例如，`view` 就是 `edit -r` 的默认别名。
+  定义一条新别名，或更新一条现存别名。传递`nil`作为参数即可移除一条别名。请注意别名不仅限于程序名，也可以包含参数。例如，默认情况下`view`就是`edit -r`的别名。
+\\
 - `shell.aliases(): function`
-  返回所有已知别名的迭代器。
+  返回一个迭代器，遍历所有已知别名。
+\\
 - `shell.getWorkingDirectory(): string`
-  获取指向当前工作目录的路径。此函数为 `os.getenv("PWD")` 的别名。
+  获取指向当前工作目录的路径。此函数为`os.getenv("PWD")`的别名。
+\\
 - `shell.setWorkingDirectory(dir: string)`
-  设定当前工作目录。此函数为 `os.setenv("PWD", dir)` 的经校验版本。
+  设定当前工作目录。此函数为`os.setenv("PWD", dir)`的经校验版本。
+\\
 - `shell.getPath(): string`
-  获取 `shell.resolve` 使用的搜索路径。此结果可能包含多条路径，中间用冒号(`:`)隔开。
+  获取`shell.resolve`使用的搜索路径。此结果可能包含多条路径，中间用冒号(`:`)隔开。
   此函数为 `os.getenv("PATH")` 的别名。
+\\
 - `shell.setPath(value: string)`
-  设定搜索路径。请注意此操作将会覆盖当前的搜索路径。要添加新路径，请执行：
+  设定搜索路径。请注意此操作将会覆盖当前的搜索路径。要添加新路径，请执行：`shell.setPath(shell.getPath() .. ":/some/path")`
-  `shell.setPath(shell.getPath() .. ":/some/path")`
+  此函数为`os.setenv("PATH", value)`的别名。
-  此函数为 `os.setenv("PATH", value)` 的别名。
+\\
 - `shell.resolve(path: string[, ext: string]): string`
-  尝试“解析”一条路径，可选是否同时检查带指定后缀的文件，此时 `path` 只应当包含*文件名*（不含后缀）。此函数会首先搜索工作目录，然后是搜索目录的所有条目（参见 `getPath`/`setPath` ）。
+  尝试“解析”一条路径，可选是否同时检查带指定后缀的文件，此时`path`中只应当包含**文件名**（不含后缀）。
-  若不存在名称与给定值精确匹配的文件，并且给出了扩展名，此函数还会检查是否存在名称为给定名称加上给定后缀的文件，即 `path .. "." .. ext`。
+  此函数会首先在工作目录中进行查找，然后查找搜索路径的所有条目（参见 `getPath`/`setPath` ）。
+  若不存在名称与给定值精确匹配的文件，且给出了扩展名，此函数还会检查是否存在名称为给定名称加上给定后缀的文件，即 `path .. "." .. ext`。
+\\
 - `shell.execute(command: string, env: table[, ...]): boolean ...`
-  运行给定命令。此函数会运行默认shell（参见 `os.getenv("SHELL")`）并将命令作为参数传递给它。  `env` 是提供给shell使用的环境表，以备你希望够在沙盒环境运行被调用程序，或者防止它污染调用者的命名空间。附加参数会被直接传递给基于给定命令启动的第一个程序，因此你可以向程序传递非字符串值。
+  运行给定命令。此函数会运行默认shell（参见`os.getenv("SHELL")`）并将命令作为参数传递给它。
-  函数的返回值类似于 `pcall` 和 `coroutine.resume`：第一个返回值为布尔值，代表了执行是否成功。当发生错误时，第二个返回值为详细报错信息。其他情况下第一条后的返回值均为指定程序结束后返回的返回值。
+  `env`是提供给shell使用的环境表，以备你希望在沙盒环境中运行程序，或者防止程序污染调用者的命名空间。额外参数会被直接传递给基于给定命令启动的第一个程序，因此你可以向程序传递非字符串值。
+  函数的返回值类似于`pcall`和`coroutine.resume`：第一个返回值为布尔值，代表了执行是否成功。当发生错误时，第二个返回值为详细报错信息。其他情况下，第一条之后的返回值均为指定程序结束后返回的结果。
+\\
 - `shell.parse(...): table, table`
-  让程序用于解析自身参数的实用方法。将会返回两个表，第一个表中包含了“普通”参数，第二个表中包含了“选项”。选项的开头有 `-`进行标记，所有的选项都只能为单个字母长，因为一个`-`后面跟着多个字母会被认为是多个选项。以两个破折号开头的选项不会被拆分，也就可以有多个字符长。并且，双破折号的选项还可以使用等于号赋值。下列样例均假定脚本 `program` 使用 `local args, ops = shell.parse(...)` 解析选项。
+  让程序用于解析自身参数的实用性方法。它将会返回两个表，第一个表中包含了“普通”参数，第二个表中包含了“选项”。
+  选项的开头有`-`进行标记，所有的选项都只能为单个字母长，因为一个`-`后面跟着多个字母会被认为是多个选项。以两个破折号开头的选项不会被拆分，也就可以有多个字符长。并且，双破折号的选项还可以使用等于号赋值。下列样例均假定脚本`program`使用`local args, ops = shell.parse(...)`解析选项。
-  例1：`program`
+\\
+  例1：`program`
-  # `args` 为 `{}`
+  # `args`为`{}`
+  # `ops`为`{}`
-  # `ops` 为 `{}`.
+\\
+  例2：`program -abC -d arg1 arg2`
-  例2：`program -abC -d arg1 arg2`
+  # `args`为`{"arg1", "arg2"}`
+  # `ops`为`{a=true,b=true,C=true,d=true}`
-  # `args` 为 `{"arg1", "arg2"}`
+\\
+  例3：`program -abC --dog arg1 arg2`
-  # `ops` 为 `{a=true,b=true,C=true,d=true}`.
+  # `args`为`{"arg1", "arg2"}`
+  # `ops`为`{a=true,b=true,C=true,dog=true}`
-  例3：`program -abC --dog arg1 arg2`
+\\
+  例4：`program -abC --dog=foo arg1 arg2`
-  # `args` 为 `{"arg1", "arg2"}`
+  # `args`为`{"arg1", "arg2"}`
+  # `ops`为`{a=true,b=true,C=true,dog="foo"}`
-  # `ops` 为 `{a=true,b=true,C=true,dog=true}`.
+\\
+  在下一个样例中，请注意 `dog` 前面的单破折号。这使得后续所有字符均被解析为单独字符。
-  例4：`program -abC --dog=foo arg1 arg2`
+\\
+  例5：`program -abC -dog=foo arg1 arg2`
-  # `args` 为 `{"arg1", "arg2"}`
+  # `args`为`{"arg1", "arg2"}`
+  # `ops`为`{a=true,b=true,C=true,d=true,g=true,["="]=true,f=true,o=true}`
-  # `ops` 为 `{a=true,b=true,C=true,dog="foo"}`.
-  在下一个样例中，请注意 `dog` 前面的单破折号。这使得后续所有字符均被解析为单独字符。
-  例5：`program -abC -dog=foo arg1 arg2`
-  # `args` 为 `{"arg1", "arg2"}`
-  # `ops` 为 `{a=true,b=true,C=true,d=true,g=true,["="]=true,f=true,o=true}`.