Library loading and writing: The basics

[Wobbo 8]

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!

Loading Libraries
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!


Writing Libraries
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`. 

 

 

And Now?

Now you should be ready to install and write your own libraries and make changes to the libraries of others. If you still have questions, feel free to ask them here!

[Antheus 4]

Nice

[dequbed 3]

You two made like the best tutorial beginners could wish for. Very much appreciated!

[Antheus 4]

Thank you, Wobbo!

[Cat 3]

Nice tutorial. Though very basic code-wise there is plenty of information and a good amount of formatting. +1