This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.
The fourth edition targets Lua 5.3 and is available at Amazon and other bookstores.
By buying the book, you also help to support the Lua project.

Previous Programming in Lua Next
Part I. The Language Chapter 8. Compilation, Execution, and Errors

8.1 – The require Function

Lua offers a higher-level function to load and run libraries, called require. Roughly, require does the same job as dofile, but with two important differences. First, require searches for the file in a path; second, require controls whether a file has already been run to avoid duplicating the work. Because of these features, require is the preferred function in Lua for loading libraries.

The path used by require is a little different from typical paths. Most programs use paths as a list of directories wherein to search for a given file. However, ANSI C (the abstract platform where Lua runs) does not have the concept of directories. Therefore, the path used by require is a list of patterns, each of them specifying an alternative way to transform a virtual file name (the argument to require) into a real file name. More specifically, each component in the path is a file name containing optional interrogation marks. For each component, require replaces each `?´ by the virtual file name and checks whether there is a file with that name; if not, it goes to the next component. The components in a path are separated by semicolons (a character seldom used for file names in most operating systems). For instance, if the path is 

    ?;?.lua;c:\windows\?;/usr/local/lua/?/?.lua
then the call require"lili" will try to open the following files: 
    lili
    lili.lua
    c:\windows\lili
    /usr/local/lua/lili/lili.lua
The only things that require fixes is the semicolon (as the component separator) and the interrogation mark; everything else (such as directory separators or file extensions) is defined in the path.

To determine its path, require first checks the global variable LUA_PATH. If the value of LUA_PATH is a string, that string is the path. Otherwise, require checks the environment variable LUA_PATH. Finally, if both checks fail, require uses a fixed path (typically "?;?.lua", although it is easy to change that when you compile Lua).

The other main job of require is to avoid loading the same file twice. For that purpose, it keeps a table with the names of all loaded files. If a required file is already in the table, require simply returns. The table keeps the virtual names of the loaded files, not their real names. Therefore, if you load the same file with two different virtual names, it will be loaded twice. For instance, the command require"foo" followed by require"foo.lua", with a path like "?;?.lua", will load the file foo.lua twice. You can access this control table through the global variable _LOADED. Using this table, you can check which files have been loaded; you can also fool require into running a file twice. For instance, after a successful require"foo", _LOADED["foo"] will not be nil. If you then assign nil to _LOADED["foo"], a subsequent require"foo" will run the file again.

A component does not need to have interrogation marks; it can be a fixed file name, such as the last component in the following path: 

    ?;?.lua;/usr/local/default.lua
In this case, whenever require cannot find another option, it will run this fixed file. (Of course, it only makes sense to have a fixed component as the last component in a path.) Before require runs a chunk, it defines a global variable _REQUIREDNAME containing the virtual name of the file being required. We can use these facilities to extend the functionality of require. In an extreme example, we may set the path to something like "/usr/local/lua/newrequire.lua", so that every call to require runs newrequire.lua, which can then use the value of _REQUIREDNAME to actually load the required file.
Copyright © 2003–2004 Roberto Ierusalimschy. All rights reserved. Next