API Shell

This API provides "session" information, 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.
• shell.setWorkingDirectory(dir: string)
  Sets the current working directory.
• shell.getPath(): string
  Gets the search path used by shell.resolve. This can contain multiple paths, separated by colons (:).
• 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.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(program: string, env: table[, ...]): boolean ...
  Runs a program with the specified name. It applies shell.resolve to the specified path, also searching for files with a .lua file extension. env is the environment table to use for the called program, in case you wish to sandbox it or avoid it cluttering the caller's namespace.
  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
  Returns the path to the currently running program (i.e. the last program started via shell.execute). The level can optionally be provided to get parent programs. It defaults to 1, the current program. 2 is the current program's parent (the one that called shell.execute to start the current program) and so on.