Difference between revisions of "OS (API)"

From ComputerCraft Wiki
Jump to: navigation, search
(use API table template)
(add cancelTimer and cancelAlarm calls.)
 
(5 intermediate revisions by 4 users not shown)
Line 2: Line 2:
  
  
{{API table|Os|image=Grid disk.png|2=
+
{{API table|OS|image=Grid disk.png|2=
  
 
{{API table/row
 
{{API table/row
Line 10: Line 10:
  
 
{{API table/row
 
{{API table/row
|[[os.getComputerId]]()|{{type|number}} id
+
|[[os.getComputerID]]()|{{type|number}} id
 
|Returns the unique ID of this computer. [[os.computerID]]() also behaves exactly the same as [[os.getComputerID]]().
 
|Returns the unique ID of this computer. [[os.computerID]]() also behaves exactly the same as [[os.getComputerID]]().
 
|}}
 
|}}
  
 
{{API table/row
 
{{API table/row
|[[os.getComputerLabel]]()|{{type|string}} label
+
|[[os.getComputerLabel]]()|{{type|string}}/{{type|nil}} label
|Returns the label of this computer. [[os.computerLabel]]() also behaves exactly the same as [[os.getComputerLabel]](). <!-- what does it return if there's no label? -->
+
|Returns the label of this computer. [[os.computerLabel]]() also behaves exactly the same as [[os.getComputerLabel]]().
 
|odd}}
 
|odd}}
  
 
{{API table/row
 
{{API table/row
|[[os.setComputerLabel]]({{type|string}} label)|{{type|nil}}
+
|[[os.setComputerLabel]]({{type|string}}/{{type|nil}} label)|{{type|nil}}
 
|Set the label of this computer.
 
|Set the label of this computer.
 
|}}
 
|}}
  
 
{{API table/row
 
{{API table/row
|[[os.run]]({{type|table}} environment, {{type|string}} program path [, {{type|string}} arguments])|{{type|nil}}
+
|[[os.run]]({{type|table}} environment, {{type|string}} programPath [, {{type|string}} arguments])
 +
|{{type|boolean}} success
 
|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.
 
|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.
 
|odd}}
 
|odd}}
  
 
{{API table/row
 
{{API table/row
|[[#APIs|os.loadAPI]]({{type|string}} name)|{{type|nil}}
+
|[[os.loadAPI]]({{type|string}} path)
|Loads a Lua script as an API in its own namespace (see example). It will be available to '''all''' programs that run on the terminal.
+
|{{type|boolean}} success
|}}
+
|Loads a Lua script as an API in its own namespace. It will be available to '''all''' programs that run on the terminal.}}
  
 
{{API table/row
 
{{API table/row
|[[#APIs|os.unloadAPI]]({{type|string}} name)|{{type|nil}}
+
|[[os.unloadAPI]]({{type|string}} name)|{{type|nil}}
 
|Unloads a previously loaded API.
 
|Unloads a previously loaded API.
 
|odd}}
 
|odd}}
  
 
{{API table/row
 
{{API table/row
|[[Os.pullEvent|os.pullEvent]]({{type|string}}/{{type|nil}} target-event)|any
+
|[[os.pullEvent]]([<nowiki/>{{type|string}} target-event])
|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).
+
|{{type|string}} event, param1, param2, ...
 +
|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]](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).
 
|}}
 
|}}
  
 
{{API table/row
 
{{API table/row
|[[#pullEvent|os.pullEventRaw]]()|any
+
|[[os.pullEventRaw]]([<nowiki/>{{type|string}} target-event])
|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 raise an error if a 'terminate' event is received.
+
|{{type|string}} event, param1, param2, ...
 +
|Advanced version of pullEvent(). 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.pullEventRaw]](target-event) returns the event and any parameters the event may have. Unlike [[os.pullEvent]](target-event), this function will not raise an error if a [[terminate_(event)|'terminate' event]] is received.
 
|odd}}
 
|odd}}
  
 
{{API table/row
 
{{API table/row
 
|[[os.queueEvent]]({{type|string}} event, param1, param2, ...)|{{type|nil}}
 
|[[os.queueEvent]]({{type|string}} event, param1, param2, ...)|{{type|nil}}
|Adds an event to the event queue with the name <var>event</var> and the given parameters
+
|Adds an event to the event queue with the name <var>event</var> and the given parameters.
 
|}}
 
|}}
  
 
{{API table/row
 
{{API table/row
 
|[[os.clock]]()|{{type|number}} time
 
|[[os.clock]]()|{{type|number}} time
|Returns the amount of time since the computer was started.
+
|Returns the amount of time since the in-game computer was started.
 
|odd}}
 
|odd}}
  
Line 62: Line 65:
 
|[[os.startTimer]]({{Type|number}} timeout)|{{type|number}} timerID
 
|[[os.startTimer]]({{Type|number}} timeout)|{{type|number}} timerID
 
|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.
 
|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.
 +
|}}
 +
 +
{{API table/row
 +
|[[os.cancelTimer]]({{Type|number}} timerID)|{{type|nil}}
 +
|Cancels a running timer, to prevent it throwing an event.
 
|}}
 
|}}
  
Line 76: Line 84:
 
{{API table/row
 
{{API table/row
 
|[[os.day]]()|{{type|number}} day
 
|[[os.day]]()|{{type|number}} day
|Return the current in-game day (the number of days since the world was created).
+
|Return the current in-game day (the number of in-game days since the world was created).
 
|odd}}
 
|odd}}
  
Line 82: Line 90:
 
|[[os.setAlarm]]({{type|number}} time)|{{type|number}} alarmID
 
|[[os.setAlarm]]({{type|number}} time)|{{type|number}} alarmID
 
|Queues an event to be triggered at the specified in-game <var>time</var>.
 
|Queues an event to be triggered at the specified in-game <var>time</var>.
 +
|}}
 +
 +
{{API table/row
 +
|[[os.cancelAlarm]]({{Type|number}} alarmID)|{{type|nil}}
 +
|Cancels a pending alarm, to prevent it throwing an event.
 
|}}
 
|}}
  

Latest revision as of 06:54, 4 January 2015

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


Grid disk.png  OS (API)
Function Return values Description
os.version() string version Returns the version of the OS the computer is running, which (for CraftOS) also contains the version of ComputerCraft.
os.getComputerID() number id Returns the unique ID of this computer. os.computerID() also behaves exactly the same as os.getComputerID().
os.getComputerLabel() string/nil label Returns the label of this computer. os.computerLabel() also behaves exactly the same as os.getComputerLabel().
os.setComputerLabel(string/nil label) nil Set the label of this computer.
os.run(table environment, string programPath [, string arguments]) boolean success 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(string path) boolean success Loads a Lua script as an API in its own namespace. It will be available to all programs that run on the terminal.
os.unloadAPI(string name) nil Unloads a previously loaded API.
os.pullEvent([string target-event]) string event, param1, param2, ... 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([string target-event]) string event, param1, param2, ... Advanced version of pullEvent(). Blocks until the computer receives an event, or if target-event is specified, will block until an instance of target-event occurs. os.pullEventRaw(target-event) returns the event and any parameters the event may have. Unlike os.pullEvent(target-event), this function will not raise an error if a 'terminate' event is received.
os.queueEvent(string event, param1, param2, ...) nil Adds an event to the event queue with the name event and the given parameters.
os.clock() number time Returns the amount of time since the in-game computer was started.
os.startTimer(number timeout) number timerID 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.cancelTimer(number timerID) nil Cancels a running timer, to prevent it throwing an event.
os.time() number time Returns the current in-game time.
os.sleep(number time) nil Makes the system wait a number of seconds before continuing in the program. os.sleep(time) may also be used as simply "sleep(time)".
os.day() number day Return the current in-game day (the number of in-game days since the world was created).
os.setAlarm(number time) number alarmID Queues an event to be triggered at the specified in-game time.
os.cancelAlarm(number alarmID) nil Cancels a pending alarm, to prevent it throwing an event.
os.shutdown() nil Turns off the computer.
os.reboot() nil Reboots the computer.

APIs

APIs are Lua files which are loaded into 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 its 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.