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

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

  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.