This shows you the differences between two versions of the page.
Both sides previous revision Previous revision | |||
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 | Shell API | ||
======== | ======== | ||
- | 此API提供了与shell相关的功能,例如shell的当前工作目录、程序查找目录和别名。 | + | 此API提供了与shell相关的功能,例如shell的当前工作目录、程序查找路径和别名。 |
- `shell.getAlias(alias: string): string` | - `shell.getAlias(alias: string): string` | ||
- | 获取指定别名的值(存在的话),若不存在此别名则返回 `nil`。 | + | 获取指定别名的值(若存在),若不存在此别名则返回`nil`。 |
+ | \\ | ||
- `shell.setAlias(alias: string, value: string or nil)` | - `shell.setAlias(alias: string, value: string or nil)` | ||
- | 定义一条新别名,或更新一条现存别名。传递`nil`作为参数以移除一条别名。请注意别名不仅限于程序名,也可以包含参数。例如,`view` 就是 `edit -r` 的默认别名。 | + | 定义一条新别名,或更新一条现存别名。传递`nil`作为参数即可移除一条别名。请注意别名不仅限于程序名,也可以包含参数。例如,默认情况下`view`就是`edit -r`的别名。 |
+ | \\ | ||
- `shell.aliases(): function` | - `shell.aliases(): function` | ||
- | 返回所有已知别名的迭代器。 | + | 返回一个迭代器,遍历所有已知别名。 |
+ | \\ | ||
- `shell.getWorkingDirectory(): string` | - `shell.getWorkingDirectory(): string` | ||
- | 获取指向当前工作目录的路径。此函数为 `os.getenv("PWD")` 的别名。 | + | 获取指向当前工作目录的路径。此函数为`os.getenv("PWD")`的别名。 |
+ | \\ | ||
- `shell.setWorkingDirectory(dir: string)` | - `shell.setWorkingDirectory(dir: string)` | ||
- | 设定当前工作目录。此函数为 `os.setenv("PWD", dir)` 的经校验版本。 | + | 设定当前工作目录。此函数为`os.setenv("PWD", dir)`的经校验版本。 |
+ | \\ | ||
- `shell.getPath(): string` | - `shell.getPath(): string` | ||
- | 获取 `shell.resolve` 使用的搜索路径。此结果可能包含多条路径,中间用冒号(`:`)隔开。 | + | 获取`shell.resolve`使用的搜索路径。此结果可能包含多条路径,中间用冒号(`:`)隔开。 |
- | 此函数为 `os.getenv("PATH")` 的别名。 | + | 此函数为 `os.getenv("PATH")` 的别名。 |
+ | \\ | ||
- `shell.setPath(value: string)` | - `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` | - `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.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` | - `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}`. | + | |