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.
|Programming in Lua|
|Part I. The Language Chapter 8. Compilation, Execution, and Errors|
Lua offers a higher-level function to load and run libraries,
require does the same job as
but with two important differences.
require searches for the file in a path;
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
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
into a real file name.
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/?/?.luathen the call
require"lili"will try to open the following files:
lili lili.lua c:\windows\lili /usr/local/lua/lili/lili.luaThe only things that
requirefixes 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
If the value of
LUA_PATH is a string,
that string is the path.
require checks the environment variable
Finally, if both checks fail,
require uses a fixed path
"?;?.lua", although it is easy to change that when
you compile Lua).
The other main job of
require is to avoid loading the same
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.
require"foo" followed by
with a path like
will load the file
You can access this control table through the
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
_LOADED["foo"] will not be nil.
If you then assign nil to
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.luaIn this case, whenever
requirecannot 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
requireruns a chunk, it defines a global variable
_REQUIREDNAMEcontaining 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
newrequire.lua, which can then use the value of
_REQUIREDNAMEto actually load the required file.
|Copyright © 2003–2004 Roberto Ierusalimschy. All rights reserved.|