Module global
Lua global variables.
The basic library provides core functions to Lua. If you do not include this library in your application, you should check carefully whether you need to provide implementations for some of its facilities.
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 |
bit32 |
This library provides generic functions for bitwise manipulation. |
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 |
getmetatable(object) |
If |
io |
The I/O library provides function for file manipulation. |
ipairs(t) |
If t has a metamethod __ipairs, calls it with t as argument and returns the first three results from the call. |
load(ld, source, mode, env) |
Loads a chunk. |
loadfile(filename, mode, env) |
Similar to |
math |
This library is an interface to the standard C math library. |
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) |
If t has a metamethod |
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 |
rawlen(v) |
Returns the length of the object |
rawset(table, index, value) |
Sets the real value of |
require(modname) |
Loads the given module. |
select(index, ...) |
If |
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) |
When called with no base, tonumber tries to convert its argument to a number. |
tostring(v) |
Receives an argument of any type and converts it to a string in a reasonable format. |
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.
- #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.2
".
- 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 (optional, "assertion failed" by default)
Return value
All its arguments.
-
- bit32#bit32 bit32
-
This library provides generic functions for bitwise manipulation.
This is a global variable which hold the preloaded bit32 module.
- collectgarbage(opt, arg)
-
This function is a generic interface to the garbage collector.
It performs different functions according to its first argument,
opt
:"collect": performs a full garbage-collection cycle. This is the default option.
"stop": stops automatic execution of the garbage collector. The collector will run only when explicitly invoked, until a call to restart it.
"restart": restarts automatic execution of the garbage collector.
"count": returns the total memory in use by Lua (in Kbytes) and a second value with the total memory in bytes modulo
1024
. The first value has a fractional part, so the following equality is always true: (The second result is useful when Lua is compiled with a non floating-point type for numbers.)k, b = collectgarbage("count") assert(k*1024 == math.floor(k)*1024 + b)
"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 of arg. 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."isrunning": returns a boolean that tells whether the collector is running (i.e., not stopped).
"generational": changes the collector to generational mode. This is an experimental feature.
"incremental": changes the collector to incremental mode. This is the default mode.
Parameters
-
#string opt
: the command to send (optional, "collect" by default) -
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)
Return value
values returned by the chunk
-
- 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 (optional,1
by default).
-
- 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 values
-
#table: the metatable of object.
-
#nil: if no metatable was found
-
- 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)
-
If t has a metamethod __ipairs, calls it with t as argument and returns the first three results from the call.
Otherwise, returns three values: an iterator function, the table
t
, and0
, so that the constructionfor 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.
Return value
iterator function, table
t
, the value0
-
- load(ld, source, mode, env)
-
Loads a chunk.
If
ld
is a string, the chunk is this string. Ifld
is a function, load calls it repeatedly to get the chunk pieces. Each call told
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 syntactic errors, returns the compiled chunk as a function; otherwise, returns nil plus the error message.
If the resulting function has upvalues, the first upvalue is set to the value of
env
, if that parameter is given, or to the value of the global environment. (When you load a main chunk, the resulting function will always have exactly one upvalue, the_ENV
variable. When you load a binary chunk created from a function (seestring.dump
), the resulting function can have arbitrary upvalues.)source
is used as the source of the chunk for error messages and debug information. When absent, it defaults told
, ifld
is a string, or to"=(load)"
otherwise.The string mode controls whether the chunk can be text or binary (that is, a precompiled chunk). It may be the string
"b"
(only binary chunks),"t"
(only text chunks), or"bt"
(both binary and text). The default is"bt"
.Parameters
-
ld
: string or function representing the chunk. -
#string source
: used as source code (optional, by defaultld
ifld
is a string, or to"=(load)"
otherwise. -
#string mode
:"b"
for only binary chunk,"t"
for only text chunks,bt
for both binary and text (optional, "bt" by default). -
env
: environment where to set the first upvalue if any.
Return values
-
compiled chunk as a function
-
#nil, #string: error message
-
- loadfile(filename, mode, env)
-
Similar to
load
, but gets the chunk from filefilename
or from the standard input, if no file name is given.Parameters
-
#string filename
: the path to the file. (optional) -
#string mode
:"b"
for only binary chunk,"t"
for only text chunks,bt
for both binary and text (optional, "bt" by default). -
env
: environment where to set the first upvalue if any.
Return values
-
compiled chunk as a function
-
#nil, #string: error message
-
- 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.
- 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.)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 (optional).
Return values
-
index, value
-
#nil: if called on the last index or on an empty table
-
- 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)
-
If t has a metamethod
__pairs
, calls it with t as argument and returns the first three results from the call.Otherwise, returns three values: the
next
function, the table t, and nil, so that the constructionfor 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.
Return value
iterator function, table
t
, the value0
-
- 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 each argument to a string.print is not intended for formatted output, but only as a quick way to show a value, for instance for debugging. For complete control over the output, use
string.format
andio.write
.Parameter
-
...
: values to print tostdout
.
-
- rawequal(v1, v2)
-
Checks whether
v1
is equal tov2
, without invoking any metamethod.Returns a boolean.
Parameters
-
v1
: first operand -
v2
: second operand
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
: table to looking for -
index
: index in the table
Return value
The real value of
table[index]
, without invoking any metamethod. -
- rawlen(v)
-
Returns the length of the object
v
, which must be a table or a string, without invoking any metamethod.Returns an integer number.
Parameter
-
v
: table or a string
Return value
#number: length of
v
-
- 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.
Return value
#table: the given table
-
- require(modname)
-
Loads the given module.
The function starts by looking into the
package.loaded
table to determine whether modname is already loaded. If it is, then require 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 the
package.searchers
sequence. By changing this sequence, we can change how require looks for a module. The following explanation is based on the default configuration forpackage.searchers
.First require queries
package.preload[modname]
. If it has a value, this value (which should be a function) is the loader. Otherwise require 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.searchers
).Once a loader is found, require calls the loader with two arguments: modname and an extra value dependent on how it got the loader. (If the loader came from a file, this extra value is the file name.) If the loader returns any non-nil value, require assigns the returned value to package.loaded[modname]. If the loader does not return a non-nil 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].If there is any error loading or running the module, or if it cannot find any loader for the module, then require raises an error.
Parameter
-
#string modname
: name of module to load.
Return value
loaded module
-
- 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"#"
-
...
:
Return values
-
all arguments after argument number
index
-
total number of extra arguments
-
- 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
#table: 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)
-
When called with no base, tonumber 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.
When called with base, then e should be a string to be interpreted as an integer numeral in that base. The base may be any integer between
2
and36
, inclusive. In bases above10
, the letter 'A' (in either upper or lower case) represents10
, 'B' represents11
, and so forth, with 'Z' representing35
. If the stringe
is not a valid numeral in the given base, the function returns nil.Parameters
-
e
: a number or string to convert to a number. -
#number base
: the base to interpret the numeral, any integer between2
and36
(optional,10
by default).
Return values
-
#number: converted number
-
#nil: if convertion fail.
-
- tostring(v)
-
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
v
has a"__tostring"
field, thentostring
calls the corresponding value withv
as argument, and uses the result of the call as its result.Parameter
-
v
: an argument of any type.
Return value
#string: a string in a reasonable format.
-