Difference between revisions of "OS (API)"

From ComputerCraft Wiki
Jump to: navigation, search
(API: Fixed dead link)
(Updated to API overview v2)
Line 1: Line 1:
 
The Operating System API allows for interfacing with the Lua based Operating System itself.
 
The Operating System API allows for interfacing with the Lua based Operating System itself.
{| border="1" cellpadding="2" cellspacing="0"
+
 
!style="background:#EEE" width="200px"|Method name
+
<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
!style="background:#EEE" width="*"|Description
+
<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;
|[[os.version]]()
+
OS (API)
|Returns the version of the OS the computer is running.
+
</td></tr>
|-
+
 
|[[os.getComputerID]]()
+
<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>
|Returns the unique ID of this computer. [[os.computerID]]() also behaves exactly the same as [[os.getComputerID]]().
+
 
|-
+
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[os.version]]()</td>
|[[os.getComputerLabel]]()
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the version of the OS the computer is running.</td></tr>
|Returns the label of this computer.
+
 
|-
+
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[os.getComputerID]]()</td>
|[[os.setComputerLabel]]( label )
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the unique ID of this computer. [[os.computerID]]() also behaves exactly the same as [[os.getComputerID]]().</td></tr>
|Set the label of this computer.
+
 
|-
+
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[os.getComputerLabel]]()</td>
|[[os.run]]( environment, programpath, arguments )
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the label of this computer.</td></tr>
|An advanced way of starting programs. A started program will have a given <var>environment</var> table which determines what functions it has available, as well as any variables it will be able to access by default. You may prefer to use the [[Shell (API)]] unless you need to do something special.
+
 
|-
+
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[os.setComputerLabel]]( label )</td>
|[[#api|os.loadAPI]]( name )
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Set the label of this computer.</td></tr>
|Loads a Lua script as an API in it's own namespace (see example). It will be available to '''all''' programs that run on the terminal.
+
 
|-
+
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[os.run]]( environment, programpath, arguments )</td>
|[[#api|os.unloadAPI]]( name )
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">An advanced way of starting programs. A started program will have a given <var>environment</var> table which determines what functions it has available, as well as any variables it will be able to access by default. You may prefer to use the [[Shell (API)]] unless you need to do something special.</td></tr>
|Unloads a previously loaded API.
+
 
|-
+
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[#api|os.loadAPI]]( name )</td>
|[[Os.pullEvent|os.pullEvent]]( target-event )
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Loads a Lua script as an API in it's own namespace (see example). It will be available to '''all''' programs that run on the terminal.</td></tr>
|Blocks until the computer receives an event, or if <var>target-event</var> is specified, will block until an instance of <var>target-event</var> occurs. [[Os.pullEvent|os.pullEvent]]( target-event ) returns the event and any parameters the event may have. If a <var>target-event</var> is specified, the computer will not break for any other events (except termination).
+
 
|-
+
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[#api|os.unloadAPI]]( name )</td>
|[[#pullEvent|os.pullEventRaw]]()
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Unloads a previously loaded API.</td></tr>
|Advanced version of pullEvent(). [[#pullEvent|os.pullEventRaw]]() will block until an event occurs, and then returns the event (any any parameters the event may have). Unlike [[Os.pullEvent|os.pullEvent]]( target-event ), this function will not break for system events, and can be used to handle termination events.
+
 
|-
+
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[Os.pullEvent|os.pullEvent]]( target-event )</td>
|[[os.queueEvent]]( event, param1, param2, ... )
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Blocks until the computer receives an event, or if <var>target-event</var> is specified, will block until an instance of <var>target-event</var> occurs. [[Os.pullEvent|os.pullEvent]]( target-event ) returns the event and any parameters the event may have. If a <var>target-event</var> is specified, the computer will not break for any other events (except termination).</td></tr>
|Adds an event to the event queue with the name <var>event</var> and the given parameters
+
 
|-
+
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[#pullEvent|os.pullEventRaw]]()</td>
|[[os.clock]]()
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Advanced version of pullEvent(). [[#pullEvent|os.pullEventRaw]]() will block until an event occurs, and then returns the event (any any parameters the event may have). Unlike [[Os.pullEvent|os.pullEvent]]( target-event ), this function will not break for system events, and can be used to handle termination events.</td></tr>
|Returns CPU time.
+
 
|-
+
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[os.queueEvent]]( event, param1, param2, ... )</td>
|[[os.startTimer]]( timeout )
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Adds an event to the event queue with the name <var>event</var> and the given parameters</td></tr>
|Queues an event to be triggered after a number of seconds (<var>timeout</var>). The ID of the timer is returned from this function to differentiate multiple timers. Timers are one-shot; once they have fired an event you will need to start another one if you need a recurring timer.
+
 
|-
+
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[os.clock]]()</td>
|[[os.sleep]]( timeout )
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns CPU time.</td></tr>
|Makes the system wait a number of seconds before continuing in the program. [[os.sleep]]( timeout ) may also be used as simply "sleep( timeout )".
+
 
|-
+
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[os.startTimer]]( timeout )</td>
|[[os.time]]()
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Queues an event to be triggered after a number of seconds (<var>timeout</var>). The ID of the timer is returned from this function to differentiate multiple timers. Timers are one-shot; once they have fired an event you will need to start another one if you need a recurring timer.</td></tr>
|Returns the current Minecraft world time.
+
 
|-
+
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[os.sleep]]( timeout )</td>
|[[os.setAlarm]]( time )
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Makes the system wait a number of seconds before continuing in the program. [[os.sleep]]( timeout ) may also be used as simply "sleep( timeout )".</td></tr>
|Queues an event to be triggered at the specified Minecraft world <var>time</var>.
+
 
|-
+
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[os.time]]()</td>
|[[os.shutdown]]()
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the current Minecraft world time.</td></tr>
|Turns off the computer.
+
 
|-
+
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[os.setAlarm]]( time )</td>
|[[os.reboot]]()
+
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Queues an event to be triggered at the specified Minecraft world <var>time</var>.</td></tr>
|Reboots the computer.
+
 
|}
+
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[os.shutdown]]()</td>
 +
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Turns off the computer.</td></tr>
 +
 
 +
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[os.reboot]]()</td>
 +
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Reboots the computer.</td></tr>
 +
</table>
 +
 
 +
 
 +
[[Category:APIs]]
  
 
== API ==
 
== API ==
Line 84: Line 92:
  
 
An advanced version of this method <code>os.pullEventRaw</code> bypasses the normal handling of events from the OS. You may use this to act on the "Terminate" event (triggered when holding Ctrl-T) for custom termination logic.
 
An advanced version of this method <code>os.pullEventRaw</code> bypasses the normal handling of events from the OS. You may use this to act on the "Terminate" event (triggered when holding Ctrl-T) for custom termination logic.
 
<!-- === Event names ===
 
-- please wikitable this --
 
*[[Raw key events|"key": keypress]]
 
*"rednet_message": recieved a rednet message
 
*"terminate" (? please verify name): Ctrl-T held
 
-->
 
[[Category:APIs]]
 

Revision as of 22:18, 30 November 2012

The Operating System API allows for interfacing with the Lua based Operating System itself.

Grid disk.png   OS (API)

Method NameDescription
os.version() Returns the version of the OS the computer is running.
os.getComputerID() Returns the unique ID of this computer. os.computerID() also behaves exactly the same as os.getComputerID().
os.getComputerLabel() Returns the label of this computer.
os.setComputerLabel( label ) Set the label of this computer.
os.run( environment, programpath, arguments ) An advanced way of starting programs. A started program will have a given environment table which determines what functions it has available, as well as any variables it will be able to access by default. You may prefer to use the Shell (API) unless you need to do something special.
os.loadAPI( name ) Loads a Lua script as an API in it's own namespace (see example). It will be available to all programs that run on the terminal.
os.unloadAPI( name ) Unloads a previously loaded API.
os.pullEvent( target-event ) Blocks until the computer receives an event, or if target-event is specified, will block until an instance of target-event occurs. os.pullEvent( target-event ) returns the event and any parameters the event may have. If a target-event is specified, the computer will not break for any other events (except termination).
os.pullEventRaw() Advanced version of pullEvent(). os.pullEventRaw() will block until an event occurs, and then returns the event (any any parameters the event may have). Unlike os.pullEvent( target-event ), this function will not break for system events, and can be used to handle termination events.
os.queueEvent( event, param1, param2, ... ) Adds an event to the event queue with the name event and the given parameters
os.clock() Returns CPU time.
os.startTimer( timeout ) Queues an event to be triggered after a number of seconds (timeout). The ID of the timer is returned from this function to differentiate multiple timers. Timers are one-shot; once they have fired an event you will need to start another one if you need a recurring timer.
os.sleep( timeout ) Makes the system wait a number of seconds before continuing in the program. os.sleep( timeout ) may also be used as simply "sleep( timeout )".
os.time() Returns the current Minecraft world time.
os.setAlarm( time ) Queues an event to be triggered at the specified Minecraft world time.
os.shutdown() Turns off the computer.
os.reboot() Reboots the computer.

API

API are programs which are loaded in to the OS itself, and expose functions which other programs may use. The stock APIs that ship with ComputerCraft are loaded in this way, and may be replaced by a computer's user or programs.

The following is an example of a valid implementation of an API, and, it's usage after being registered:

 -- "apiTest" file
 function foo(bar)
   print(bar)
 end
 
 -- "program" file
 os.loadAPI("apiTest")
 apiTest.foo("this is a test")

os.pullEvent()

os.pullEvent() causes the current program to pause, retrieving the next event from the computer's queue of events. If there is no event to read, then the program will stall until such an event becomes available. Note that if a program has not attempted to pull an event in the past ten seconds, it will be forcefully terminated to prevent CPU waste in SMP environments.

os.pullEvent() returns the name of the event that was read, as well as up to five parameters: local event, p1, p2, p3, p4, p5 = os.pullEvent()

os.pullEvent() is usually run inside a 'while true do' loop.

An advanced version of this method os.pullEventRaw bypasses the normal handling of events from the OS. You may use this to act on the "Terminate" event (triggered when holding Ctrl-T) for custom termination logic.