Shell API

此API提供了与shell相关的功能,例如shell的当前工作目录、程序查找路径和别名。

  • shell.getAlias(alias: string): string
    获取指定别名的值(若存在),若不存在此别名则返回nil

  • shell.setAlias(alias: string, value: string or nil)
    定义一条新别名,或更新一条现存别名。传递nil作为参数即可移除一条别名。请注意别名不仅限于程序名,也可以包含参数。例如,默认情况下view就是edit -r的别名。

  • shell.aliases(): function
    返回一个迭代器,遍历所有已知别名。

  • shell.getWorkingDirectory(): string
    获取指向当前工作目录的路径。此函数为os.getenv("PWD")的别名。

  • shell.setWorkingDirectory(dir: string)
    设定当前工作目录。此函数为os.setenv("PWD", dir)的经校验版本。

  • shell.getPath(): string
    获取shell.resolve使用的搜索路径。此结果可能包含多条路径,中间用冒号(:)隔开。
    此函数为 os.getenv("PATH") 的别名。

  • shell.setPath(value: string)
    设定搜索路径。请注意此操作将会覆盖当前的搜索路径。要添加新路径,请执行:shell.setPath(shell.getPath() .. ":/some/path")
    此函数为os.setenv("PATH", value)的别名。

  • shell.resolve(path: string[, ext: string]): string
    尝试“解析”一条路径,可选是否同时检查带指定后缀的文件,此时path中只应当包含文件名(不含后缀)。
    此函数会首先在工作目录中进行查找,然后查找搜索路径的所有条目(参见 getPath/setPath )。
    若不存在名称与给定值精确匹配的文件,且给出了扩展名,此函数还会检查是否存在名称为给定名称加上给定后缀的文件,即 path .. "." .. ext

  • shell.execute(command: string, env: table[, ...]): boolean ...
    运行给定命令。此函数会运行默认shell(参见os.getenv("SHELL"))并将命令作为参数传递给它。
    env是提供给shell使用的环境表,以备你希望在沙盒环境中运行程序,或者防止程序污染调用者的命名空间。额外参数会被直接传递给基于给定命令启动的第一个程序,因此你可以向程序传递非字符串值。
    函数的返回值类似于pcallcoroutine.resume:第一个返回值为布尔值,代表了执行是否成功。当发生错误时,第二个返回值为详细报错信息。其他情况下,第一条之后的返回值均为指定程序结束后返回的结果。

  • shell.parse(...): table, table
    让程序用于解析自身参数的实用性方法。它将会返回两个表,第一个表中包含了“普通”参数,第二个表中包含了“选项”。
    选项的开头有-进行标记,所有的选项都只能为单个字母长,因为一个-后面跟着多个字母会被认为是多个选项。以两个破折号开头的选项不会被拆分,也就可以有多个字符长。并且,双破折号的选项还可以使用等于号赋值。下列样例均假定脚本program使用local args, ops = shell.parse(...)解析选项。

    例1:program
    # args{}
    # ops{}

    例2:program -abC -d arg1 arg2
    # args{"arg1", "arg2"}
    # ops{a=true,b=true,C=true,d=true}

    例3:program -abC --dog arg1 arg2
    # args{"arg1", "arg2"}
    # ops{a=true,b=true,C=true,dog=true}

    例4:program -abC --dog=foo arg1 arg2
    # args{"arg1", "arg2"}
    # 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}

目录