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, _G._G = _G).

_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 v is false (i.e., nil or false); otherwise, returns all its arguments.

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 message as the error message.

getmetatable(object)

If object does not have a metatable, returns nil.

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 load, but gets the chunk from file filename or from the standard input, if no file name is given.

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 __pairs, calls it with t as argument and returns the first three results from the call.

pcall(f, ...)

Calls function f with the given arguments in protected mode.

print(...)

Receives any number of arguments and prints their values to stdout, using the tostring function to convert each argument to a string.

rawequal(v1, v2)

Checks whether v1 is equal to v2, without invoking any metamethod.

rawget(table, index)

Gets 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.

rawset(table, index, value)

Sets the real value of table[index] to value, without invoking any metamethod.

require(modname)

Loads the given module.

select(index, ...)

If index is a number, returns all arguments after argument number index.

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. The level argument specifies how to get the error position.
With level 1 (the default), the error position is where the error function was called.
Level 2 points the error to where the function that called error 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

  1. #table: the metatable of object.

  2. #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, 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.

Return value

iterator function, table t, the value 0

load(ld, source, mode, env)

Loads a chunk.

If ld is a string, the chunk is this string. If ld is a function, load calls it repeatedly to get the chunk pieces. Each call to ld 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 (see string.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 to ld, if ld 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 default ld if ld 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

  1. compiled chunk as a function

  2. #nil, #string: error message

loadfile(filename, mode, env)

Similar to load, but gets the chunk from file filename 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

  1. compiled chunk as a function

  2. #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.

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

  1. index, value

  2. #nil: if called on the last index or on an empty table

os#os os

Operating System Facilities.

This is a global variable which hold the preloaded os module.

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 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.

Return value

iterator function, table t, the value 0

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

  1. #boolean: true plus the result of f function if its call succeeds without errors.

  2. #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 the tostring 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 and io.write.

Parameter

  • ... : values to print to stdout.

rawequal(v1, v2)

Checks whether v1 is equal to v2, without invoking any metamethod.

Returns a boolean.

Parameters

  • v1 : first operand

  • v2 : second operand

Return value

#boolean: true if v1 is equal to v2.

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] to value, without invoking any metamethod.

table must be a table, index any value different from nil, and value any Lua value.
This function returns table.

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 at package.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 for package.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 in package.path. If that also fails, it searches for a C loader using the path stored in package.cpath. If that also fails, it tries an all-in-one loader (see package.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 number index.

Otherwise, index must be the string "#", and select returns the total number of extra arguments it received.

Parameters

  • index : a number or the string "#"

  • ... :

Return values

  1. all arguments after argument number index

  2. 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 returns table.

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 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. If the string e 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 between 2 and 36 (optional, 10 by default).

Return values

  1. #number: converted number

  2. #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, then tostring calls the corresponding value with v 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.