Module global
Lua global variables.
The basic library provides some core functions to Lua. All the preloaded module of Lua are declared here.
Global(s)
_G |
A global variable (not a function) that holds the global environment
(that is, |
_VERSION |
A global variable (not a function) that holds a string containing the current interpreter version. |
assert(v, message) |
Issues an error when the value of its argument |
collectgarbage(opt, arg) |
This function is a generic interface to the garbage collector. |
coroutine |
This library provides generic functions for coroutine manipulation. |
debug |
The Debug Library. |
dofile(filename) |
Opens the named file and executes its contents as a Lua chunk. |
error(message, level) |
Terminates the last protected function called and returns |
getfenv(f) |
Returns the current environment in use by the function. |
getmetatable(object) |
If |
io |
The I/O library provides function for file manipulation. |
ipairs(t) |
Use to iterate over a table by index. |
load(func, chunkname) |
Loads a chunk using function |
loadfile(filename) |
Similar to |
loadstring(string, chunkname) |
Similar to |
math |
This library is an interface to the standard C math library. |
module(name) |
Creates a module. |
next(table, index) |
Allows a program to traverse all fields of a table. |
os |
Operating System Facilities. |
package |
The package library provides basic facilities for loading and building modules in Lua. |
pairs(t) |
Use to iterate over a table. |
pcall(f, ...) |
Calls function |
print(...) |
Receives any number of arguments, and prints their values to |
rawequal(v1, v2) |
Checks whether |
rawget(table, index) |
Gets the real value of |
rawset(table, index, value) |
Sets the real value of |
require(modname) |
Loads the given module. |
select(index, ...) |
If |
setfenv(f, table) |
Sets the environment to be used by the given function. |
setmetatable(table, metatable) |
Sets the metatable for the given table. |
string |
This library provides generic functions for string manipulation. |
table |
This library provides generic functions for table manipulation. |
tonumber(e, base) |
Tries to convert its argument to a number. |
tostring(e) |
Receives an argument of any type and converts it to a string in a reasonable format. |
type(v) |
Returns the type of its only argument, coded as a string. |
unpack(list, i, j) |
Returns the elements from the given table. |
xpcall(f, err) |
This function is similar to |
Global(s)
- #table _G
-
A global variable (not a function) that holds the global environment (that is,
_G._G = _G
).Lua itself does not use this variable; changing its value does not affect any environment, nor vice-versa. (Use
setfenv
to change environments.)
- #string _VERSION
-
A global variable (not a function) that holds a string containing the current interpreter version.
The current contents of this variable is "
Lua 5.1
".
- assert(v, message)
-
Issues an error when the value of its argument
v
is false (i.e., nil or false); otherwise, returns all its arguments.message
is an error message; when absent, it defaults to "assertion failed!".Parameters
-
v
: if this argument is false an error is issued. -
#string message
: an error message. defaults value is "assertion failed".
Return value
All its arguments.
-
- collectgarbage(opt, arg)
-
This function is a generic interface to the garbage collector.
It performs different functions according to its first argument,
opt
:- "stop": stops the garbage collector.
- "restart": restarts the garbage collector.
- "collect": performs a full garbage-collection cycle.
- "count": returns the total memory in use by Lua (in Kbytes).
- "step": performs a garbage-collection step. The step "size" is controlled
by
arg
(larger values mean more steps) in a non-specified way. If you want to control the step size you must experimentally tune the value ofarg
. Returns true if the step finished a collection cycle. - "setpause": sets
arg
as the new value for the pause of the collector. Returns the previous value for pause. - "setstepmul": sets
arg
as the new value for the step multiplier of the collector. Returns the previous value for step.
Parameters
-
#string opt
: the command to send. -
arg
: the argument of the command. (optional)
- coroutine#coroutine coroutine
-
This library provides generic functions for coroutine manipulation.
This is a global variable which hold the preloaded coroutine module.
- debug#debug debug
-
The Debug Library.
This is a global variable which hold the preloaded debug module.
- dofile(filename)
-
Opens the named file and executes its contents as a Lua chunk.
When called without arguments,
dofile
executes the contents of the standard input (stdin
). Returns all values returned by the chunk. In case of errors,dofile
propagates the error to its caller (that is,dofile
does not run in protected mode).Parameter
-
#string filename
: the path to the file. (optional)
-
- error(message, level)
-
Terminates the last protected function called and returns
message
as the error message.Function
error
never returns.Usually,
error
adds some information about the error position at the beginning of the message. Thelevel
argument specifies how to get the error position. With level 1 (the default), the error position is where theerror
function was called. Level 2 points the error to where the function that callederror
was called; and so on. Passing a level 0 avoids the addition of error position information to the message.Parameters
-
#string message
: an error message. -
#number level
: specifies how to get the error position, default value is1
.
-
- getfenv(f)
-
Returns the current environment in use by the function.
Parameter
-
f
: can be a Lua function or a number that specifies the function at that stack level: Level 1 is the function callinggetfenv
. If the given function is not a Lua function, or iff
is0
,getfenv
returns the global environment. The default forf
is1
.
-
- getmetatable(object)
-
If
object
does not have a metatable, returns nil.Otherwise, if the object's metatable has a
"__metatable"
field, returns the associated value. Otherwise, returns the metatable of the given object.Parameter
-
object
:
Return value
#table: the metatable of object.
-
- io#io io
-
The I/O library provides function for file manipulation.
This is a global variable which hold the preloaded io module.
- ipairs(t)
-
Use to iterate over a table by index.
Returns three values: an iterator function, the table
t
, and 0, so that the construction :for i,v in ipairs(t) do *body* end
will iterate over the pairs (
1,t[1]
), (2,t[2]
), ..., up to the first integer key absent from the table.Parameter
-
#table t
: a table by index.
-
- load(func, chunkname)
-
Loads a chunk using function
func
to get its pieces.Each call to
func
must return a string that concatenates with previous results. A return of an empty string, nil, or no value signals the end of the chunk.If there are no errors, returns the compiled chunk as a function; otherwise, returns nil plus the error message. The environment of the returned function is the global environment.
chunkname
is used as the chunk name for error messages and debug information. When absent, it defaults to "=(load)
".Parameters
-
func
: function which loads the chunk. -
#string chunkname
: chunk name used for error messages and debug information, default value is "=(load)
".
-
- loadfile(filename)
-
Similar to
load
, but gets the chunk from filefilename
or from the standard input, if no file name is given.Parameter
-
#string filename
: the path to the file. (optional)
-
- loadstring(string, chunkname)
-
Similar to
load
, but gets the chunk from the given string.To load and run a given string, use the idiom
assert(loadstring(s))()
When absent,
chunkname
defaults to the given string.Parameters
-
#string string
: lua code to load. -
#string chunkname
: chunk name used for error messages and debug information, default value is the given string.
-
- math#math math
-
This library is an interface to the standard C math library.
This is a global variable which hold the preloaded math module.
- module(name)
-
Creates a module.
If there is a table in
package.loaded[name]
, this table is the module. Otherwise, if there is a global tablet
with the given name, this table is the module.Otherwise creates a new table
t
and sets it as the value of the globalname
and the value ofpackage.loaded[name]
. This function also initializest._NAME
with the given name,t._M
with the module (t
itself), andt._PACKAGE
with the package name (the full module name minus last component; see below). Finally,module
setst
as the new environment of the current function and the new value ofpackage.loaded[name]
, so thatrequire
returnst
.If
name
is a compound name (that is, one with components separated by dots),module
creates (or reuses, if they already exist) tables for each component. For instance, ifname
isa.b.c
, thenmodule
stores the module table in fieldc
of fieldb
of globala
.This function can receive optional options after the module name, where each option is a function to be applied over the module.
Parameter
-
name
: the module name.
-
- next(table, index)
-
Allows a program to traverse all fields of a table.
Its first argument is a table and its second argument is an index in this table.
next
returns the next index of the table and its associated value.When called with nil as its second argument,
next
returns an initial index and its associated value. When called with the last index, or with nil in an empty table,next
returns nil.If the second argument is absent, then it is interpreted as nil. In particular, you can use
next(t)
to check whether a table is empty. The order in which the indices are enumerated is not specified, even for numeric indices. (To traverse a table in numeric order, use a numerical for or theipairs
function.)The behavior of
next
is undefined if, during the traversal, you assign any value to a non-existent field in the table. You may however modify existing fields. In particular, you may clear existing fields.Parameters
-
#table table
: table to traverse. -
index
: initial index.
-
- package#package package
-
The package library provides basic facilities for loading and building modules in Lua.
This is a global variable which hold the preloaded package module.
- pairs(t)
-
Use to iterate over a table.
Returns three values: the
next
function, the tablet
, and nil, so that the construction :for k,v in pairs(t) do *body* end
will iterate over all key-value pairs of table
t
.See function
next
for the caveats of modifying the table during its traversal.Parameter
-
#table t
: table to traverse.
-
- pcall(f, ...)
-
Calls function
f
with the given arguments in protected mode.This means that any error inside
f
is not propagated; instead,pcall
catches the error and returns a status code. Its first result is the status code (a boolean), which is true if the call succeeds without errors. In such case,pcall
also returns all results from the call, after this first result. In case of any error,pcall
returns false plus the error message.Parameters
-
f
: function to be call in protected mode. -
...
: function arguments.
Return values
-
#boolean: true plus the result of
f
function if its call succeeds without errors. -
#boolean, #string: false plus the error message in case of any error.
-
- print(...)
-
Receives any number of arguments, and prints their values to
stdout
, using thetostring
function to convert them to strings.print
is not intended for formatted output, but only as a quick way to show a value, typically for debugging. For formatted output, usestring.format
.Parameter
-
...
: values to print tostdout
.
-
- rawequal(v1, v2)
-
Checks whether
v1
is equal tov2
, without invoking any metamethod.Returns a boolean.
Parameters
-
v1
: -
v2
:
Return value
#boolean: true if
v1
is equal tov2
. -
- rawget(table, index)
-
Gets the real value of
table[index]
, without invoking any metamethod.table
must be a table;index
may be any value.Parameters
-
#table table
: -
index
: may be any value.
Return value
The real value of
table[index]
, without invoking any metamethod. -
- rawset(table, index, value)
-
Sets the real value of
table[index]
tovalue
, without invoking any metamethod.table
must be a table,index
any value different from nil, andvalue
any Lua value. This function returnstable
.Parameters
-
#table table
: -
index
: any value different from nil. -
value
: any Lua value.
-
- require(modname)
-
Loads the given module.
The function starts by looking into the
package.loaded
table to determine whethermodname
is already loaded. If it is, thenrequire
returns the value stored atpackage.loaded[modname]
. Otherwise, it tries to find a loader for the module.To find a loader,
require
is guided by thepackage.loaders
array. By changing this array, we can change howrequire
looks for a module. The following explanation is based on the default configuration forpackage.loaders
.First
require
queriespackage.preload[modname]
. If it has a value, this value (which should be a function) is the loader. Otherwiserequire
searches for a Lua loader using the path stored inpackage.path
. If that also fails, it searches for a C loader using the path stored inpackage.cpath
. If that also fails, it tries an all-in-one loader (seepackage.loaders
).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 topackage.loaded[modname]
. If the loader returns no value and has not assigned any value topackage.loaded[modname]
, thenrequire
assigns true to this entry. In any case,require
returns the final value ofpackage.loaded[modname]
.If there is any error loading or running the module, or if it cannot find any loader for the module, then
require
signals an error.Parameter
-
#string modname
: name of module to load.
-
- select(index, ...)
-
If
index
is a number, returns all arguments after argument numberindex
.Otherwise,
index
must be the string"#"
, andselect
returns the total number of extra arguments it received.Parameters
-
index
: a number or the string"#"
-
...
:
-
- setfenv(f, table)
-
Sets the environment to be used by the given function.
f
can be a Lua function or a number that specifies the function at that stack level: Level 1 is the function callingsetfenv
.setfenv
returns the given function. As a special case, whenf
is 0setfenv
changes the environment of the running thread. In this case,setfenv
returns no values.Parameters
-
f
: a Lua function or a number that specifies the stack level. -
#table table
: used as environment forf
.
Return value
The given function.
-
- setmetatable(table, metatable)
-
Sets the metatable for the given table.
(You cannot change the metatable of other types from Lua, only from C.) If
metatable
is nil, removes the metatable of the given table. If the original metatable has a"__metatable"
field, raises an error. This function returnstable
.Parameters
-
#table table
: -
#table metatable
:
Return value
The first argument
table
. -
- string#string string
-
This library provides generic functions for string manipulation.
This is a global variable which hold the preloaded string module.
- table#table table
-
This library provides generic functions for table manipulation.
This is a global variable which hold the preloaded table module.
- tonumber(e, base)
-
Tries to convert its argument to a number.
If the argument is already a number or a string convertible to a number, then
tonumber
returns this number; otherwise, it returns nil.An optional argument specifies the base to interpret the numeral. The base may be any integer between 2 and 36, inclusive. In bases above 10, the letter '
A
' (in either upper or lower case) represents 10, 'B
' represents 11, and so forth, with 'Z
' representing 35. In base 10 (the default), the number can have a decimal part, as well as an optional exponent part. In other bases, only unsigned integers are accepted.Parameters
-
e
: a number or string to convert to a number. -
#number base
: the base to interpret the numeral, any integer between 2 and 36.(default is 10).
Return value
#number: a number if conversion succeeds else nil.
-
- tostring(e)
-
Receives an argument of any type and converts it to a string in a reasonable format.
For complete control of how numbers are converted, use
string.format
.If the metatable of
e
has a"__tostring"
field, thentostring
calls the corresponding value withe
as argument, and uses the result of the call as its result.Parameter
-
e
: an argument of any type.
Return value
#string: a string in a reasonable format.
-
- type(v)
-
Returns the type of its only argument, coded as a string.
The possible results of this function are "
nil
" (a string, not the value nil), "number
", "string
", "boolean
", "table
", "function
", "thread
", and "userdata
".Parameter
-
v
: any value.
Return value
#string: the type of
v
. -
- unpack(list, i, j)
-
Returns the elements from the given table.
This function is equivalent to
return list[i], list[i+1], ..., list[j]
except that the above code can be written only for a fixed number of elements. By default,
i
is 1 andj
is the length of the list, as defined by the length operator.Parameters
-
#table list
: a table by index -
i
: index of first value. -
j
: index of last value.
-
- xpcall(f, err)
-
This function is similar to
pcall
, except that you can set a new error handler.xpcall
calls functionf
in protected mode, usingerr
as the error handler. Any error insidef
is not propagated; instead,xpcall
catches the error, calls theerr
function with the original error object, and returns a status code. Its first result is the status code (a boolean), which is true if the call succeeds without errors. In this case,xpcall
also returns all results from the call, after this first result. In case of any error,xpcall
returns false plus the result fromerr
.Parameters
-
f
: function to be call in protected mode. -
err
: function used as error handler.
Return values
-
#boolean: true plus the result of
f
function if its call succeeds without errors. -
#boolean, #string: false plus the result of
err
function.
-