ComputerCraft Wiki - User contributions [en]

Talk:Coroutine (API)

2013-05-28T13:41:22Z

Hawk777:

Bottom section (Interaction with other APIs) is written upside-down. It would be more useful to start out talking about how the event-based model ComputerCraft uses actually utilizes coroutines and the .yield and .resume parameters and return values. That is the primary use case for coroutines in ComputerCraft, so it would be better to lead with that, as it will cause less confusion among new users. From there, it would be good to mention that if one does desire to deviate from the event-based model ComputerCraft uses, that one should avoid using (or add special handling for) all of the functions which wait for events. "Blocking" is also a misleading term, since it implies that the execution point gets stuck in that function (which would block other coroutines from running), when the truth of the matter is that it simply yields execution. "Yielding" would be a better term. [[User:Lyqyd|Lyqyd]] 15:53, 28 May 2013 (MSK)

:Better? [[User:Hawk777|Hawk777]] 17:41, 28 May 2013 (MSK)

Coroutine (API)

2013-05-28T13:38:37Z

Hawk777: /* Interaction with Other APIs */ Apparently people usually replicate the event dispatcher rather than using asynchronous calls so that should be first

{{NeedsWork}}
:{| border="1" class="wikitable"
| '''Bug'''
'''From ComputerCraft 1.3''' this API suffers from the problem of potentially spawning Java threads that live forever therefore, use of coroutines should be minimized. This is '''fixed in ComputerCraft 1.32+''', though.
|}

''This is for the Coroutine API. For the Coroutine Object, visit [[Coroutine (type)]].''

Coroutine is a default Lua 5.1 API defined [http://www.lua.org/manual/5.1/manual.html#5.2 here]. Please list any non-working functions on this page.

<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
<tr><td colspan="3" 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]]  
Coroutine (API)
</td></tr>

<tr><td style="width: 100px; background: #E0E0E0; padding: .4em; font-weight:bold;">Return</td><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>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|coroutine}} coro</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[coroutine.create]]({{Type|function}} f)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Creates a new coroutine.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|boolean}} success, …</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[coroutine.resume]]({{Type|coroutine}} coro, [var1], [var2], ...)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Starts or resumes an existing coroutine.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|coroutine}} coro</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[coroutine.running]]()</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the currently executing coroutine.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|string}} status</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[coroutine.status]]({{type|coroutine}} coroutine)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the status of the given coroutine.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|function}} coroutine wrapper</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[coroutine.wrap]]({{type|function}} function)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Creates a new coroutine and wraps it in a function.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[var3], [var4], …</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[coroutine.yield]]([var1], [var2], …)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Pauses the currently executing coroutine and passes control to its caller.</td></tr>
</table>

== Coroutine States and Ancestry ==
Every coroutine is in one of four states:
* A ''suspended'' coroutine is one that has not yet been started or that has yielded. A suspended coroutine can become running if it is passed to [[coroutine.resume]].
* A ''running'' coroutine is one that is currently executing code. Only one coroutine can be running at a time on a particular computer. A running coroutine can become suspended if it [[coroutine.yield]], normal if it calls [[coroutine.resume]] on another coroutine, or dead by if it returns from its body function.
* A ''normal'' coroutine is one that, while running, resumed another coroutine (the ''child coroutine''). A normal coroutine can become running if its child calls [[coroutine.yield]] or returns from its function body.
* A ''dead'' coroutine is one that, while running, returned from its function body. A dead coroutine can never change state.

While suspended and dead coroutines simply sit loose with no connections to other coroutines, normal and running coroutines have an ancestry relationship between them. Exactly one coroutine is running at any given time, and the running coroutine has no children. Every running or normal coroutine except the top-level BIOS coroutine has a parent, and this relationship forms a chain with one end (the furthest ancestor) being the top-level BIOS coroutine and the other end (the furthest descendant) being the running coroutine. Remember that only the running coroutine can actually execute code, so any functions invoked must be invoked by that coroutine. Then, calling [[coroutine.resume]] makes the chain longer by taking a previously suspended coroutine, hanging it underneath the current coroutine as a new child, and making the current coroutine normal and the new child running. Meanwhile, calling [[coroutine.yield]] makes the chain shorter by turning the currently executing coroutine into a suspended coroutine, detaching it from the chain, and letting its former parent become running.

It is important not to confuse this coroutine chain with the function call stack. Each individual coroutine contains a complete function call stack of its own, rooted at the coroutine’s body function, whether the coroutine is running, normal, or suspended; the chain described in the previous paragraph refers to how entire coroutines are connected together.

== Examples ==
As the coroutine API is very tightly coupled and many of its function must be used to get any interesting results, examples are shown here instead of on the individual function pages.

=== Using the Basic Coroutine Functions ===
This example demonstrates using the basic coroutine functions to pass control and data between coroutines. This example prints the numbers 1 through 17 in order, showing how control flow moves through the main program coroutine and the two created coroutines, while using assertions to show how data flows through the program:

-- These variables will hold the coroutine objects.
local c1 = nil
local c2 = nil

-- This function will be the body of the first coroutine.
local function f1(x)
-- The main code, below, starts c1 first, passing 1.
-- Thus c1 should be running, c2 should be suspended (not started yet), and x should receive the value from main, 1.
-- STEP 2: Check these assumptions.
print(2)
assert(coroutine.status(c1) == "running")
assert(coroutine.status(c2) == "suspended")
assert(x == 1)
-- STEP 3: Run c2 until it yields, start it off with the value 2.
print(3)
success, value = coroutine.resume(c2, 2)
assert(success)
-- In step 6, c2 yields and passes back the value 3.
-- Then c2, having yielded, should be suspended, and c1 should be running again.
-- STEP 7: Check all that.
print(7)
assert(coroutine.status(c1) == "running")
assert(coroutine.status(c2) == "suspended")
assert(value == 3)
-- STEP 8: Run c2 again, passing it the value 4.
-- Since c2 has already run before, this time the 4 will come out of the yield() instead of appear as a function parameter.
print(8)
success, value = coroutine.resume(c2, 4)
-- In step 10, c2 yields and passes back the value 5.
-- Then c2, having yielded, should be suspended, and c1 should be running again.
-- STEP 11: Check all that.
print(11)
assert(coroutine.status(c1) == "running")
assert(coroutine.status(c2) == "suspended")
assert(value == 5)
-- STEP 12: Yield, turning c1 back into a suspended coroutine and continuing execution of the main program, passing back value 6.
print(12)
value = coroutine.yield(6)
end

-- This function will be the body of the second coroutine.
local function f2(x)
-- The first time c2 is run, it is run from f1, which passes 2.
-- Thus c1 should be normal (as we are nested inside it), c2 should be running, and x should receive the value from f1, 2.
-- STEP 4: Check these assumptions.
print(4)
assert(coroutine.status(c1) == "normal")
assert(coroutine.status(c2) == "running")
assert(x == 2)
-- Because c1 is not suspended, we should not be able to resume it.
-- STEP 5: Check this is correct.
print(5)
success, value = coroutine.resume(c1)
assert(not success)
assert(value == "cannot resume normal coroutine")
-- STEP 6: Yield, turning c2 back into a suspended coroutine and continuing execution of c1, passing back value 3.
print(6)
value = coroutine.yield(3)
-- In step 8, c1 resumed c2 again and passed the value 4.
-- c2 should now be running again, and c1 normal again.
-- STEP 9: Check all that.
print(9)
assert(coroutine.status(c1) == "normal")
assert(coroutine.status(c2) == "running")
assert(value == 4)
-- STEP 10: Yield, turning c2 back into a suspended coroutine and continuing execution of c1, passing back value 5.
print(10)
value = coroutine.yield(5)
-- In step 14, the main program resumed c2 directly and passed the value 7, bypassing c1.
-- So c2 should be running and c1 should be suspended.
-- STEP 15: Check all that.
print(15)
assert(coroutine.status(c1) == "suspended")
assert(coroutine.status(c2) == "running")
assert(value == 7)
-- STEP 16: Now die, returning value 8 to the main program.
print(16)
return 8
end

-- Construct the two coroutines.
c1 = coroutine.create(f1)
c2 = coroutine.create(f2)

-- Newly constructed coroutines are always suspended.
assert(coroutine.status(c1) == "suspended")
assert(coroutine.status(c2) == "suspended")

-- STEP 1: Run c1 until it yields, starting it off with the value 1.
print(1)
success, value = coroutine.resume(c1, 1)
assert(success)

-- In step 12, c1 should have yielded and returned the value 6.
-- So now c1 and c2 should both be suspended.
-- STEP 13: Check all that.
print(13)
assert(coroutine.status(c1) == "suspended")
assert(coroutine.status(c2) == "suspended")
assert(value == 6)

-- STEP 14: Run c2 directly, NOT nested inside c1 this time, passing it the value 7.
print(14)
success, value = coroutine.resume(c2, 7)
assert(success)

-- c2 should have exited normally, returning the value 8.
-- Therefore c1 should still be suspended, but c2 should be dead.
-- STEP 17: Check all that.
print(17)
assert(coroutine.status(c1) == "suspended")
assert(coroutine.status(c2) == "dead")
assert(value == 8)

=== Using Coroutine Wrapper Functions ===
This second example is virtually identical, but shows using [[coroutine.wrap]] and wrapper functions instead of the basic coroutine functions (checks of [[coroutine.status]] have been removed as the raw coroutine objects are not available):

-- These variables will hold the coroutine wrapper functions.
local cw1 = nil
local cw2 = nil

-- This function will be the body of the first coroutine.
local function f1(x)
-- The main code, below, starts c1 first, passing 1.
-- Thus c1 should be running, c2 should be suspended (not started yet), and x should receive the value from main, 1.
-- STEP 2: Check these assumptions.
print(2)
assert(x == 1)
-- STEP 3: Run c2 until it yields, start it off with the value 2.
print(3)
value = cw2(2)
-- In step 6, c2 yields and passes back the value 3.
-- Then c2, having yielded, should be suspended, and c1 should be running again.
-- STEP 7: Check all that.
print(7)
assert(value == 3)
-- STEP 8: Run c2 again, passing it the value 4.
-- Since c2 has already run before, this time the 4 will come out of the yield() instead of appear as a function parameter.
print(8)
value = cw2(4)
-- In step 10, c2 yields and passes back the value 5.
-- Then c2, having yielded, should be suspended, and c1 should be running again.
-- STEP 11: Check all that.
print(11)
assert(value == 5)
-- STEP 12: Yield, turning c1 back into a suspended coroutine and continuing execution of the main program, passing back value 6.
print(12)
value = coroutine.yield(6)
end

-- This function will be the body of the second coroutine.
local function f2(x)
-- The first time c2 is run, it is run from f1, which passes 2.
-- Thus c1 should be normal (as we are nested inside it), c2 should be running, and x should receive the value from f1, 2.
-- STEP 4: Check these assumptions.
print(4)
assert(x == 2)
-- Because c1 is not suspended, we should not be able to resume it.
-- STEP 5: Check this is correct (we must use pcall because an error will be raised).
print(5)
success, value = pcall(cw1)
assert(not success)
-- STEP 6: Yield, turning c2 back into a suspended coroutine and continuing execution of c1, passing back value 3.
print(6)
value = coroutine.yield(3)
-- In step 8, c1 resumed c2 again and passed the value 4.
-- c2 should now be running again, and c1 normal again.
-- STEP 9: Check all that.
print(9)
assert(value == 4)
-- STEP 10: Yield, turning c2 back into a suspended coroutine and continuing execution of c1, passing back value 5.
print(10)
value = coroutine.yield(5)
-- In step 14, the main program resumed c2 directly and passed the value 7, bypassing c1.
-- So c2 should be running and c1 should be suspended.
-- STEP 15: Check all that.
print(15)
assert(value == 7)
-- STEP 16: Now die, returning value 8 to the main program.
print(16)
return 8
end

-- Construct the two coroutine wrappers.
cw1 = coroutine.wrap(f1)
cw2 = coroutine.wrap(f2)

-- STEP 1: Run cw1 until it yields, starting it off with the value 1.
print(1)
value = cw1(1)

-- In step 12, c1 should have yielded and returned the value 6.
-- So now c1 and c2 should both be suspended.
-- STEP 13: Check all that.
print(13)
assert(value == 6)

-- STEP 14: Run c2 directly, NOT nested inside c1 this time, passing it the value 7.
print(14)
value = cw2(7)

-- c2 should have exited normally, returning the value 8.
-- Therefore c1 should still be suspended, but c2 should be dead.
-- STEP 17: Check all that.
print(17)
assert(value == 8)

== Interaction with Other APIs ==
The [[OS (API)#pullEvent|os.pullEventRaw]] (and therefore [[os.pullEvent]]) functions are built on top of coroutines: <code>os.pullEventRaw</code> actually just calls [[coroutine.yield]], passing the event type filter up to the parent coroutine. The parent coroutine is expected to wait until an event of the required type arrives, then use [[coroutine.resume]] to pass the event to the suspended coroutine (where it will be returned from <code>os.pullEventRaw</code>). If you use the [[Parallel (API)|parallel API]], this is exactly what [[parallel.waitForAny]] and [[parallel.waitForAll]] do: they pull events from the system event queue (or even from a higher invocation of <code>parallel.waitForAny</code> or <code>parallel.waitForAll</code>!) and deliver them to all nested coroutines. Therefore, the easiest way to use coroutines is the parallel API, if it works for your situation. However, in the event that you are not able to use the parallel API (e.g. if you need to add and remove coroutines from the executing set dynamically), you can build your own dispatcher that delivers events in the same way as the parallel API—looking at the source code to the parallel API may be useful here.

If you choose to use coroutines in a different way, then <code>os.pullEventRaw</code> and <code>os.pullEvent</code> will not work. This in turn will break any other API function which is written on top of <code>os.pullEvent</code>. As a guideline, nearly any API function that can possibly take time to complete will fall into this category; some examples are:
* [[rednet.receive]] blocks until either a [[Rednet message (event)|rednet_message event]] or (if a timeout was requested) a matching [[Timer (event)|timer event]] occurs.
* [[Gps (API)|gps.locate]] blocks until either a number of [[Modem message (event)|modem_message events]] or (if a timeout was requested) a matching [[Timer (event)|timer event]] occurs.
* [[http.get]] blocks until an [[Http success (event)|HTTP success event]] or [[Http failure (event)|HTTP failure event]] occurs.
* [[IO (API)|io.read]] and the built-in [[read]] functions block waiting for, presumably, either [[Char (event)|char events]] or [[Key (event)|key events]].
* [[os.sleep]] blocks until a matching [[Timer (event)|timer event]] occurs.
* [[textutils.slowPrint]] calls [[os.sleep]].
* [[textutils.pagedPrint]] blocks until a [[Key (event)|key event]] occurs for each page.
* Most of the functions in the [[Turtle (API)|turtle API]] (with the exception of [[turtle.getItemCount]], [[turtle.getItemSpace]], and [[turtle.getFuelLevel]]) block waiting for a [[Turtle response (event)|turtle response event]].

Most of these can be worked around by using non-blocking equivalents that return immediately and then queue an event on completion (such as using [[http.request]]) or that deliver an event unconditionally (such as [[Char (Event)|char]] for keyboard input), then handling events in a way that is suitable for the application. However, if possible, it will often be easier to implement event dispatching instead, remembering that [[os.queueEvent]] can be used for inter-coroutine communication within an application. Another alternative, if you must use a custom protocol between your coroutines and dispatcher, might be to replace <code>os.pullEventRaw</code> with a new function that uses a mechanism appropriate to the application.

[[Category:APIs]]

Keys.getName

2013-05-05T23:21:24Z

Hawk777: Type-templateify, add nil return value possibility on failure, and clarify description

{{lowercase}}
{{Function
|name=keys.getName
|args={{type|int}} code
|api=keys
|returns={{type|string}} the name of the key, or [[nil]] if not a valid key code
|addon=ComputerCraft
|desc=Translates a numerical key code to a human-readable name. The human-readable name is one of the constants in the [[Keys (API)|keys API]].
|examples=
{{Example
|desc=Look up the name of key code 42.
|code=print(keys.getName(42))
|output=leftShift
}}
}}

[[Category:API_Functions]]

Keys (API)

2013-05-05T23:19:40Z

Hawk777: Add return type column

The Keys API provides a table of numerical codes corresponding to keyboard keys, suitable for decoding [[Key (event)|key events]].

<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
<tr><td colspan="3" 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]]  
keys (API)
</td></tr>

<tr><td style="width: 100px; background: #E0E0E0; padding: .4em; font-weight:bold;">Return</td><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>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{type|string}} keyName</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[keys.getName]]({{type|int}} code)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Translates a numerical key code to a human-readable name.</td></tr>

</table>

Although this API contains only one method, it also contains a vast number of constants, one per key, containing the numerical key codes for those keys. As of ComputerCraft 1.52, the following constants are defined:
* a
* b
* c
* d
* e
* f
* g
* h
* i
* j
* k
* l
* m
* n
* o
* p
* q
* r
* s
* t
* u
* v
* w
* x
* y
* z
* one
* two
* three
* four
* five
* six
* seven
* eight
* nine
* zero
* minus
* equals
* backspace
* tab
* leftBracket
* rightBracket
* enter
* leftCtrl
* semiColon
* apostrophe
* grave
* leftShift
* backslash
* comma
* period
* slash
* rightShift
* multiply
* leftAlt
* space
* capsLock
* f1
* f2
* f3
* f4
* f5
* f6
* f7
* f8
* f9
* f10
* numLock
* scollLock
* numPad7
* numPad8
* numPad9
* numPadSubtract
* numPad4
* numPad5
* numPad6
* numPadAdd
* numPad1
* numPad2
* numPad3
* numPad0
* numPadDecimal
* f11
* f12
* f13
* f14
* f15
* kana
* convert
* noconvert
* yen
* numPadEquals
* cimcumflex
* at
* colon
* underscore
* kanji
* stop
* ax
* numPadEnter
* rightCtrl
* numPadComma
* numPadDivide
* rightAlt
* pause
* home
* up
* pageUp
* left
* right
* end
* down
* pageDown
* insert
* delete

[[Category:APIs]]

Key (event)

2013-05-05T23:18:47Z

Hawk777: Add note about scan codes; note escape is not seen; remove needswork banner as an example has, in fact, been added earlier

{{Event
|name=key
|desc=Fired when any key except Escape is pressed while the terminal is focused.
|return1=The numerical key value of the key pressed
}}
{{Example
|desc=Print each key pressed on the keyboard whenever a ''key'' event is fired. Use Ctrl+T (Windows) to terminate the loop.
|code=
while true do
event, scancode = os.pullEvent("key")
print(tostring(scancode).." was pressed.")
end
|output=Any key that is pressed.
}}

==Key scan codes ==
[[File:CC-Keyboard-Charcodes.png|center|frame|250x250px|Click for a larger copy of this image - contains keys and their event numbers.]]

These scan codes are also available as constants in the [[Keys (API)|keys API]], and can be translated from numerical codes to strings using [[keys.getName]].

Http.post

2013-05-05T23:15:28Z

Hawk777: Type-templatify, link to handles documentation in API page, deduplicate description

{{lowercase}}
{{Function
|name=http.post
|args={{type|string}} url, {{type|string}} postData
|api=HTTP
|returns={{type|table}} a [[HTTP (API)#Handles|handle]] on success, or [[nil]] on failure
|addon=ComputerCraft
|desc=Sends a HTTP POST request to a website, synchronously. Returns when the request completes, successfully or not.
}}

[[Category:Lua_Core_Functions]]

Http.get

2013-05-05T23:14:06Z

Hawk777: Type-templatify, link to handles documentation in API page, deduplicate description, tidy URL in example

{{lowercase}}
{{Function
|name=http.get
|args={{type|string}} url
|api=HTTP
|returns={{type|table}} a [[HTTP (API)#Handles|handle]] on success, or [[nil]] on failure
|addon=ComputerCraft
|desc=Sends a HTTP GET request to a website, synchronously. Returns when the request completes, successfully or not.
|examples=
{{Example
|desc=Gets the content of example.com (in HTML)
|code=local sExample = http.get("http://example.com/") --Get contents of page<br />write(sExample.readAll()) --Read and print contents of page<br />sExample.close() --Just in case
|output=The source of http://example.com/
}}
}}

[[Category:Lua_Core_Functions]]

Http.request

2013-05-05T23:10:50Z

Hawk777: Document asynchrony

{{lowercase}}
{{Function
|name=http.request
|args={{type|string}} url<nowiki>[</nowiki>, {{type|string}} postData]
|api=HTTP
|addon=ComputerCraft
|desc=Sends a HTTP request to a website, asynchronously. Returns immediately, with an [[Http success (event)|http_success]] or [[Http failure (event)|http_failure]] event being delivered later to indicate the outcome. Issues a POST request if ''postData'' is provided, or a GET request if it is [[nil]] (or omitted).
|examples=
{{Example
|desc=Prints the code of a loading bar program if successful.
|code=http.request("http://pastebin.com/raw.php?i=Tk19jv43")
local requesting = true
while requesting do
local event, url, sourceText = os.pullEvent()
if event == "http_success" then
local respondedText = sourceText.readAll()
print(respondedText)
requesting = false
elseif event == "http_failure" then
print("Server didn't respond.")
requesting = false
end
end
}}
}}

[[Category:Lua_Core_Functions]]

HTTP (API)

2013-05-05T23:10:35Z

Hawk777: Document synchrony and asynchrony

:{|class="wikitable"
| '''The HTTP API must be enabled in mod_ComputerCraft.cfg before being used. To enable it open .minecraft/config/ComputerCraft.cfg and change enableAPI_http=false to enableAPI_http=true.'''
|}

The HTTP API allows interfacing with websites and downloading from them.

<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
<tr><td colspan="3" 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]]  
HTTP (API)
</td></tr>

<tr><td style="width: 100px; background: #E0E0E0; padding: .4em; font-weight:bold;">Return</td><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>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[http.request]]({{type|string}} url, <nowiki>[</nowiki>{{type|string}} postData])</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sends a HTTP request to a website, asynchronously.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{type|table}} handle</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[http.get]]({{type|string}} url)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sends a HTTP GET request to a website, synchronously.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{type|table}} handle</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[http.post]]({{type|string}} url, {{type|string}} postData)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sends a HTTP POST request to a website, synchronously.</td></tr>
</table>

[[http.request]] is used to send a HTTP request that completes asynchronously and generates an event (one of [[Http success (event)|http_success]] or [[Http failure (event)|http_failure]]). [[http.get]] and [[http.post]] execute [[http.request]] and block until the operation completes.

== Handles ==
All three operations make use of ''handles'', tables that contain functions to read data returned from the HTTP server. These handles act the same as the I/O handles returned by [[fs.open]] in read-only text mode, implementing the [[fs.open#Closing_a_file_handle|close]], [[fs.open#Files_opened_in_text_read_mode|readLine]], and [[fs.open#Files_opened_in_text_read_mode|readAll]] methods. These handles also implement the following function:

{{Function
|name=<var>h</var>.getResponseCode
|returns={{type|number}} HTTP response code
|api=HTTP
|desc=Returns the numerical [https://en.wikipedia.org/wiki/List_of_HTTP_status_codes HTTP response code] sent by the server
}}

[[Category:APIs]]

Http.request

2013-05-05T23:09:51Z

Hawk777: Document parameters, clarify description, remove return value (it DOES NOT return a value!), and remove excessive line breaks in example

{{lowercase}}
{{Function
|name=http.request
|args={{type|string}} url<nowiki>[</nowiki>, {{type|string}} postData]
|api=HTTP
|addon=ComputerCraft
|desc=Sends a HTTP request to a website. Returns immediately, with an [[Http success (event)|http_success]] or [[Http failure (event)|http_failure]] event being delivered later to indicate the outcome. Issues a POST request if ''postData'' is provided, or a GET request if it is [[nil]] (or omitted).
|examples=
{{Example
|desc=Prints the code of a loading bar program if successful.
|code=http.request("http://pastebin.com/raw.php?i=Tk19jv43")
local requesting = true
while requesting do
local event, url, sourceText = os.pullEvent()
if event == "http_success" then
local respondedText = sourceText.readAll()
print(respondedText)
requesting = false
elseif event == "http_failure" then
print("Server didn't respond.")
requesting = false
end
end
}}
}}

[[Category:Lua_Core_Functions]]

Http failure (event)

2013-05-05T23:05:26Z

Hawk777: Trim a bit, clarify description

{{Event
|name=http_failure
|return1=The URL to the website
|desc=Fired when a call to [[http.request]] fails, and used internally in [[http.get]] and [[http.post]].
}}
{{Example
|desc=Prints a message and quits when the requested URL could not be contacted.
|code=
http.request( "http://www.example-failure.com" )
while true do
event, url = os.pullEvent()
if event == "http_failure" then
print( "Cannot contact the server: "..url )
break
end
end
}}

Http success (event)

2013-05-05T23:03:52Z

Hawk777: Trim a bit, clarify description, point back at the handle description in HTTP API

{{Event
|name=http_success
|desc=Fired when a call to [[http.request]] completes successfully, and used internally in [[http.get]] and [[http.post]].
|return1=The URL to the website
|return2=A [[HTTP (API)#Handles|handle]] that allows reading the response sent from the server
}}
{{Example
|desc=Prints the response code from the server and the text returned from the server
|code=
http.request( "http://www.example.com" )
event, url, handle = os.pullEvent( "http_success" )
print( "Got a response with the status code: "..handle.getResponseCode() )
print( "With the text: "..handle.readAll() )
handle:close()
}}
{{Example
|desc=Prints all the available functions to call on the response from the server
|code=
http.request( "http://www.example.com" )
while true do
event, url, handle = os.pullEvent( "http_success" )
for k, v in pairs( handle ) do
print( k )
end
end
}}

HTTP (API)

2013-05-05T22:59:44Z

Hawk777: Tidying, add return value column, add getResponseCode documentation

:{|class="wikitable"
| '''The HTTP API must be enabled in mod_ComputerCraft.cfg before being used. To enable it open .minecraft/config/ComputerCraft.cfg and change enableAPI_http=false to enableAPI_http=true.'''
|}

The HTTP API allows interfacing with websites and downloading from them.

<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
<tr><td colspan="3" 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]]  
HTTP (API)
</td></tr>

<tr><td style="width: 100px; background: #E0E0E0; padding: .4em; font-weight:bold;">Return</td><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>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[http.request]]({{type|string}} url, <nowiki>[</nowiki>{{type|string}} postData])</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sends a HTTP request to a website.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{type|table}} handle</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[http.get]]({{type|string}} url)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sends a HTTP GET request to a website.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{type|table}} handle</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[http.post]]({{type|string}} url, {{type|string}} postData)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sends a HTTP POST request to a website.</td></tr>
</table>

[[http.request]] is used to send a HTTP request that completes asynchronously and generates an event (one of [[Http success (event)|http_success]] or [[Http failure (event)|http_failure]]). [[http.get]] and [[http.post]] execute [[http.request]] and block until the operation completes.

== Handles ==
All three operations make use of ''handles'', tables that contain functions to read data returned from the HTTP server. These handles act the same as the I/O handles returned by [[fs.open]] in read-only text mode, implementing the [[fs.open#Closing_a_file_handle|close]], [[fs.open#Files_opened_in_text_read_mode|readLine]], and [[fs.open#Files_opened_in_text_read_mode|readAll]] methods. These handles also implement the following function:

{{Function
|name=<var>h</var>.getResponseCode
|returns={{type|number}} HTTP response code
|api=HTTP
|desc=Returns the numerical [https://en.wikipedia.org/wiki/List_of_HTTP_status_codes HTTP response code] sent by the server
}}

[[Category:APIs]]

Help (API)

2013-04-23T19:53:31Z

Hawk777: Add return column, use type template, and update descriptions

The Help API allows you to mess around with the help files.

<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
<tr><td colspan="3" 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]]  
Help (API)
</td></tr>

<tr><td style="width: 100px; background: #E0E0E0; padding: .4em; font-weight:bold;">Return</td><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>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|string}} path</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[help.path]]()</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the list of locations the API will look in for help files.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[help.setPath]]({{Type|string}} path)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sets the list of locations the API will look in for help files.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|string}} path, or [[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[help.lookup]]({{Type|string}} topic)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the path to the file containing the help page for <var>topic</var>, or [[nil]] if the topic cannot be found.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|table}} topics</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[help.topics]]()</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns a list of all available help topics.</td></tr>

</table>

[[Category:APIs]]
td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the list of locations the API will look in for help files.

Help.topics

2013-04-23T19:53:28Z

Hawk777: Update description, reformat example and use ipairs to get sorted output, and use type template

{{lowercase}}
{{Function
|name=help.topics
|api=help
|returns={{Type|table}} all valid topics
|addon=ComputerCraft
|desc=Returns a list of all available help topics. This is all files found in the directories in the search path returned by [[help.path]]. The returned table is sorted.
|examples=
{{Example
|desc=Lists all valid help topics.
|code=for _, v in ipairs(help.topics()) do
print(v)
end
|output=List of all valid help topics
}}
}}

[[Category:API_Functions]]

Help.lookup

2013-04-23T19:53:26Z

Hawk777: Update description and use type template

{{lowercase}}
{{Function
|name=help.lookup
|args={{Type|string}} topic
|api=help
|returns={{Type|string}} path of help file for <var>topic</var> or [[nil]]
|addon=ComputerCraft
|desc=Returns the path to the file containing the help page for <var>topic</var>, or [[nil]] if the topic cannot be found. Each element of the string returned by [[help.path]] is searched, in order, for a file named <var>topic</var>.
|examples=
{{Example
|desc=Looks up the path for help on the disk API.
|code=print(help.lookup("disk"))
|output=/rom/help/disk
}}
}}

[[Category:API_Functions]]

Help.setPath

2013-04-23T19:53:24Z

Hawk777: Update description and use type template

{{lowercase}}
{{Function
|name=help.setPath
|args={{Type|string}} path
|api=help
|addon=ComputerCraft
|desc=Returns the list of locations the API will look in for help files. This should be a string containing one or more search paths separated by colons.
|examples=
{{Example
|desc=Sets the search path of the help API to /disk/help.
|code=help.setPath("/disk/help")
}}
}}

[[Category:API_Functions]]

Help.path

2013-04-23T19:53:22Z

Hawk777: Update description and use type template

{{lowercase}}
{{Function
|name=help.path
|api=help
|returns={{Type|string}} the path list, separated by colons
|addon=ComputerCraft
|desc=Returns the list of locations the API will look in for help files. This is returned in the form of a string containing multiple search paths separated by colons.
|examples=
{{Example
|desc=Prints the current path list for the help API.
|code=print(help.path())
|output=/rom/help
}}
}}

[[Category:API_Functions]]

Gps (API)

2013-04-23T19:37:20Z

Hawk777: Add return column to table, shift types over into return and method name columns, and reduce description by removing that information

The GPS API provides a method for turtles and computers to retrieve their own locations.

It broadcasts a PING message over [[Rednet_(API)|rednet]] and wait for responses. In order for this system to work, there must be at least 4 computers used as gps ''hosts'' which will respond and allow [[Wikipedia:Trilateration|trilateration]]. Three of these hosts should be in a plane, and the fourth should be either above or below the other three. You can set up hosts using the [[Gps (program)|gps program]].

Note: When entering in the coordinates for the ''host'' you need to put in the x,y,z of the computer, not the modem, as all rednet distances are measured from the block the computer is in.


<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
<tr><td colspan="3" 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]]  
Gps (API)
</td></tr>

<tr><td style="width: 100px; background: #E0E0E0; padding: .4em; font-weight:bold;">Return</td><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>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">({{Type|int}} x, {{Type|int}} y, {{Type|int}} z), or [[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">gps.locate(<nowiki>[</nowiki>{{Type|float}} timeout, <nowiki>[</nowiki>{{Type|boolean}} debug]])</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Tries to retrieve the computer or turtles own location. On success, returns the location of the turtle’s modem. On failure (if no responses are received for <var>timeout</var> seconds, by default 2), returns [[nil]]. If <var>debug</var> is <code>true</code>, debug messages are printed.</table>

== Example ==
print("Man I am so lost right now!")
local x, y, z = gps.locate(5)
if x == nil then
print("Nope, still lost :(")
else
print("I am at ",x," ",y," ",z)
end

== Vector Example ==
GPS position and navigation can be handled more easily using a [[vector (API)|vector]].

local home = vector.new(45, 85, 20)
local position = vector.new(gps.locate(5))
local displacement = position - home

print("I am ", displacement.tostring(), " away from home!!!")

[[Category:APIs]]
code>true

Coroutine (API)

2013-04-23T19:20:02Z

Hawk777: /* Interaction with Other APIs */ Explain how one might potentially do event dispatch

:{| border="1" class="wikitable"
| '''Bug'''
'''From ComputerCraft 1.3''' this API suffers from the problem of potentially spawning Java threads that live forever therefore, use of coroutines should be minimized. This is '''fixed in ComputerCraft 1.32+''', though.
|}

''This is for the Coroutine API. For the Coroutine Object, visit [[Coroutine (type)]].''

Coroutine is a default Lua 5.1 API defined [http://www.lua.org/manual/5.1/manual.html#5.2 here]. Please list any non-working functions on this page.

<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
<tr><td colspan="3" 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]]  
Coroutine (API)
</td></tr>

<tr><td style="width: 100px; background: #E0E0E0; padding: .4em; font-weight:bold;">Return</td><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>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|coroutine}} coro</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[coroutine.create]]({{Type|function}} f)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Creates a new coroutine.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|boolean}} success, …</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[coroutine.resume]]({{Type|coroutine}} coro, [var1], [var2], ...)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Starts or resumes an existing coroutine.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|coroutine}} coro</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[coroutine.running]]()</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the currently executing coroutine.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|string}} status</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[coroutine.status]](coroutine)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the status of the given coroutine.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|function}} coroutine wrapper</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[coroutine.wrap]](function)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Creates a new coroutine and wraps it in a function.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[var3], [var4], …</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[coroutine.yield]]([var1], [var2], …)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Pauses the currently executing coroutine and passes control to its caller.</td></tr>
</table>

== Coroutine States and Ancestry ==
Every coroutine is in one of four states:
* A ''suspended'' coroutine is one that has not yet been started or that has yielded. A suspended coroutine can become running if it is passed to [[coroutine.resume]].
* A ''running'' coroutine is one that is currently executing code. Only one coroutine can be running at a time on a particular computer. A running coroutine can become suspended if it [[coroutine.yield]], normal if it calls [[coroutine.resume]] on another coroutine, or dead by if it returns from its body function.
* A ''normal'' coroutine is one that, while running, resumed another coroutine (the ''child coroutine''). A normal coroutine can become running if its child calls [[coroutine.yield]] or returns from its function body.
* A ''dead'' coroutine is one that, while running, returned from its function body. A dead coroutine can never change state.

While suspended and dead coroutines simply sit loose with no connections to other coroutines, normal and running coroutines have an ancestry relationship between them. Exactly one coroutine is running at any given time, and the running coroutine has no children. Every running or normal coroutine except the top-level BIOS coroutine has a parent, and this relationship forms a chain with one end (the furthest ancestor) being the top-level BIOS coroutine and the other end (the furthest descendant) being the running coroutine. Remember that only the running coroutine can actually execute code, so any functions invoked must be invoked by that coroutine. Then, calling [[coroutine.resume]] makes the chain longer by taking a previously suspended coroutine, hanging it underneath the current coroutine as a new child, and making the current coroutine normal and the new child running. Meanwhile, calling [[coroutine.yield]] makes the chain shorter by turning the currently executing coroutine into a suspended coroutine, detaching it from the chain, and letting its former parent become running.

It is important not to confuse this coroutine chain with the function call stack. Each individual coroutine contains a complete function call stack of its own, rooted at the coroutine’s body function, whether the coroutine is running, normal, or suspended; the chain described in the previous paragraph refers to how entire coroutines are connected together.

== Examples ==
As the coroutine API is very tightly coupled and many of its function must be used to get any interesting results, examples are shown here instead of on the individual function pages.

=== Using the Basic Coroutine Functions ===
This example demonstrates using the basic coroutine functions to pass control and data between coroutines. This example prints the numbers 1 through 17 in order, showing how control flow moves through the main program coroutine and the two created coroutines, while using assertions to show how data flows through the program:

-- These variables will hold the coroutine objects.
local c1 = nil
local c2 = nil

-- This function will be the body of the first coroutine.
local function f1(x)
-- The main code, below, starts c1 first, passing 1.
-- Thus c1 should be running, c2 should be suspended (not started yet), and x should receive the value from main, 1.
-- STEP 2: Check these assumptions.
print(2)
assert(coroutine.status(c1) == "running")
assert(coroutine.status(c2) == "suspended")
assert(x == 1)
-- STEP 3: Run c2 until it yields, start it off with the value 2.
print(3)
success, value = coroutine.resume(c2, 2)
assert(success)
-- In step 6, c2 yields and passes back the value 3.
-- Then c2, having yielded, should be suspended, and c1 should be running again.
-- STEP 7: Check all that.
print(7)
assert(coroutine.status(c1) == "running")
assert(coroutine.status(c2) == "suspended")
assert(value == 3)
-- STEP 8: Run c2 again, passing it the value 4.
-- Since c2 has already run before, this time the 4 will come out of the yield() instead of appear as a function parameter.
print(8)
success, value = coroutine.resume(c2, 4)
-- In step 10, c2 yields and passes back the value 5.
-- Then c2, having yielded, should be suspended, and c1 should be running again.
-- STEP 11: Check all that.
print(11)
assert(coroutine.status(c1) == "running")
assert(coroutine.status(c2) == "suspended")
assert(value == 5)
-- STEP 12: Yield, turning c1 back into a suspended coroutine and continuing execution of the main program, passing back value 6.
print(12)
value = coroutine.yield(6)
end

-- This function will be the body of the second coroutine.
local function f2(x)
-- The first time c2 is run, it is run from f1, which passes 2.
-- Thus c1 should be normal (as we are nested inside it), c2 should be running, and x should receive the value from f1, 2.
-- STEP 4: Check these assumptions.
print(4)
assert(coroutine.status(c1) == "normal")
assert(coroutine.status(c2) == "running")
assert(x == 2)
-- Because c1 is not suspended, we should not be able to resume it.
-- STEP 5: Check this is correct.
print(5)
success, value = coroutine.resume(c1)
assert(not success)
assert(value == "cannot resume normal coroutine")
-- STEP 6: Yield, turning c2 back into a suspended coroutine and continuing execution of c1, passing back value 3.
print(6)
value = coroutine.yield(3)
-- In step 8, c1 resumed c2 again and passed the value 4.
-- c2 should now be running again, and c1 normal again.
-- STEP 9: Check all that.
print(9)
assert(coroutine.status(c1) == "normal")
assert(coroutine.status(c2) == "running")
assert(value == 4)
-- STEP 10: Yield, turning c2 back into a suspended coroutine and continuing execution of c1, passing back value 5.
print(10)
value = coroutine.yield(5)
-- In step 14, the main program resumed c2 directly and passed the value 7, bypassing c1.
-- So c2 should be running and c1 should be suspended.
-- STEP 15: Check all that.
print(15)
assert(coroutine.status(c1) == "suspended")
assert(coroutine.status(c2) == "running")
assert(value == 7)
-- STEP 16: Now die, returning value 8 to the main program.
print(16)
return 8
end

-- Construct the two coroutines.
c1 = coroutine.create(f1)
c2 = coroutine.create(f2)

-- Newly constructed coroutines are always suspended.
assert(coroutine.status(c1) == "suspended")
assert(coroutine.status(c2) == "suspended")

-- STEP 1: Run c1 until it yields, starting it off with the value 1.
print(1)
success, value = coroutine.resume(c1, 1)
assert(success)

-- In step 12, c1 should have yielded and returned the value 6.
-- So now c1 and c2 should both be suspended.
-- STEP 13: Check all that.
print(13)
assert(coroutine.status(c1) == "suspended")
assert(coroutine.status(c2) == "suspended")
assert(value == 6)

-- STEP 14: Run c2 directly, NOT nested inside c1 this time, passing it the value 7.
print(14)
success, value = coroutine.resume(c2, 7)
assert(success)

-- c2 should have exited normally, returning the value 8.
-- Therefore c1 should still be suspended, but c2 should be dead.
-- STEP 17: Check all that.
print(17)
assert(coroutine.status(c1) == "suspended")
assert(coroutine.status(c2) == "dead")
assert(value == 8)

=== Using Coroutine Wrapper Functions ===
This second example is virtually identical, but shows using [[coroutine.wrap]] and wrapper functions instead of the basic coroutine functions (checks of [[coroutine.status]] have been removed as the raw coroutine objects are not available):

-- These variables will hold the coroutine wrapper functions.
local cw1 = nil
local cw2 = nil

-- This function will be the body of the first coroutine.
local function f1(x)
-- The main code, below, starts c1 first, passing 1.
-- Thus c1 should be running, c2 should be suspended (not started yet), and x should receive the value from main, 1.
-- STEP 2: Check these assumptions.
print(2)
assert(x == 1)
-- STEP 3: Run c2 until it yields, start it off with the value 2.
print(3)
value = cw2(2)
-- In step 6, c2 yields and passes back the value 3.
-- Then c2, having yielded, should be suspended, and c1 should be running again.
-- STEP 7: Check all that.
print(7)
assert(value == 3)
-- STEP 8: Run c2 again, passing it the value 4.
-- Since c2 has already run before, this time the 4 will come out of the yield() instead of appear as a function parameter.
print(8)
value = cw2(4)
-- In step 10, c2 yields and passes back the value 5.
-- Then c2, having yielded, should be suspended, and c1 should be running again.
-- STEP 11: Check all that.
print(11)
assert(value == 5)
-- STEP 12: Yield, turning c1 back into a suspended coroutine and continuing execution of the main program, passing back value 6.
print(12)
value = coroutine.yield(6)
end

-- This function will be the body of the second coroutine.
local function f2(x)
-- The first time c2 is run, it is run from f1, which passes 2.
-- Thus c1 should be normal (as we are nested inside it), c2 should be running, and x should receive the value from f1, 2.
-- STEP 4: Check these assumptions.
print(4)
assert(x == 2)
-- Because c1 is not suspended, we should not be able to resume it.
-- STEP 5: Check this is correct (we must use pcall because an error will be raised).
print(5)
success, value = pcall(cw1)
assert(not success)
-- STEP 6: Yield, turning c2 back into a suspended coroutine and continuing execution of c1, passing back value 3.
print(6)
value = coroutine.yield(3)
-- In step 8, c1 resumed c2 again and passed the value 4.
-- c2 should now be running again, and c1 normal again.
-- STEP 9: Check all that.
print(9)
assert(value == 4)
-- STEP 10: Yield, turning c2 back into a suspended coroutine and continuing execution of c1, passing back value 5.
print(10)
value = coroutine.yield(5)
-- In step 14, the main program resumed c2 directly and passed the value 7, bypassing c1.
-- So c2 should be running and c1 should be suspended.
-- STEP 15: Check all that.
print(15)
assert(value == 7)
-- STEP 16: Now die, returning value 8 to the main program.
print(16)
return 8
end

-- Construct the two coroutine wrappers.
cw1 = coroutine.wrap(f1)
cw2 = coroutine.wrap(f2)

-- STEP 1: Run cw1 until it yields, starting it off with the value 1.
print(1)
value = cw1(1)

-- In step 12, c1 should have yielded and returned the value 6.
-- So now c1 and c2 should both be suspended.
-- STEP 13: Check all that.
print(13)
assert(value == 6)

-- STEP 14: Run c2 directly, NOT nested inside c1 this time, passing it the value 7.
print(14)
value = cw2(7)

-- c2 should have exited normally, returning the value 8.
-- Therefore c1 should still be suspended, but c2 should be dead.
-- STEP 17: Check all that.
print(17)
assert(value == 8)

== Interaction with Other APIs ==
Raw coroutines are not always safe to use with other API functions. The reason is that [[os.pullEventRaw]] (and therefore [[os.pullEvent]], which calls it) are themselves built using coroutines: <code>os.pullEventRaw</code> actually invokes [[coroutine.yield]], passing the event type filter up to what it expects is the [[Parallel (API)|parallel API]], which would resume the coroutine once a matching event arrives. This is how the parallel API allows other code to run while one function is blocking waiting for an event. However, it means if you call <code>os.pullEventRaw</code> ''or any other function that uses it'' while managing coroutines yourself, you will see a coroutine unexpectedly yield, with the parent [[coroutine.resume]] being passed as a return value the filter string passed to <code>os.pullEventRaw</code>.

In this situation, it is essential that a developer carefully audit any APIs (s)he may wish to use to verify whether they could possibly block—many APIs, even those one might not expect, fall into this category. Some examples are:
* [[rednet.receive]] blocks until either a [[Rednet message (event)|rednet_message event]] or (if a timeout was requested) a matching [[Timer (event)|timer event]] occurs.
* [[Gps (API)|gps.locate]] blocks until either a number of [[Modem message (event)|modem_message events]] or (if a timeout was requested) a matching [[Timer (event)|timer event]] occurs.
* [[http.get]] blocks until an [[Http success (event)|HTTP success event]] or [[Http failure (event)|HTTP failure event]] occurs.
* [[IO (API)|io.read]] and the built-in [[read]] functions block waiting for, presumably, either [[Char (event)|char events]] or [[Key (event)|key events]].
* [[os.sleep]] blocks until a matching [[Timer (event)|timer event]] occurs.
* [[textutils.slowPrint]] calls [[os.sleep]].
* [[textutils.pagedPrint]] blocks until a [[Key (event)|key event]] occurs for each page.
* Most of the functions in the [[Turtle (API)|turtle API]] (with the exception of [[turtle.getItemCount]], [[turtle.getItemSpace]], and [[turtle.getFuelLevel]]) block waiting for a [[Turtle response (event)|turtle response event]].

Although it is not always practical to do so, in some situations, the [[Parallel (API)|parallel API]] may be preferable to using coroutines directly, as it handles event dispatching properly. However, it does not allow chaining coroutine invocations, nor does it allow adding coroutines to the parallel set after parallel execution has started. If coroutines are to be used directly, an application may either ensure it avoids any blocking API calls, or may arrange to handle event dispatch the same way that the parallel API does so that the blocking functions work properly. For example, one might arrange the convention that the top-level coroutine in the application will call [[os.pullEvent]] and deliver any returned events to sub-coroutines, the same way that the parallel API does, thus allowing those sub-coroutines to themselves call [[os.pullEvent]], while insisting on a convention that more deeply nested coroutines never call [[os.pullEvent]] at all.

[[Category:APIs]]

Fs (API)

2013-04-22T19:43:38Z

Hawk777: Copy descriptions from function pages, add return column, and use type template

The FS API allows you to mess around with the filesystem.

<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
<tr><td colspan="3" 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]]  
Fs (API)
</td></tr>

<tr><td style="width: 100px; background: #E0E0E0; padding: .4em; font-weight:bold;">Return</td><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>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|table}} files</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[fs.list]]({{Type|string}} path)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns a list of all the files (including subdirectories but not their contents) contained in a directory, as a numerically indexed table.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|boolean}} exists</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[fs.exists]]({{Type|string}} path)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Checks if a path refers to an existing file or directory.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|boolean}} dir</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[fs.isDir]]({{Type|string}} path)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Checks if a path refers to an existing directory.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|boolean}} readOnly</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[fs.isReadOnly]]({{Type|string}} path)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Checks if a path is read-only (i.e. cannot be modified).</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|string}} name</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[fs.getName]]({{Type|string}} path)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Gets the final component of a pathname.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|string}} drive, or [[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[fs.getDrive]]({{Type|string}} path)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns the storage medium holding a path, or [[nil]] if the path does not exist.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|int}} size</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[fs.getSize]]({{Type|string}} path)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Gets the size of a file in bytes</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|int}} space</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[fs.getFreeSpace]]({{Type|string}} path)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Gets the remaining space in the given directory.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[fs.makeDir]]({{Type|string}} path)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Makes a directory.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[fs.move]]({{Type|string}} fromPath, {{Type|string}} toPath)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Moves a file or directory to a new location.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[fs.copy]]({{Type|string}} fromPath, {{Type|string}} toPath)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Copies a file or directory to a new location.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[fs.delete]]({{Type|string}} path)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Deletes a file or directory.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|string}} path</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[fs.combine]]({{Type|string}} basePath, {{Type|string}} localPath)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Combines two path components, returning a path consisting of the local path nested inside the base path.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|table}} handle</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[fs.open]]({{Type|string}} path, {{Type|string}} mode)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Opens a file so it can be read or written.</td></tr>
</table>

[[Category:APIs]]

==Path Names==
All of these functions except for [[fs.combine]] refer solely to <em>absolute paths</em>.<br />
This means that the current working directory, as set by the <code>cd</code> command or the [[shell.setDir]] function, is ignored. Each path name consists of a list of nonempty path components separated by forward slashes, and those path components are taken one by one with the first being contained in the root directory of the computer.

If you need to deal with paths provided by the user that may be absolute or may be relative to the current working directory, use [[shell.resolve]].

Unlike most real-world operating systems, ComputerCraft's absolute path name system does not need to be started with a forward slash ( / ), making the directory "a/b/c" the same as "/a/b/c". Leaving the slashes is just a matter of preference to the coder.

Fs.open

2013-04-22T19:43:34Z

Hawk777: Copy description from API page, change return, and use type template

{{lowercase}}
{{Function
|name=fs.open
|args={{Type|string}} path, {{Type|string}} mode
|api=fs
|returns={{Type|table}} the file handle, or [[nil]] on error (e.g. if <var>mode</var> was "r" and the file did not exist, or if <var>mode</var> was "w" or "a" and the file was in a read-only location)
|desc=
'''Supported File Modes'''
Opens a file so it can be read or written. <var>mode</var> consists of a first character which is one of the following:
* "r" to open the file read-only,
* "w" to open it for writing and remove any existing data on file open, or
* "a" to open for writing but keep existing data and append any writes to the end of the file
optionally followed by "b" to open the file for binary access instead of text access
(text mode will perform end-of-line conversions necessary to move text files between Windows, Linux, and Mac OS systems; binary files should not have these conversions applied as they will be corrupted)

When you have opened a file you must always close the file handle, or else data will not be saved.
|examples=
{{Example
|desc=Creates the file "abcd" for writing, and holds a file handle to it
|code=h = fs.open("abcd", "w")
}}
}}

== File Handles ==

A file handle allows access to a file. A file handle is a table; the functions within the table are accessed with the dot operator (<em>not</em> the colon operator, as may be more intuitive!). The examples below assume a file has already been opened and the handle stored in the variable <var>h</var>.

=== Closing a file handle ===

When you open a file you must remember to then close the handle! With the write modes supported by ComputerCraft all the data that you are writing to a file will not be written into the file until you close the file. A file opened in any mode exposes the following close function.
{{Function
|name=<var>h</var>.close
|api=fs
|desc=Closes the file handle, after which it can no longer be used
}}

=== Files opened in text read mode ===

A file opened in mode "r" (text read mode) exposes the following functions.

{{Function
|name=<var>h</var>.readLine
|api=fs
|returns=[[string]] the next line read from the file, with the end-of-line character stripped; or nil if there are no more lines in the file
|desc=Reads the next line from the file
}}
{{Function
|name=<var>h</var>.readAll
|api=fs
|returns=[[string]] the entire rest of the file, with the end-of-line character on the very last line (if present) stripped
|desc=Reads the all the text in the file
}}

=== Files opened in text write/append mode ===

A file opened in mode "w" (text write mode) or "a" (text append mode) exposes the following functions:

{{Function
|name=<var>h</var>.write
|args=[[string (type)|string]] data
|api=fs
|desc=Writes a string of characters to the file exactly as they appear in the string <var>data</var>
}}
{{Function
|name=<var>h</var>.writeLine
|args=[[string (type)|string]] data
|api=fs
|desc=Writes a string of characters to the file, then appends an end-of-line character
}}

=== Files opened in binary read mode ===

A file opened in mode "rb" (binary read mode) exposes the following functions:

{{Function
|name=<var>h</var>.read
|api=fs
|returns=[[int (type)|int]] the byte read from the file, or [[Nil|nil]] if there are no more bytes
|desc=Reads a single byte from the file and returns it
}}

=== Files opened in binary write/append mode ===

A file opened in mode "wb" (binary write mode) or "ab" (binary append mode) exposes the following functions:

{{Function
|name=<var>h</var>.write
|args=[[int (type)|int]] byte
|api=fs
|desc=Writes a single byte into the file
}}

[[Category:Lua_Core_Functions]]

Fs.combine

2013-04-22T19:43:32Z

Hawk777: Copy description from API page and use type template

{{lowercase}}
{{Function
|name=fs.combine
|args={{Type|string}} basePath, {{Type|string}} localPath
|api=fs
|returns={{Type|string}} the combined path
|desc=Combines two path components, returning a path consisting of the local path nested inside the base path. The resultant path consists of all the components of <var>localPath</var> inside all the components of <var>basePath</var>. Neither path needs to exist; this function only manipulates strings and does not touch the filesystem.
|examples=
{{Example
|desc=Computes the absolute path to a file called "d" inside a directory called "c", where "c" is itself inside a directory "b" which is inside a directory "a"
|code=print(fs.combine("a/b", "c/d"))
|output=a/b/c/d
}}
{{Example
|desc=An empty first path refers to the root directory, so the second path is returned
|code=print(fs.combine("", "c/d"))
|output=c/d
}}
{{Example
|desc=An empty second path refers to the first path directly, so the first path is returned
|code=print(fs.combine("a/b", ""))
|output=a/b
}}
{{Example
|desc=The last two examples make sense combined, returning the empty string (referring to the root directory)
|code=print(fs.combine("", ""))
|output=
}}
}}

[[Category:Lua_Core_Functions]]

Fs.delete

2013-04-22T19:43:30Z

Hawk777: Copy description from API page and use type template

{{lowercase}}
{{Function
|name=fs.delete
|args={{Type|string}} path
|api=fs
|desc=Deletes a file or directory. A nonexistent target is ignored; a directory is deleted along with all its contents.
|examples=
{{Example
|desc=Deletes a file or directory called "test1" in the root directory
|code=fs.delete("test1")
}}
}}

[[Category:Lua_Core_Functions]]

Fs.copy

2013-04-22T19:43:28Z

Hawk777: Copy description from API page and use type template

{{lowercase}}
{{Function
|name=fs.copy
|args={{Type|string}} fromPath, {{Type|string}} toPath
|api=fs
|desc=Copies a file or directory to a new location. The parent of the new location must be an existing, writable directory, <var>toPath</var> must include the target filename and cannot be only a directory to move the file into, and <var>toPath</var> itself must not already exist.
|examples=
{{Example
|desc=Makes a copy of a file "test1" in the root directory, calling it "test2" and storing the copy in a directory called "mydir"
|code=fs.copy("test1", "mydir/test2")
}}
}}

[[Category:Lua_Core_Functions]]

Fs.move

2013-04-22T19:43:26Z

Hawk777: Copy description from API page and use type template

{{lowercase}}
{{Function
|name=fs.move
|args={{Type|string}} fromPath, {{Type|string}} toPath
|api=fs
|desc=Moves a file or directory to a new location. The parent of the new location must be an existing, writable directory, <var>toPath</var> must include the target filename and cannot be only a directory to move the file into, and <var>toPath</var> itself must not already exist.
|examples=
{{Example
|desc=Renames a file from "test1" to "test2" and moves it from the root directory into a directory called "mydir"
|code=fs.move("test1", "mydir/test2")
}}
}}

[[Category:Lua_Core_Functions]]

Fs.makeDir

2013-04-22T19:43:24Z

Hawk777: Copy description from API page and use type template

{{lowercase}}
{{Function
|name=fs.makeDir
|args={{Type|string}} path
|api=fs
|desc=Makes a directory. If the location is already a directory, this function silently does nothing. If any parent path components are missing, they are also created. If the target location or any parent exists and is a file (instead of a directory), the operation fails.
|examples=
{{Example
|desc=Create a directory called "efgh" inside a directory called "abcd" ("abcd" need not exist; it will be created)
|code=fs.makeDir("abcd/efgh")
}}
}}

[[Category:Lua_Core_Functions]]

Fs.getFreeSpace

2013-04-22T19:43:22Z

Hawk777: Copy description from API page, clean up return, and use type template

{{lowercase}}
{{Function
|name=fs.getFreeSpace
|args={{Type|string}} path
|api=fs
|returns={{Type|int}} free space in bytes
|desc=Gets the remaining space in the given directory. The directory may refer to the computer’s local hard drive or to a floppy disk.
|examples=
{{Example
|desc=Computes the amount of free space on the computer
|code=print(tostring(fs.getFreeSpace("/")))
|output=10(can be different)
}}
}}

[[Category:Lua_Core_Functions]]

Fs.getSize

2013-04-22T19:43:20Z

Hawk777: Change description and use type template

{{lowercase}}
{{Function
|name=fs.getSize
|args={{Type|string}} path
|returns={{Type|int}} size in bytes
|api=fs
|desc=Gets the size of a file in bytes. This is not actually the exactly length of the file in bytes; rather, it is the amount that the file contributes towards the computer’s or disk’s storage quota. This is either 512 bytes or the actual length of the file plus the length of its name, whichever is larger.[http://www.computercraft.info/forums2/index.php?/topic/12243-152fsgetsize-returns-unexpected-values/]
|examples=
{{Example
|desc=Get the size of the shell from the ROM and print it
|code=print( fs.getSize("/rom/programs/shell") )
}}
}}

[[Category:Lua_Core_Functions]]

Fs.getDrive

2013-04-22T19:43:18Z

Hawk777: Use type template

{{lowercase}}
{{Function
|name=fs.getDrive
|args={{Type|string}} path
|api=fs
|returns={{Type|string}} the type of storage medium holding the path, or [[nil]] if the path does not exist
|desc=Returns the storage medium holding a path, or [[nil]] if the path does not exist. This is one of “hdd” if the path is stored on the computer’s local hard drive, “rom” if the path is in ROM, or the side on which a disk drive is attached if the path is on a [[Floppy Disk]]. As of ComputerCraft 1.52, a network-attached disk drive with a floppy in it returns the side of the computer on which the modem is attached, rather than the network name of the disk drive; presumably this is a bug.[http://www.computercraft.info/forums2/index.php?/topic/12369-mc-151-cc-152-fsgetdrive-wrong-answer-for-network-drives/]
|examples=
{{Example
|desc=Checks that the standard "startup" file is stored in ROM
|code=print(fs.getDrive("rom/startup"))
|output=rom
}}
}}

[[Category:Lua_Core_Functions]]

Fs.exists

2013-04-22T19:43:15Z

Hawk777: Copy description from API page, fix return styling, and use type template

{{lowercase}}
{{Function
|name=fs.exists
|args={{Type|string}} path
|api=fs
|returns={{Type|boolean}} <code>true</code> if <var>path</var> is an existing file or directory, or <code>false</code> if not
|desc=Checks if a path refers to an existing file or directory.
|examples=
{{Example
|desc=Checks that the "rom" directory exists
|code=print(fs.exists("rom"))
|output=true
}}
}}

[[Category:Lua_Core_Functions]]

Fs.list

2013-04-22T19:43:14Z

Hawk777: Update description to correct semantics for non-directories and use type template

{{lowercase}}
{{Function
|name=fs.list
|args={{Type|string}} path
|api=fs
|returns={{Type|table}} list of files and folders in <var>path</var>. If <var>path</var> is not a directory, an empty table is returned.
|desc=Returns a list of all the files (including subdirectories but not their contents) contained in a directory, as a numerically indexed table.
|examples=
{{Example
|desc=Displays a list of all files and folders in the root directory of a computer
|code=local FileList = fs.list("") --Table with all the files and directories available

for _, file in ipairs(FileList) do --Loop. Underscore because we don't use the key, ipairs so it's in order
print(file) --Print the file name
end --End the loop

|output=A list of all files and folders in the root directory as a table. Note that fs.list() could also be inserted directly into ipairs() or pairs().
}}
}}

[[Category:Lua_Core_Functions]]

Fs.isDir

2013-04-22T19:43:12Z

Hawk777: Copy description from API page, fix return formatting, and use type template

{{lowercase}}
{{Function
|name=fs.isDir
|args={{Type|string}} path
|api=fs
|returns={{Type|boolean}} <code>true</code> if <var>path</var> is an existing directory, or <code>false</code> if not (if it doesn't exist or if it is a regular file)
|desc=Checks if a path refers to an existing directory.
|examples=
{{Example
|desc=Checks that the "rom" directory is, in fact, a directory
|code=print(fs.isDir("rom"))
|output=true
}}
}}

[[Category:Lua_Core_Functions]]

Fs.isReadOnly

2013-04-22T19:43:10Z

Hawk777: Copy description from API page, fix return formatting, and use type template

{{lowercase}}
{{Function
|name=fs.isReadOnly
|args={{Type|string}} path
|api=fs
|returns={{Type|boolean}} <code>false</code> if <var>path</var> can be written to, or <code>true</code> if not
|desc=Checks if a path is read-only (i.e. cannot be modified). The path need not exist in order to perform this test. Note that the root directory and the mount points of any floppy disks are considered read-only, perhaps because they cannot ''themselves'' be modified, only their ''contents'' can be.
|examples=
{{Example
|desc=Checks that the "rom" directory is read-only, as its name implies
|code=print(fs.isReadOnly("rom"))
|output=true
}}
}}

[[Category:Lua_Core_Functions]]

Fs.getName

2013-04-22T19:43:06Z

Hawk777: Copy description from API page and use type template

{{lowercase}}
{{Function
|name=fs.getName
|args={{Type|string}} path
|api=fs
|returns={{Type|string}} the last path component of the path, or "root" if the path refers to the root directory
|desc=Gets the final component of a pathname. Pathname components are separated by forward slashes. The path need not exist.
|examples=
{{Example
|desc=Gets the last path component of a file
|code=print(fs.getName("rom/apis/colors"))
|output=colors
}}
}}

[[Category:Lua_Core_Functions]]

Fs.list

2013-04-22T19:18:47Z

Hawk777: Clarify that subdirectories’ contents are not returned

{{lowercase}}
{{Function
|name=fs.list
|args=[[string (type)|string]] path
|api=fs
|returns=[[table (type)|table]] list of files and folders in <var>path</var>, which must be a directory
|desc=Returns a list of all the files (including subdirectories but not their contents) contained in a directory, as a numerically indexed table.
|examples=
{{Example
|desc=Displays a list of all files and folders in the root directory of a computer
|code=local FileList = fs.list("") --Table with all the files and directories available

for _, file in ipairs(FileList) do --Loop. Underscore because we don't use the key, ipairs so it's in order
print(file) --Print the file name
end --End the loop

|output=A list of all files and folders in the root directory as a table. Note that fs.list() could also be inserted directly into ipairs() or pairs().
}}
}}

[[Category:Lua_Core_Functions]]

Disk.hasData

2013-04-22T19:12:56Z

Hawk777: Use type template

{{lowercase}}
{{Function
|name=disk.hasData
|args={{Type|string}} side
|api=disk
|returns={{Type|boolean}} whether the item is a floppy
|desc=Checks whether the current disk is a [[Floppy Disk|floppy disk]], as opposed to a [http://www.minecraftwiki.net/wiki/Music_Discs music disc] or other item.
|addon=ComputerCraft
|examples=
{{Example
|desc=Checks for what is in the bottom drive
|code=print(disk.hasData("bottom"))
|output=true if the item is a floppy, otherwise false
}}
}}

[[Category:API_Functions]]

Disk.isPresent

2013-04-22T19:12:54Z

Hawk777: Use type template

{{lowercase}}
{{Function
|name=disk.isPresent
|args={{Type|string}} side
|api=disk
|returns={{Type|boolean}} something is in the disk drive
|addon=ComputerCraft
|desc=Checks whether any item at all is in the disk drive.
|examples=
{{Example
|desc=Checks whether something is in the bottom disk drive or not
|code=print(disk.isPresent("bottom"))
|output=true if there is an item, otherwise false
}}
}}

[[Category:API_Functions]]

Disk.getMountPath

2013-04-22T19:12:52Z

Hawk777: Use type template

{{lowercase}}
{{Function
|name=disk.getMountPath
|args={{Type|string}} side
|api=disk
|returns={{Type|string}} path, or [[nil]] if the drive does not contain a floppy
|desc=Finds the directory name on the local computer where the contents of the [[Floppy Disk]] currently inserted in the drive can be found.
|addon=ComputerCraft
|examples=
{{Example
|desc=Finds the path of the bottom disk drive
|code=print(disk.getMountPath("bottom"))
|output=disk
}}
}}

[[Category:API_Functions]]

Disk.setLabel

2013-04-22T19:12:51Z

Hawk777: Use type template

{{lowercase}}
{{Function
|name=disk.setLabel
|args={{Type|string}} side, {{Type|string}} label
|api=disk
|addon=ComputerCraft
|desc=Writes a label to the floppy disk, which can be read with [[disk.getLabel]] and viewed in the item tooltip.
|examples=
{{Example
|desc=Sets the label of the disk in the bottom drive to "Floppy"
|code=disk.setLabel("bottom", "Floppy")
}}
}}

[[Category:API_Functions]]

Disk.getLabel

2013-04-22T19:12:49Z

Hawk777: Use type template

{{lowercase}}
{{Function
|name=disk.getLabel
|args={{Type|string}} side
|api=disk
|returns={{Type|string}} disk label, or [[nil]] if the item in the drive is neither a floppy disk nor a music record or if it is a floppy disk with no label
|addon=ComputerCraft
|desc=Reads the label from the disk in the drive. This is the label that shows up in the item tooltip (for both [[Floppy Disk|floppy disks]] and music records). For floppy disks, the label can be set with [[disk.setLabel]].
|examples=
{{Example
|desc=Checks for data saved on the disk in the bottom drive
|code=print(disk.getLabel("bottom"))
|output=Floppy --'''Output changes according to the disk label'''
}}
}}

[[Category:API_Functions]]

Disk.getID

2013-04-22T19:12:47Z

Hawk777: Use type template

{{lowercase}}
{{Function
|name=disk.getID
|args={{Type|string}} side
|api=disk
|returns={{Type|int}} the disk ID, or [[nil]] if the drive does not contain a [[Floppy Disk]]
|addon=ComputerCraft
|desc=Returns a number which uniquely identifies the disk in the drive and which is the name of the directory in the world’s <code>computer/disk</code> directory containing the disk’s data.
|examples=
{{Example
|desc=Prints the ID of the disk.
|code=print(disk.getID("bottom"))
|output=The ID of the disk (side varies).
}}
}}

[[Category:API_Functions]]

Disk.hasAudio

2013-04-22T19:12:46Z

Hawk777: Use type template

{{lowercase}}
{{Function
|name=disk.hasAudio
|args={{Type|string}} side
|api=disk
|returns={{Type|boolean}} whether there is audio saved on the disk
|addon=ComputerCraft
|desc=Checks whether the current disk is a [http://www.minecraftwiki.net/wiki/Music_Discs music disk], as opposed to a [[Floppy Disk|floppy disk]] or other item.
|examples=
{{Example
|desc=Checks for audio saved on the disk in the bottom drive
|code=print(disk.hasAudio("bottom"))
|output=true if there is audio, otherwise false
}}
}}

[[Category:API_Functions]]

Disk.getAudioTitle

2013-04-22T19:12:44Z

Hawk777: Use type template

{{lowercase}}
{{Function
|name=disk.getAudioTitle
|args={{Type|string}} side
|api=disk
|returns={{Type|string}} the track title, or [[nil]] if there is not a music record in the drive
|addon=ComputerCraft
|desc=Reads the title of the audio track from the music record in the drive. The [[disk.getLabel]] function also returns the track title of a music record.
|examples=
{{Example
|desc=Returns the title of an audio disk
|code=print(disk.getAudioTitle("bottom"))
|output=C418 - ward '''Output changes according to the audio title'''
}}
}}

[[Category:API_Functions]]

Disk.playAudio

2013-04-22T19:12:43Z

Hawk777: Use type template

{{lowercase}}
{{Function
|name=disk.playAudio
|args={{Type|string}} side
|api=disk
|addon=ComputerCraft
|desc=Starts playing the music record in the drive. If any record is already playing on any disk drive, it stops before the target drive starts playing. The record stops when it reaches the end of the track, when it is removed from the drive, when [[disk.stopAudio]] is called, or when another record is started.
|examples=
{{Example
|desc=Plays the audio found on the disk on the bottom drive (if any)
|code=disk.playAudio("bottom")
}}
}}

[[Category:API_Functions]]

Disk.stopAudio

2013-04-22T19:12:41Z

Hawk777: Use type template

{{lowercase}}
{{Function
|name=disk.stopAudio
|args={{Type|string}} side
|api=disk
|addon=ComputerCraft
|desc=Stops the music record in the drive from playing, if it was started with [[disk.playAudio]].
|examples=
{{Example
|desc=Stops the audio playing on the disk on the bottom drive (if any)
|code=disk.stopAudio("bottom")
}}
}}

[[Category:API_Functions]]

Disk.eject

2013-04-22T19:12:39Z

Hawk777: Use type template

{{lowercase}}
{{Function
|name=disk.eject
|args={{Type|string}} side
|api=disk
|addon=ComputerCraft
|desc=Ejects any item currently in the drive, spilling it into the world as a loose item.
|examples=
{{Example
|desc=Ejects the disk in the bottom drive
|code=disk.eject("bottom")
}}
}}

[[Category:API_Functions]]

Disk (API)

2013-04-22T19:08:32Z

Hawk777: Fix template transclusion

''If you were looking for the item, please see [[Floppy Disk]].''

The Disk API allows you to interact with disk drives. These functions can operate on locally attached or remote disk drives. To use a locally attached drive, specify “side” as one of the six sides (e.g. “left”); to use a remote disk drive, specify its name as printed when enabling its modem (e.g. “drive_0”).

<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
<tr><td colspan="3" 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]]  
Disk (API)
</td></tr>

<tr><td style="width: 100px; background: #E0E0E0; padding: .4em; font-weight:bold;">Return</td><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>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|boolean}} present</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[disk.isPresent|disk.isPresent]]({{Type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Checks whether any item at all is in the disk drive.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|boolean}} disk</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[disk.hasData|disk.hasData]]({{Type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Checks whether the current disk is a [[Floppy Disk|floppy disk]], as opposed to a [http://www.minecraftwiki.net/wiki/Music_Discs music disc] or other item.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|string}} path, or [[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[disk.getMountPath|disk.getMountPath]]({{Type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Finds the directory name on the local computer where the contents of the Floppy Disk currently inserted in the drive can be found.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[disk.setLabel|disk.setLabel]]({{Type|string}} side, {{Type|string}} label)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Writes a label to the floppy disk, which can be read with [[disk.getLabel]] and viewed in the item tooltip.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|string}} label</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[disk.getLabel|disk.getLabel]]({{Type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Reads the label from the disk in the drive.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|int}} id</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[disk.getID|disk.getID]]({{Type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns a number which uniquely identifies the disk in the drive and which is the name of the directory in the world’s <code>computer/disk</code> directory containing the disk’s data.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|boolean}} audio</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[disk.hasAudio|disk.hasAudio]]({{Type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Checks whether the current disk is a [http://www.minecraftwiki.net/wiki/Music_Discs music disk], as opposed to a [[Floppy Disk|floppy disk]] or other item.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">{{Type|string}} title</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[disk.getAudioTitle|disk.getAudioTitle]]({{Type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Reads the title of the audio track from the music record in the drive.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[disk.playAudio|disk.playAudio]]({{Type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Starts playing the music record in the drive.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[disk.stopAudio|disk.stopAudio]]({{Type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Stops the music record in the drive from playing, if it was started with [[disk.playAudio]].</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[nil]]</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[disk.eject|disk.eject]]({{Type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Ejects any item currently in the drive, spilling it into the world as a loose item.</td></tr>
</table>

[[Category:APIs]]
/td>

Disk.hasAudio

2013-04-22T19:07:59Z

Hawk777: Take better description from function table on API page

{{lowercase}}
{{Function
|name=disk.hasAudio
|args=[[string (type)|string]] side
|api=disk
|returns=[[boolean_(type)|boolean]] whether there is audio saved on the disk
|addon=ComputerCraft
|desc=Checks whether the current disk is a [http://www.minecraftwiki.net/wiki/Music_Discs music disk], as opposed to a [[Floppy Disk|floppy disk]] or other item.
|examples=
{{Example
|desc=Checks for audio saved on the disk in the bottom drive
|code=print(disk.hasAudio("bottom"))
|output=true if there is audio, otherwise false
}}
}}

[[Category:API_Functions]]

Disk.hasData

2013-04-22T19:07:54Z

Hawk777: Take better description from function table on API page

{{lowercase}}
{{Function
|name=disk.hasData
|args=[[string (type)|string]] side
|api=disk
|returns=[[boolean_(type)|boolean]] whether the item is a floppy
|desc=Checks whether the current disk is a [[Floppy Disk|floppy disk]], as opposed to a [http://www.minecraftwiki.net/wiki/Music_Discs music disc] or other item.
|addon=ComputerCraft
|examples=
{{Example
|desc=Checks for what is in the bottom drive
|code=print(disk.hasData("bottom"))
|output=true if the item is a floppy, otherwise false
}}
}}

[[Category:API_Functions]]