Created API/Shell (markdown)

API-Shell.md

@@ -0,0 +1,29 @@
+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.