MUSHclient documentation: require

require

require
Lua function require Summary Loads a module Prototype `val = require (modname)` Description Loads the named module. First checks the table package.loaded to see if it has already been loaded. If so, returns the value there. Otherwise it tries to find a loader for the module. It tries these things: If the table item package.preload [modname] is a function, that is called as the module loader. Process the variable package.path, substituting modname where it has a "?" (that is, ? becomes the name) and then repeatedly attempting to open the files in the list (paths separated by semicolons) as Lua source files. The first attempt in the default configuration is in the current directory, for modname.lua, then in the executable directory (that is, where MUSHclient executable is, if you are running from MUSHclient), various combinations of subdirectories and file names. To see exactly what tests are being done, just type 'require "foo"' and the error message will show you. Process the variable package.cpath, substituting modname where it has a "?" (that is, ? becomes the name) and then repeatedly attempting to open the files in the list (paths separated by semicolons) as DLLs. This attempts to load various DLLs, again see the package.cpath variable to see which ones exactly, or try a dummy require, as described above. If a DLL is found it attempts to call the function "luaopen_" concatenated with the module name, where dots are replaced by underscores. Finally if all else fails try to load the all-in-one loader (executable-path/loadall.dll) and look for an appropriate function. Once a loader is found, require calls the loader with a single argument, modname. If the loader returns any value, require assigns the returned value to package.loaded [modname]. If the loader returns no value and has not assigned any value to package.loaded [modname], then require assigns true to this entry. In any case, require returns the final value of package.loaded [modname]. f = require ("test") --> loads module "test" Effectively this lets various modules "require" a package, and it will only be loaded once. Also see the description for "module" for ways of effectively setting up a module to work in conjunction with "require". See Also ... Topics Lua base functions Lua bc (big number) functions Lua bit manipulation functions Lua coroutine functions Lua debug functions Lua io functions Lua math functions Lua os functions Lua package functions Lua PCRE regular expression functions Lua script extensions Lua string functions Lua table functions Lua utilities Scripting Lua functions assert (Asserts that condition is not nil and not false) collectgarbage (Collects garbage) dofile (Executes a Lua file) error (Raises an error message) gcinfo (Returns amount of dynamic memory in use) getfenv (Returns the current environment table) getmetatable (Returns the metatable for the object) ipairs (Iterates over a numerically keyed table) load (Loads a chunk by calling a function repeatedly) loadfile (Loads a Lua file and parses it) loadlib (Loads a DLL (obsolete in Lua 5.1)) loadstring (Compiles a string of Lua code) module (Creates a Lua module) next (Returns next key / value pair in a table) pairs (Traverse all items in a table) pcall (Calls a function in protected mode) print (Prints its arguments) rawequal (Compares two values for equality without invoking metamethods) rawget (Gets the value of a table item without invoking metamethods) rawset (Sets the value of a table item without invoking metamethods) select (Returns items in a list) setfenv (Sets a function's environment) setmetatable (Sets the metatable for a table) tonumber (Converts a string (of the given base) to a number) tostring (Converts its argument to a string) type (Returns the type of a variable) unpack (Unpacks a table into individual items) xpcall (Calls a function with a custom error handler) (Help topic: lua=require) Documentation contents page

Lua function

require

Summary

Loads a module

Prototype

val = require (modname)

Description

Loads the named module. 



First checks the table package.loaded to see if it has already been loaded. If so, returns the value there.



Otherwise it tries to find a loader for the module. It tries these things:





If the table item package.preload [modname] is a function, that is called as the module loader.



Process the variable package.path, substituting modname where it has a "?" (that is, ? becomes the name) and then repeatedly attempting to open the files in the list (paths separated by semicolons) as Lua source files. The first attempt in the default configuration is in the current directory, for modname.lua, then in the executable directory (that is, where MUSHclient executable is, if you are running from MUSHclient), various combinations of subdirectories and file names. To see exactly what tests are being done, just type 'require "foo"' and the error message will show you.



Process the variable package.cpath, substituting modname where it has a "?" (that is, ? becomes the name) and then repeatedly attempting to open the files in the list (paths separated by semicolons) as DLLs. This attempts to load various DLLs, again see the package.cpath variable to see which ones exactly, or try a dummy require, as described above. If a DLL is found it attempts to call the function "luaopen_" concatenated with the module name, where dots are replaced by underscores.



Finally if all else fails try to load the all-in-one loader (executable-path/loadall.dll) and look for an appropriate function.





Once a loader is found, require calls the loader with a single argument, modname. If the loader returns any value, require assigns the returned value to package.loaded [modname]. If the loader returns no value and has not assigned any value to package.loaded [modname], then require assigns true to this entry. In any case, require returns the final value of package.loaded [modname].




f = require ("test")  --> loads module "test" 




Effectively this lets various modules "require" a package, and it will only be loaded once. Also see the description for "module" for ways of effectively setting up a module to work in conjunction with "require".