Difference between revisions of "OS (API)"

From ComputerCraft Wiki
Jump to: navigation, search
m
(Made it less barren.)
Line 1: Line 1:
 +
 
''You may be looking for alternative OS's for ComputerCraft. If so, go to the [[list of OS's]].''
 
''You may be looking for alternative OS's for ComputerCraft. If so, go to the [[list of OS's]].''
  
Line 7: Line 8:
 
|-
 
|-
 
|os.version()
 
|os.version()
|Returns version
+
|Returns the version of the OS the computer is running.
 
|-
 
|-
 
|os.computerID()
 
|os.computerID()
|Returns the ID of the computer
+
|Returns the unique ID of this computer.
 
|-
 
|-
 
|os.run( environment, programpath, arguments )
 
|os.run( environment, programpath, arguments )
|<no description given>
+
|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 )
+
|[[#api|os.loadAPI( name )]]
|Loads the API given.
+
|Loads a lua script as an API, making it available to all programs.
 
|-
 
|-
|os.unloadAPI( name )
+
|[[#api|os.unloadAPI( name )]]
|Unloads the API given.
+
|Unloads a previously loaded API.
 
|-
 
|-
 
|[[#pullEvent|os.pullEvent()]]
 
|[[#pullEvent|os.pullEvent()]]
|<no description given>
+
|Blocks until the computer has detected an event, then returns the event.
 +
|-
 +
|[[#pullEvent|os.pullEventRaw()]]
 +
|Advanced version of pullEvent().
 
|-
 
|-
 
|os.queueEvent()
 
|os.queueEvent()
Line 31: Line 38:
 
|-
 
|-
 
|os.startTimer( timeout )
 
|os.startTimer( timeout )
|<no description given>
+
|Queues an event to be triggered after a number of seconds.
 +
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 )
 
|os.sleep( timeout )
|Makes the system wait before continuing in the program.
+
|Makes the system wait a number of seconds before continuing in the program.
 +
May also be used as simply "sleep( timeout )".
 
|-
 
|-
 
|os.time()
 
|os.time()
|Returns MineCraft time.
+
|Returns the current Minecraft world time.
 
|-
 
|-
 
|os.setAlarm( time )
 
|os.setAlarm( time )
|<no description given>
+
|Queues an event to be triggered at the specific Minecraft world time.
 
|-
 
|-
 
|os.shutdown()
 
|os.shutdown()
Line 49: Line 60:
 
|}
 
|}
  
 +
== <div id="api">API</div> ==
 +
 +
API are programs which are loaded in to the OS itself, and expose functions
 +
which other programs may use. The stock [[Category:APIs|APIs that ship with
 +
ComputerCraft]] are loaded in this way, and may be replaced by a computer's
 +
user or programs.
  
 
== <div id="pullEvent">os.pullEvent()</div> ==
 
== <div id="pullEvent">os.pullEvent()</div> ==
  
The pullEvent() function allows the computer to check if a certain event has occurred and acts upon that event through 'if' and 'elseif' statements. os.pullEvent() is usually run inside a 'while true do' loop.
+
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.
 +
 
 +
pullEvent returns the name of the event that was read, as well as up to
 +
five parameters:
 +
 
 +
<code>
 +
local event, p1, p2, p3, p4, p5 = os.pullEvent()
 +
</code>
 +
 
 +
os.pullEvent() is usually run inside a 'while true do' loop.
 +
 
 +
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.
  
 
[[Category:APIs]]
 
[[Category:APIs]]

Revision as of 09:01, 23 February 2012

You may be looking for alternative OS's for ComputerCraft. If so, go to the list of OS's.

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

Method name Description
os.version() Returns the version of the OS the computer is running.
os.computerID() Returns the unique ID 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, making it available to all programs.
os.unloadAPI( name ) Unloads a previously loaded API.
os.pullEvent() Blocks until the computer has detected an event, then returns the event.
os.pullEventRaw() Advanced version of pullEvent().
os.queueEvent() <no description given>
os.clock() Returns CPU time.
os.startTimer( timeout ) Queues an event to be triggered after a number of seconds.

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.

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 specific 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 are loaded in this way, and may be replaced by a computer's user or programs.

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.

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.