Skip to content

API Shell

Jump to bottom
Vexatos edited this page Jul 13, 2014 · 3 revisions

For those that don't like images: the wiki has moved to a new place, http://ocdoc.cil.li/.
This wiki will no longer be updated.

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.
  • 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.
  • 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").
  • shell.setWorkingDirectory(dir: string)
    Sets the current working directory. This is a checked version of os.setenv("PWD", dir).
  • shell.getPath(): string
    Gets the search path used by shell.resolve. This can contain multiple paths, separated by colons (:).
    This is an alias for 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")
    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).
    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.
  • 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.
    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.
  • 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. For example, if a program is called like this: program -abC -d arg1 arg2
    And program does local args, options = shell.parse(...), then args is the table {"arg1", "arg2"}, and options is the table {a=true,b=true,C=true,d=true}.
  • shell.running([level: number]): string
    Deprecated, use [[process.running|API/Process]].
Clone this wiki locally