Jump to content




Api Basics


13 replies to this topic

#1 Yevano

  • Members
  • 376 posts
  • LocationUSA

Posted 02 September 2013 - 09:14 AM

This is a tutorial in the Ask a Pro Renewal Project series.

In this tutorial, you will learn why APIs are used, how to use them, and how to create your own API. It is helpful to first read Lqyd's series on Computer Basics (start here) before reading this tutorial. You should also have at least basic knowledge of Lua. For the Programming in Lua manual, go here.

The API (Application Programming Interface) system in ComputerCraft provides a standard way to load libraries from separate files. Without the API system, you would find yourself making programs which contain the same code to do common things. For example, suppose you write a custom text editor, and you write many GUI functions for it inside the program. Later, you might want to do something else with these GUI functions, like create a file explorer. The problem is, you would have to copy and paste all of those functions from your old program into the new one. You'll end up spending more time and writing more code than you bargained for! A common solution is to separate your common functions into an API. This way, any program you make which needs to use those GUI functions can just call them from the API, and you can make improvements to your API in one file, instead of having to make changes across multiple files.

Let's first have a look at the help message for the apis command. Enter help apis into the shell prompt.

Posted Image


To restate what the picture says, the apis command lists all of the currently loaded APIs. We're also told that we can run help <api> (e.g. help os) to get help for a specific API, and the message tells us how we can load an API using os.loadAPI. Let's first try running apis and see what the console spits at us.

Posted Image


What we have here is a complete list of all the APIs that are automatically loaded from the /rom/apis/ folder when CraftOS starts. You don't have to load these yourself, since they're automatically made available. Let's try using some of these APIs in the Lua prompt. Open the Lua prompt by entering lua into the shell prompt, and then enter these lines into the Lua prompt.

math.floor(22.2)
string.sub("Hello", 2, 4)
textutils.serialize({a=2, b={"b"}, c="c"})


Posted Image


Exit the Lua prompt by entering exit() into the Lua prompt. By example, you can see that you can call an API function using the form someAPI.someFunction(...). Now let's look at how we can create and use our own API. Start off by creating the file that will hold the API functions. Enter edit testAPI into the shell prompt. Then, enter the code into the editor as shown below.

function sayHello()
    print("Hello from testAPI!")
end

Posted Image


Press Ctrl and select exit to leave the editor. The sayHello function will now be available to any program that loads this API. Let's see that in action. Go back to the Lua prompt and enter os.loadAPI("testAPI"). This will load our API so that any program can use it. Note that the argument given to os.loadAPI must be the precise path to the API file. The name of the file determines the name of the API in code. To make sure it's loaded, run the apis command again.

Posted Image


If you look closely, you can see that our API is now listed! Since it's loaded, let's try calling that function we defined inside of it. Go back to the Lua prompt and enter testAPI.sayHello().

Posted Image


Now that we're done with it, let's unload the API. Enter os.unloadAPI("testAPI") into the Lua prompt. Just like os.loadAPI, the argument must be the precise path to the API you want to unload. Exit the Lua prompt and run the apis command again so we can verify the API has been unloaded.

Posted Image


Our API is no longer listed, since it has been unloaded.

Let's backtrack. In this tutorial you learned:
  • Why APIs are used.
  • How to call API functions.
  • How to create, load, and unload your own simple API.
That's it, I'll be working on another API tutorial within probably the next few days. There will be a link here when it's done. Feedback is appreciated.

#2 Zudo

  • Members
  • 800 posts
  • LocationUK

Posted 02 September 2013 - 12:18 PM

This is a nice tutorial :)

#3 MudkipTheEpic

  • Members
  • 639 posts
  • LocationWhere you'd least expect it.

Posted 02 September 2013 - 01:49 PM

You never explained what functions are.

#4 Yevano

  • Members
  • 376 posts
  • LocationUSA

Posted 02 September 2013 - 03:14 PM

View PostMudkipTheEpic, on 02 September 2013 - 01:49 PM, said:

You never explained what functions are.

I don't think an explanation on functions would really be appropriate for this tutorial, since that has more to do with the actual language than how APIs work. Now that you mention it, though, I will go ahead and link to the PIL website for those who may not know Lua.

#5 theoriginalbit

    Semi-Professional ComputerCrafter

  • Moderators
  • 7,332 posts
  • LocationAustralia

Posted 02 September 2013 - 03:22 PM

View PostYevano, on 02 September 2013 - 03:14 PM, said:

I don't think an explanation on functions would really be appropriate for this tutorial, since that has more to do with the actual language than how APIs work. Now that you mention it, though, I will go ahead and link to the PIL website for those who may not know Lua.

I was originally going to side with you, stating that it would be out of the scope, but then when I read the AaP Renewal thread again, I found that there aren't really any "Lua basics/intermediate" threads that would explain things like functions. For yours however it did say this

Quote

API basics - purpose for using, functions in APIs, simple example API
So it says functions in APIs, so it may be worth putting a basic explanation, Lyqyd will ultimately have the overall say as to whether you should or not though.

Also I suggest you put up the top about how this is part of the Renewal series, like Lyqyd has on his two.

EDIT: Apparently I hit post instead of "more reply options", gimme a second done

Edited by theoriginalbit, 02 September 2013 - 03:26 PM.


#6 Yevano

  • Members
  • 376 posts
  • LocationUSA

Posted 02 September 2013 - 03:34 PM

View Posttheoriginalbit, on 02 September 2013 - 03:22 PM, said:

View PostYevano, on 02 September 2013 - 03:14 PM, said:

I don't think an explanation on functions would really be appropriate for this tutorial, since that has more to do with the actual language than how APIs work. Now that you mention it, though, I will go ahead and link to the PIL website for those who may not know Lua.

I was originally going to side with you, stating that it would be out of the scope, but then when I read the AaP Renewal thread again, I found that there aren't really any "Lua basics/intermediate" threads that would explain things like functions. For yours however it did say this

Quote

API basics - purpose for using, functions in APIs, simple example API
So it says functions in APIs, so it may be worth putting a basic explanation, Lyqyd will ultimately have the overall say as to whether you should or not though.

Also I suggest you put up the top about how this is part of the Renewal series, like Lyqyd has on his two.

EDIT: Apparently I hit post instead of "more reply options", gimme a second done

I assumed there weren't supposed to be any Lua tutorials since there are already many on the Internet, which is why I linked to PIL. I could be interpreting that wrong, though. And yeah I'll put the AAP bit at the top of OP.

#7 Lyqyd

    Lua Liquidator

  • Moderators
  • 8,465 posts

Posted 02 September 2013 - 03:39 PM

We are generally steering away from trying to tackle Lua language constructs ourselves, since they are so well-documented elsewhere. A quick synopsis and link to other documentation of a newly-introduced concept is probably a good thing to have, though. I will be sure to add some links to the PIL, reference manual, and Lua-users wiki to Computer Basics 1 and possibly 2 as well.

However, if we find that there is no documentation or tutorials written at an appropriate level for what we are going for (for instance, the Reference Manual is often too dense and technical), we can come up with a Lua series highlighting a concept at a time. I hope this doesn't turn out to be necessary.

#8 Lyqyd

    Lua Liquidator

  • Moderators
  • 8,465 posts

Posted 03 September 2013 - 01:04 PM

Double posting to add feedback:

This is definitely a good API basics tutorial, a solid foundation. I would suggest that we add the code for our sayHello function in a code block on the forum post rather than solely existing in the image, in case the image were to go down or be unavailable for other reasons.

#9 Yevano

  • Members
  • 376 posts
  • LocationUSA

Posted 03 September 2013 - 03:39 PM

View PostLyqyd, on 03 September 2013 - 01:04 PM, said:

Double posting to add feedback:

This is definitely a good API basics tutorial, a solid foundation. I would suggest that we add the code for our sayHello function in a code block on the forum post rather than solely existing in the image, in case the image were to go down or be unavailable for other reasons.

Thanks for the feedback. Added a code block above the image.

#10 itsme

  • Members
  • 9 posts

Posted 06 September 2013 - 06:42 AM

Hello!
Which directory should I copy my custom API file to, so that it can be loaded automatically (without using the os.loadAPI() function). The wiki states: "If you're playing single-player or you're running the multiplayer server, you can add those APIs to "rom/apis" and they will automatically be loaded on every computer in the world." but there is no such directory. The SP & MP ComputerCraft mod resides in a zip file. I'm using the latest Tekkit Lite.

Thanks

#11 Yevano

  • Members
  • 376 posts
  • LocationUSA

Posted 06 September 2013 - 04:46 PM

View Postitsme, on 06 September 2013 - 06:42 AM, said:

Hello!
Which directory should I copy my custom API file to, so that it can be loaded automatically (without using the os.loadAPI() function). The wiki states: "If you're playing single-player or you're running the multiplayer server, you can add those APIs to "rom/apis" and they will automatically be loaded on every computer in the world." but there is no such directory. The SP & MP ComputerCraft mod resides in a zip file. I'm using the latest Tekkit Lite.

Thanks

It's inside the lua folder which resides in your computercraft mod zip. Another option, however, is to create a startup file in your computer which loads the API. You could even do this for all computers automatically by using resource packs (Do some research on those. I've never used them.).

#12 itsme

  • Members
  • 9 posts

Posted 07 September 2013 - 10:01 AM

View PostYevano, on 06 September 2013 - 04:46 PM, said:

View Postitsme, on 06 September 2013 - 06:42 AM, said:

Hello!
Which directory should I copy my custom API file to, so that it can be loaded automatically (without using the os.loadAPI() function). The wiki states: "If you're playing single-player or you're running the multiplayer server, you can add those APIs to "rom/apis" and they will automatically be loaded on every computer in the world." but there is no such directory. The SP & MP ComputerCraft mod resides in a zip file. I'm using the latest Tekkit Lite.

Thanks

It's inside the lua folder which resides in your computercraft mod zip. Another option, however, is to create a startup file in your computer which loads the API. You could even do this for all computers automatically by using resource packs (Do some research on those. I've never used them.).

Thank you for your reply!

#13 bologna

  • New Members
  • 1 posts

Posted 16 September 2013 - 02:33 AM

This is a great tutorial. Coming from very very limited programming experience i have just learned what functions are and was trying to figure out how i can make functions available for different programs i design for the turtle without having to rewrite the code for each one. I found this and it was very clear, step by step, with no typing errors (us beginner programmer's worst nightmares), and had clear percise goals it achieved. Thank you for this great tutorial that will save me a lot of time and code.

#14 Yevano

  • Members
  • 376 posts
  • LocationUSA

Posted 16 September 2013 - 03:05 PM

View Postbologna, on 16 September 2013 - 02:33 AM, said:

This is a great tutorial. Coming from very very limited programming experience i have just learned what functions are and was trying to figure out how i can make functions available for different programs i design for the turtle without having to rewrite the code for each one. I found this and it was very clear, step by step, with no typing errors (us beginner programmer's worst nightmares), and had clear percise goals it achieved. Thank you for this great tutorial that will save me a lot of time and code.

I'm glad it helped you!

Edit:

View PostMohansingh, on 17 September 2013 - 02:07 AM, said:

I was searching for the same topic/ question but this page really satisfied me with the details which are very much important as well as will help others also.

Glad it helped you, too!





1 user(s) are reading this topic

0 members, 1 guests, 0 anonymous users