The Essence Of Loading Code

lua-users home

There are various ways to load external code in Lua. The relationship between these is outlined here.

The loadstring [1] function instantiates a Lua function from the specified string of either compiled Lua bytecode or Lua source code that loadstring compiles into Lua bytecode. There are a few related functions. The loadfile [2] function is similar but instead obtains its code from a file at the given file system path. loadstring and loadfile are both higher-level functions implemented in terms of the lower-level code of the load function. The load [3] function instantiates a Lua function from the concatenation of zero or more substrings obtained piecemeal. load can be more efficient that loadstring when the code is large and read piecemeal, such as when a file is read in chunks, because it doesn't necessarily store the entire source code string in memory but rather only bytecodes.

dofile [4] does what loadfile does plus executes the function.

The package.loadlib [5] function instantiates a Lua function that wraps the native code with the specified symbol name of the specified dynamically loaded shared library [6] (relative paths are searched in an OS-specific way [6][7][8]). This particularly permits dynamic loading of non-Lua code at runtime.

package.loaders [9] is an array of searcher functions [9] (perhaps it should have been named package.searchers [15]). Each of these may be used to attempt to instantiate a Lua function from some location identified by the package name [10] provided to the searcher function. One of these searcher functions is implemented in terms of loadfile. Two others of these are implemented in terms of package.loadlib. Another uses neither but returns Lua functions pre-cached in memory. You may add your own searchers as well (e.g. load from ZIP file or download from web).

The mapping of package name to file system path is only possible for chunks stored in the file system. This is defined via the package.path [11] and package.cpath [12] variables. This mapping is expected to be exposed in LuaFiveTwo as the function package.searchpath. In general, the package name need not have the convention form (e.g. it could be a URL or a GUID), as long as some searcher understands it.

The require [13] function returns the value cached in the package.loaded [14] table with the specified package name as key. If the value doesn't exist, it obtains the module's loader function returned by calling the searcher functions in package.loaders in succession, invokes the loader function while passing it the package name as an argument, caches the return value in package.loaded, and returns that value.

Note that module loading is a special case of loading functions. One could use package.loaders to load code that is not intended to be used in the sense of a Lua module. The require function also does not necessitate the use the module function, even for modules.

See Also

RecentChanges · preferences
edit · history
Last edited May 2, 2009 2:33 am GMT (diff)