MUSHclient documentation: contents

require

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 ... 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 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 syntax Lua table functions Lua utilities Scripting Scripting callbacks - plugins (Help topic: lua=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 ...

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

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 syntax
Lua table functions
Lua utilities
Scripting
Scripting callbacks - plugins

(Help topic: lua=require)

Documentation contents page

Search ...

Enter a search string to find matching documentation.

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.