So, you want to know what this require thingy does? Or maybe you installed a library you can't load? You want to write your own library? Then we are here to help you. In this tutorial, we are going to explain how the require function and the package library works. So, lets get started!
In order to load a library, you can use the function require. But what does require do? Where does it pull these libraries from?
require needs the name of the library you want to load, but not the path to that file, so it needs to search the file system somehow. This is done by looking at the string in package.path. You can open up a lua prompt and try to print it now. The default value of package.path is "/lib/?.lua;/usr/lib/?.lua;/home/lib/?.lua;./?.lua". Each string between the ; is seen as a path and the name you provide is used to replace the ?. Then require tries all the paths and sees if the file exists. If it exists, it is executed and the return value is stored and returned to the caller. The vaule is stored so require does not have to load the same library twice. This improves loading times and minimizes RAM usage!
So, lets say you installed a library in /usr/local/lib and require can't seem to find it. How do you tell require where it needs to look? This can be done by changing package.path to include the installation location of your new library. So you need to encode your new directory in the path. First you need to make the path to the new folder recognisable to require. First you need the path to the directory (/usr/local/lib/). This needs to be followed by the ?.lua to do the substitution with the name. Then we get the following path: /usr/local/lib/?.lua. So now require knows where to find your library!
So, now you know how to load a library, but not how to write one, so that is what we are going to do now. The library will not do propererror checking, that is left as an exercise to the reader.
So, what will our library do? It will be a wrapper around the movement functions of the robot api, but it will move the robot multiple times. So movebot.forward(10) will try to move the robot ten times. So open a file called movebot.lua and we can start!
First we need to require the robot api. We can do this like you would do it in any other file, with local robot = require 'robot'. Now we get to the fun part.
At the end of the file, we need to return a table which will hold all the functions. I find it easiest to create this table beforehand, but you can also create it at the end. If you do, don't forget to localise your variables! So, lets create this table!
local movebot = {}
Now we can install our functions into it! As said before, these functions wil have no error checking, this is left as an exercise to the reader.
The functions will get a number and need to call the respective function from the robot library that many times.
function movebot.forward(x)
x = x or 1
for i = 1, x do
robot.forward()
end
end
function movebot.back(x)
x = x or 1
for i = 1, x do
robot.back()
end
end
function movebot.up(x)
x = x or 1
for i = 1, x do
robot.up()
end
end
function movebot.down(x)
x = x or 1
for i = 1, x do
robot.down()
end
end
Now we only need to return the table we just created and we are done!
return movebot
The whole file should now look like this:
local robot = require 'robot'
local movebot = {}
function movebot.forward(x)
x = x or 1
for i = 1, x do
robot.forward()
end
end
function movebot.back(x)
x = x or 1
for i = 1, x do
robot.back()
end
end
function movebot.up(x)
x = x or 1
for i = 1, x do
robot.up()
end
end
function movebot.down(x)
x = x or 1
for i = 1, x do
robot.down()
end
end
return movebot
Now, save the file and you are ready to require the file! In fact, you can try it out from the lua prompt. If it errors, make sure you try to require the right file and that it is in your package.path.