Difference between revisions of "Shell (API)"

From ComputerCraft Wiki
Jump to: navigation, search
m (Edit description of shell.programs())
m (Changed variable names to maintain consistency)
 
(15 intermediate revisions by 8 users not shown)
Line 1: Line 1:
The shell API allows you to interface with the [http://en.wikipedia.org/wiki/Shell_%28computing%29 shell].
+
{{lowercase}}
 +
The shell API allows you to interface with ComputerCraft's [http://en.wikipedia.org/wiki/Shell_%28computing%29 shell] - [[CraftOS]]. The shell API is only available when programs are ran from the shell or using [[shell.run]]/[[shell.openTab]].
  
<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
+
Note that this "API" is not loaded into _G using [[os.loadAPI]]() - instead, it's loaded by [[shell|the shell script itself]] into a separate user environment, one which also holds [http://lua-users.org/wiki/ScopeTutorial global variables] for any other scripts the user executes. [[multishell (API)|The multishell API]] is handled in the same manner. They can thus be easily sandboxed (allowing for multiple shells to run on the same system at once - the APIs for each being able to return relevant results for each instance), though it does mean other APIs can't refer to these functions (as they lack access to the environment table dedicated to user scripts).
<tr><td colspan="2" style="font-weight: bold; font-size: large; padding-bottom: .3em; border-bottom: solid #C9C9C9 1px; background: #D3FFC2; line-height:28px;">
+
[[File:Grid_disk.png|24px]]&nbsp;&nbsp;
+
Shell (API)
+
</td></tr>
+
  
<tr><td style="width: 350px; background: #E0E0E0; padding: .4em; font-weight:bold;">Method Name</td><td style="background: #E0E0E0; padding: .4em; font-weight:bold;">Description</td></tr>
+
==API==
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[shell.exit]]()</td>
+
{{API table|shell|image=Grid disk.png|2=
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Exits the current shell</td></tr>
+
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[shell.dir]]()</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the directory</td></tr>
+
|[[shell.exit]]()
 +
|{{type|nil}}
 +
|Exits the current shell.
 +
|odd}}
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[shell.setDir]]({{type|string}} path)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sets the directory</td></tr>
+
|[[shell.dir]]()
 +
|{{type|string}} directory
 +
|Returns the path to the working directory.}}
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[shell.path]]()</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the path</td></tr>
+
|[[shell.setDir]]({{type|string}} path)
 +
|{{type|nil}}
 +
|Sets the working directory.
 +
|odd}}
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[shell.setPath]]({{type|string}} path)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sets the path</td></tr>
+
|[[shell.path]]()
 +
|{{type|string}} path
 +
|Returns the path.}}
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[shell.resolve]]({{type|string}} localpath)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Resolves a local path to an absolute path.</td></tr>
+
|[[shell.setPath]]({{type|string}} path)
 +
|{{type|nil}}
 +
|Sets the path.
 +
|odd}}
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[shell.resolveProgram]]({{type|string}} name)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Resolves the absolute path to the program whose name you provided.</td></tr>
+
|[[shell.resolve]]({{type|string}} localPath)
 +
|{{type|string}} absolutePath
 +
|Resolves a local path to an absolute path.}}
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[shell.aliases]]()</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns aliases.</td></tr>
+
|[[shell.resolveProgram]]({{type|string}} name)
 +
|{{type|string}} absolutePath
 +
|Resolves the absolute path to the program whose name you provided.
 +
|odd}}
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[shell.setAlias]]({{type|string}} alias, {{type|string}} program)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sets an alias.</td></tr>
+
|[[shell.aliases]]()
 +
|{{type|table}} aliases
 +
|Returns aliases.}}
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[shell.clearAlias]]({{type|string}} alias, {{type|string}} program)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Clears an alias.</td></tr>
+
|[[shell.setAlias]]({{type|string}} alias, {{type|string}} program)
 +
|{{type|nil}}
 +
|Sets an alias for ''program''.
 +
|odd}}
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[shell.programs]]()</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns a {{type|table}} of programs.</td></tr>
+
|[[shell.clearAlias]]({{type|string}} alias)
 +
|{{type|nil}}
 +
|Clears an alias.}}
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[shell.run]]({{type|string}} program, {{type|string}} arguments)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Runs a program.</td></tr>
+
|[[shell.programs]]([<nowiki/>{{type|boolean}} showHidden])
 +
|{{type|table}} programs
 +
|Returns a table of files in the current directory and in all paths in [[shell.path]].
 +
|odd}}
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[shell.getRunningProgram]]()</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the absolute path to the currently-executing program.</td></tr>
+
|[[shell.getRunningProgram]]()
</table>
+
|{{type|string}} path
 +
|Returns the absolute path to the currently-executing program.}}
  
 +
{{API table/row
 +
|[[shell.run]]({{type|string}} command [, {{type|string}} args1, {{type|string}} args2, ...])
 +
|{{type|boolean}} success
 +
|Runs a command (program).
 +
|odd}}
 +
 +
{{API table/row
 +
|[[shell.openTab]]({{type|string}} command [, {{type|string}} args1, {{type|string}} args2, ...])
 +
|{{type|number}} tabID
 +
|Runs a program in another [[multishell]] tab. ''Requires version 1.6 or newer and an advanced system.''}}
 +
 +
{{API table/row
 +
|[[shell.switchTab]]({{type|number}} tabID)
 +
|{{type|nil}}
 +
|Switches the [[multishell]] tab to tab with the given ID.  ''Requires version 1.6 or newer and an advanced system.''
 +
|odd}}
 +
 +
{{API table/row
 +
|[[shell.complete]]({{type|string}} prefix)
 +
|{{type|table}} completionList
 +
|Given a partial command line, returns a list of suffixes that could potentially be used to complete it.  ''Requires version 1.74 or newer.''}}
 +
 +
{{API table/row
 +
|[[shell.completeProgram]]({{type|string}} prefix)
 +
|{{type|table}} completionList
 +
|Given a partial script / directory path, returns a list of suffixes that could potentially be used to complete it, including [[shell.aliases|alias]] and [[shell.path|path]] matches.  ''Requires version 1.74 or newer.''
 +
|odd}}
 +
 +
{{API table/row
 +
|[[shell.setCompletionFunction]]({{type|string}} path, {{type|function}} completionFunction)
 +
|{{type|nil}}
 +
|Registers a function that determines how [[shell.complete]]() handles completion behavior for a given script. ''Requires version 1.74 or newer.''}}
 +
 +
{{API table/row
 +
|[[shell.getCompletionInfo]]()
 +
|{{type|table}} completionFunctions
 +
|Returns a pointer to the table containing functions registered by [[shell.setCompletionFunction]]() for use with [[shell.complete]](). ''Requires version 1.74 or newer.''
 +
|odd}}
 +
 +
}}
 +
 +
Note that [[shell.run]] and [[shell.openTab]] concatenate any arguments they are given (with single space separator characters) before parsing the command, and as of ComputerCraft version 1.45, now also support a single string containing ''all'' parameters.
  
 
[[Category:APIs]]
 
[[Category:APIs]]

Latest revision as of 12:31, 14 August 2015

The shell API allows you to interface with ComputerCraft's shell - CraftOS. The shell API is only available when programs are ran from the shell or using shell.run/shell.openTab.

Note that this "API" is not loaded into _G using os.loadAPI() - instead, it's loaded by the shell script itself into a separate user environment, one which also holds global variables for any other scripts the user executes. The multishell API is handled in the same manner. They can thus be easily sandboxed (allowing for multiple shells to run on the same system at once - the APIs for each being able to return relevant results for each instance), though it does mean other APIs can't refer to these functions (as they lack access to the environment table dedicated to user scripts).

API

Grid disk.png  shell (API)
Function Return values Description
shell.exit() nil Exits the current shell.
shell.dir() string directory Returns the path to the working directory.
shell.setDir(string path) nil Sets the working directory.
shell.path() string path Returns the path.
shell.setPath(string path) nil Sets the path.
shell.resolve(string localPath) string absolutePath Resolves a local path to an absolute path.
shell.resolveProgram(string name) string absolutePath Resolves the absolute path to the program whose name you provided.
shell.aliases() table aliases Returns aliases.
shell.setAlias(string alias, string program) nil Sets an alias for program.
shell.clearAlias(string alias) nil Clears an alias.
shell.programs([boolean showHidden]) table programs Returns a table of files in the current directory and in all paths in shell.path.
shell.getRunningProgram() string path Returns the absolute path to the currently-executing program.
shell.run(string command [, string args1, string args2, ...]) boolean success Runs a command (program).
shell.openTab(string command [, string args1, string args2, ...]) number tabID Runs a program in another multishell tab. Requires version 1.6 or newer and an advanced system.
shell.switchTab(number tabID) nil Switches the multishell tab to tab with the given ID. Requires version 1.6 or newer and an advanced system.
shell.complete(string prefix) table completionList Given a partial command line, returns a list of suffixes that could potentially be used to complete it. Requires version 1.74 or newer.
shell.completeProgram(string prefix) table completionList Given a partial script / directory path, returns a list of suffixes that could potentially be used to complete it, including alias and path matches. Requires version 1.74 or newer.
shell.setCompletionFunction(string path, function completionFunction) nil Registers a function that determines how shell.complete() handles completion behavior for a given script. Requires version 1.74 or newer.
shell.getCompletionInfo() table completionFunctions Returns a pointer to the table containing functions registered by shell.setCompletionFunction() for use with shell.complete(). Requires version 1.74 or newer.

Note that shell.run and shell.openTab concatenate any arguments they are given (with single space separator characters) before parsing the command, and as of ComputerCraft version 1.45, now also support a single string containing all parameters.