shell

The shell API provides access to CraftOS's command line interface.

It allows you to start programs, add completion for a program, and much more.

shell is not a "true" API. Instead, it is a standard program, which its API into the programs that it launches. This allows for multiple shells to run at the same time, but means that the API is not available in the global environment, and so is unavailable to other APIs.

execute(command, ...)Run a program with the supplied arguments.
run(...)Run a program with the supplied arguments.
exit()Exit the current shell.
dir()Return the current working directory.
setDir(dir)Set the current working directory.
path()Set the path where programs are located.
setPath(path)Set the current program path.
resolve(path)Resolve a relative path to an absolute path.
resolveProgram(command)Resolve a program, using the program path and list of aliases.
programs([include_hidden])Return a list of all programs on the path.
complete(sLine)Complete a shell command line.
completeProgram(program)Complete the name of a program.
setCompletionFunction(program, complete)Set the completion function for a program.
getCompletionInfo()Get a table containing all completion functions.
getRunningProgram()Returns the path to the currently running program.
setAlias(command, program)Add an alias for a program.
clearAlias(command)Remove an alias.
aliases()Get the current aliases for this shell.
openTab(...)Open a new multishell tab running a command.
switchTab(id)Switch to the multishell tab with the given index.
execute(command, ...)Source

Run a program with the supplied arguments.

Unlike shell.run, each argument is passed to the program verbatim. While shell.run("echo", "b c") runs echo with b and c, shell.execute("echo", "b c") runs echo with a single argument b c.

Parameters

  1. command string The program to execute.
  2. ... string Arguments to this program.

Returns

  1. boolean Whether the program exited successfully.

Usage

  • Run paint my-image from within your program:

    shell.execute("paint", "my-image")
run(...)Source

Run a program with the supplied arguments.

All arguments are concatenated together and then parsed as a command line. As a result, shell.run("program a b") is the same as shell.run("program", "a", "b").

Parameters

  1. ... string The program to run and its arguments.

Returns

  1. boolean Whether the program exited successfully.

Usage

  • Run paint my-image from within your program:

    shell.run("paint", "my-image")

See also

  • shell.execute Run a program directly without parsing the arguments.
exit()Source

Exit the current shell.

This does not terminate your program, it simply makes the shell terminate after your program has finished. If this is the toplevel shell, then the computer will be shutdown.

dir()Source

Return the current working directory. This is what is displayed before the > of the shell prompt, and is used by shell.resolve to handle relative paths.

Returns

  1. string The current working directory.

See also

  • setDir To change the working directory.
setDir(dir)Source

Set the current working directory.

Parameters

  1. dir string The new working directory.

Throws

  • If the path does not exist or is not a directory.

Usage

path()Source

Set the path where programs are located.

The path is composed of a list of directory names in a string, each separated by a colon (:). On normal turtles will look in the current directory (.), /rom/programs and /rom/programs/turtle folder, making the path .:/rom/programs:/rom/programs/turtle.

Returns

  1. string The current shell's path.

See also

  • setPath To change the current path.
setPath(path)Source

Set the current program path.

Be careful to prefix directories with a /. Otherwise they will be searched for from the current directory, rather than the computer's root.

Parameters

  1. path string The new program path.
resolve(path)Source

Resolve a relative path to an absolute path.

The fs and io APIs work using absolute paths, and so we must convert any paths relative to the current directory to absolute ones. This does nothing when the path starts with /.

Parameters

  1. path string The path to resolve.

Usage

resolveProgram(command)Source

Resolve a program, using the program path and list of aliases.

Parameters

  1. command string The name of the program

Returns

  1. string | nil The absolute path to the program, or nil if it could not be found.

Usage

programs([include_hidden])Source

Return a list of all programs on the path.

Parameters

  1. include_hidden? boolean Include hidden files. Namely, any which start with ..

Returns

  1. { string } A list of available programs.

Usage

complete(sLine)Source

Complete a shell command line.

This accepts an incomplete command, and completes the program name or arguments. For instance, l will be completed to ls, and ls ro will be completed to ls rom/.

Completion handlers for your program may be registered with shell.setCompletionFunction.

Parameters

  1. sLine string The input to complete.

Returns

  1. { string } | nil The list of possible completions.

See also

completeProgram(program)Source

Complete the name of a program.

Parameters

  1. program string The name of a program to complete.

Returns

  1. { string } A list of possible completions.

See also

setCompletionFunction(program, complete)Source

Set the completion function for a program. When the program is entered on the command line, this program will be called to provide auto-complete information.

The completion function accepts four arguments:

  1. The current shell. As completion functions are inherited, this is not guaranteed to be the shell you registered this function in.
  2. The index of the argument currently being completed.
  3. The current argument. This may be the empty string.
  4. A list of the previous arguments.

For instance, when completing pastebin put rom/st our pastebin completion function will receive the shell API, an index of 2, rom/st as the current argument, and a "previous" table of { "put" }. This function may then wish to return a table containing artup.lua, indicating the entire command should be completed to pastebin put rom/startup.lua.

You completion entries may also be followed by a space, if you wish to indicate another argument is expected.

Parameters

  1. program string The path to the program. This should be an absolute path without the leading /.
  2. complete function(shell: table, index: number, argument: string, previous: { string }):{ string } | nil The completion function.

See also

getCompletionInfo()Source

Get a table containing all completion functions.

This should only be needed when building custom shells. Use setCompletionFunction to add a completion function.

Returns

  1. { [string] = { fnComplete = function } } A table mapping the absolute path of programs, to their completion functions.
getRunningProgram()Source

Returns the path to the currently running program.

Returns

  1. string The absolute path to the running program.
setAlias(command, program)Source

Add an alias for a program.

Parameters

  1. command string The name of the alias to add.
  2. program string The name or path to the program.

Usage

clearAlias(command)Source

Remove an alias.

Parameters

  1. command string The alias name to remove.
aliases()Source

Get the current aliases for this shell.

Aliases are used to allow multiple commands to refer to a single program. For instance, the list program is aliased dir or ls. Running ls, dir or list in the shell will all run the list program.

Returns

  1. { [string] = string } A table, where the keys are the names of aliases, and the values are the path to the program.

See also

openTab(...)Source

Open a new multishell tab running a command.

This behaves similarly to shell.run, but instead returns the process index.

This function is only available if the multishell API is.

Parameters

  1. ... string The command line to run.

Usage

See also

switchTab(id)Source

Switch to the multishell tab with the given index.

Parameters

  1. id number The tab to switch to.

See also