ComputerCraft Wiki - User contributions [en]

HTTP (API)

2014-06-05T21:46:27Z

AgentE382:

:{|class="wikitable"
| '''The HTTP API must be enabled in ComputerCraft.cfg before being used. To enable it see [http://www.computercraft.info/forums2/index.php?/topic/17533-how-to-enable-the-http-api/ this tutorial].'''
|}

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 [, {{type|string}} postData [, {{type|table}} headers]])</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 [, {{type|table}} headers])</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 [, {{type|table}} headers])</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
}}

== Headers ==
As of '''ComputerCraft 1.63''', you can optionally set custom headers. This also means that you can override default headers such as the User-Agent.
{{Example
|desc=Sends a request to http://example.com/ with the custom headers.
|code=<nowiki>local headers = {
["User-Agent"] = "A custom user-agent!", -- Overrides the default User-Agent.
["Hi"] = "Hello" -- A non-standard custom header field.
}
http.get("http://example.com/", headers)</nowiki>
}}
=== Caution ===
You '''must''' either pass a ''string'' or ''nil'' as the second argument of http.request(). It will silently fail if you try to pass a header table as the second argument.
<pre>
http.request("http://example.com/", headers) -- This will produce a normal GET request.
http.request("http://example.com/", nil, headers) -- This will produce a GET request with your custom headers.
</pre>

[[Category:APIs]]

Thread (type)

2014-03-25T02:33:33Z

AgentE382: Added to "type" category.

#REDIRECT [[Coroutine_(type)]]
[[Category:Lua Types]]

Thread (type)

2014-03-25T02:32:43Z

AgentE382: Added redirect for completeness.

#REDIRECT [[Coroutine_(type)]]

Function (type)

2014-03-25T02:29:15Z

AgentE382: Added to "type" category.

[[Category:Tutorials]]
{{Tutorial
|name=Functions
|desc=An introduction to functions.
|objective=To gain an understanding of how Functions work, and how to use them
|prereqs=[[Variables|A basic understanding of Variables]].
}}

== What are functions? ==

Functions are a useful tool that helps simplify code, separating it by functionality and reducing repetitiveness. Understanding functions is key to becoming a successful coder. When a function is defined in Lua, it will most likely look like this:
function FunctionName()
--Do stuff
end
But may occasionally look more like a regular variable
Functionname=function()
--Do stuff
end

Both methods will yield the same result, so it's generally down to personal preference. Since functions are treated as normal variables, it is also possible to copy a function to a new variable
NewFunctionname=OldFunctionName
Note that here, we aren't using the "()" present in the other methods. This is because we're using OldFunctionName as a variable, and not calling it as a function.

== How do I use functions? ==

More than likely, if you've followed the "Hello World" tutorial, you have already used functions. Without standard in-built functions such as write() and print(), it would be impossible to interact with a user. Whenever you see brackets after a variable name, you know it's a function.

For our first example, we will write a simple function that will use write()
function MyFunction(Str)
write(Str)
end
MyFunction("I am writing text to the screen!\n")

If you have successfully written and executed this script, it should write "I am writing text to the screen!" on the screen. Notice how the function has a variable name in the brackets. This is called an "'''argument'''", and will likely be crucial to your functions later. There can be any number of arguments, separated by commas, and arguments can be any type of variable, including other functions. It is also very important to call your function after you have defined it otherwise you will get an error like "attempt to call nil".

Add the following line to your code
MyFunction( true )
This will pass a boolean value to your function, and it will error as it reaches the write(), which can't use a boolean value. To fix this, we'll need to validate what type of variable is being given. Try adding another line so your code looks like this:
function MyFunction( Str )
if type( Str ) ~= "string" then return end
write( Str )
end
MyFunction( "I am writing text to the screen!\n" )
MyFunction( true )

The "type" functions will give you a string with the type of variable you give it. In this case, if the variable is not a string, it will run "return". Return will be described in more detail later in this tutorial, but for now we only need to know it ends the function, so any code after it will not be run. If you run your script now, you will see that there will be no error when it tries to use the boolean value. In fact, it will produce nothing at all, which may not be desirable. Edit the return line so it reads as follows
if type( Str ) ~= "string" then print("Bad argument #1 to MyFunction: String expected, got ".. type( Str ).."!\n") return end
If you run the code again, you will find it now gives an error when it reaches the boolean. The difference between this and the usual error() command called for a real error, is that this won't exit your code, and any line afterwards will still run as normal.

All this script really does is give a new name to the write() function, so there is a simpler way to do it. Before reading the following code, see if you can use your current knowledge to work it out for yourself.

The simplest way to get a new name for a function is as follows.
MyFunction = write
This means that any call to MyFunction() will act as write() did. Note that any changes to write() ''after'' this line will not edit MyFunction, which is why this method is often used to back up a built-in function before it's overwritten. As an example, someone may want to disable the write() function, but still have a way to use it when necessary.
MyFunction = write
write = function() MyFunction("This function has been disabled!\n") end
This will write "This function has been disabled!" every time someone tries to use write()

== Return ==

Sometimes you will want a function to give a value back when it is done. This is the purpose of "return", it will return one or more values and end the function.
local function RandomNumber()
local rand = math.random(0,10)
return rand
end
local Num = RandomNumber()

This will set Num to a random number between 0 and 10. Notice how this time we are including the () for the function, this means we're calling the function rather than using it as a variable.

[[Category:Lua_Types]]