Difference between revisions of "Making an API (tutorial)"

From ComputerCraft Wiki
Jump to: navigation, search
m
 
(14 intermediate revisions by 12 users not shown)
Line 1: Line 1:
 +
== Making an API ==
  
== MAKING AN API - a tutorial by TheVarmari ==
+
An API is a program that is not directly executed, but is a collection of variables that can be accessed from any program on that computer.
'''NOTE:''' There is a better tutorial in the [http://www.computercraft.info/forums2/ forums].
+
Use this if you prefer to use ccwiki.
+
  
 +
To make an API, you must create a new file. I will call it ''myapi''. Fill it with variable declarations as normal, but without the ''local'' keyword:
  
== Introduction ==
+
<pre>
Hello, dear Computercraft Wiki user!
+
-- My awesome new API
Today I will tell you how to make an functioning API.
+
Let's get started!
+
  
 +
myvar = "Hello World!"
  
== Making the API file ==
+
function myCoolNewFunction()
First we need to define what our API will be called.
+
    print(myvar)
In this case, I use exampleAPI.
+
end
Now edit the file you want your API to be called.
+
</pre>
''NOTE: If it exists, call it something else''
+
  
=== The code ===
+
Now try it out. Save and exit the file, then open the ''lua'' program on your ingame computer. Then type:
Now, we need to put some functions in it!
+
Why don't we start with the basics;
+
  
<code>
+
<pre>
-- this is the file exampleAPI
+
os.loadAPI("myapi") -- replace myapi with the name of your API.
-- our first function:
+
myapi.myCoolNewFunction()
function printMessage()
+
</pre>
  print("message")
+
end
+
</code>
+
Which basically prints "message" when excecuted.
+
Save the file.
+
  
=== Including the API ===
+
If you have written the program correctly, you will see ''Hello World!'' printed to your screen. Now try:
Now that we have the API done, let's include it in some file!
+
Because we speak about APIs, we do it the proper way.
+
No shell.run's!
+
  
Edit the file you want to include the API in.
+
<pre>
In my case, it is called exampleFile.
+
print(myapi.myvar)
Now, we include the API in it by typing this to the '''first''' row:
+
</pre>
<code>
+
os.loadAPI("exampleAPI")
+
</code>
+
This loads the API into the file's memory.
+
''NOTE: You have to do this for every file you include it in.
+
CC doesn't have long-term memory.''
+
  
=== Using the API ===
+
You should also see ''Hello World!'' printed to your screen. Congratulations, this is your first API!
Now that that's over, let's include the printMessage command from our API.
+
Lua loads API's as tables, so you have to use api_name.function_name(function_arguments)
+
  
In my case, I use
 
<code>
 
exampleAPI.printMessage()
 
</code>
 
Ta-da! It printed out "message"!
 
  
== A couple of words ==
+
== Locals vs Globals ==
Thank you for reading this tutorial, it sure was fun to make!
+
 
Correct any mistakes I did!  
+
OK, lets go back to our API.
[[User:TheVarmari|TheVarmari]] 16:59, 22 February 2012 (UTC)
+
 
 +
<pre>
 +
-- My awesome new API
 +
 
 +
myvar = "Hello World!"
 +
 
 +
function myCoolNewFunction()
 +
    print(myvar)
 +
end
 +
</pre>
 +
 
 +
If we change our declaration for myvar to local, like this:
 +
 
 +
<pre>
 +
-- My awesome new API
 +
 
 +
local myvar = "Hello World!"
 +
 
 +
function myCoolNewFunction()
 +
    print(myvar)
 +
end
 +
</pre>
 +
 
 +
we should get the same result if we call myCoolNewFunction(). '''REMEMBER: you will need to load the API again to apply your changes!'''
 +
 
 +
But what happens if you try ''print(myapi.myvar)''?
 +
 
 +
<pre>
 +
 
 +
</pre>
 +
 
 +
It prints nothing. This is because we changed the declaration for myvar to local! This is useful if you want to have a variable visible to only your API. It will also work with functions, like this.
 +
 
 +
<pre>
 +
-- My awesome new API
 +
 
 +
local myvar = "Hello World!"
 +
 
 +
local function myCoolNewFunction()
 +
    print(myvar)
 +
end
 +
</pre>
 +
 
 +
Now if you try to call myCoolNewFunction(), you will get an ''attempt to call nil'' error.
  
 
[[Category:Tutorials]]
 
[[Category:Tutorials]]

Latest revision as of 02:37, 26 October 2013

Making an API

An API is a program that is not directly executed, but is a collection of variables that can be accessed from any program on that computer.

To make an API, you must create a new file. I will call it myapi. Fill it with variable declarations as normal, but without the local keyword:

-- My awesome new API

myvar = "Hello World!"

function myCoolNewFunction()
    print(myvar)
end

Now try it out. Save and exit the file, then open the lua program on your ingame computer. Then type:

os.loadAPI("myapi") -- replace myapi with the name of your API.
myapi.myCoolNewFunction()

If you have written the program correctly, you will see Hello World! printed to your screen. Now try:

print(myapi.myvar)

You should also see Hello World! printed to your screen. Congratulations, this is your first API!


Locals vs Globals

OK, lets go back to our API.

-- My awesome new API

myvar = "Hello World!"

function myCoolNewFunction()
    print(myvar)
end

If we change our declaration for myvar to local, like this:

-- My awesome new API

local myvar = "Hello World!"

function myCoolNewFunction()
    print(myvar)
end

we should get the same result if we call myCoolNewFunction(). REMEMBER: you will need to load the API again to apply your changes!

But what happens if you try print(myapi.myvar)?


It prints nothing. This is because we changed the declaration for myvar to local! This is useful if you want to have a variable visible to only your API. It will also work with functions, like this.

-- My awesome new API

local myvar = "Hello World!"

local function myCoolNewFunction()
    print(myvar)
end

Now if you try to call myCoolNewFunction(), you will get an attempt to call nil error.