# 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, `_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.
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.
getfenv(f) | Returns the current environment in use by the function.
getmetatable(object) | If `object` does not have a metatable, returns nil.
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 `func` to get its pieces.
loadfile(filename) | Similar to `load`, but gets the chunk from file `filename` or from the standard input, if no file name is given.
loadstring(string, chunkname) | Similar to `load`, but gets the chunk from the given string.
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) | Use to iterate over a table.
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 them to strings.
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.
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`.
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.
unpack(list, i, j) | Returns the elements from the given table.
xpcall(f, err) | This function is similar to `pcall`, except that you can set a new error handler.

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

  ### 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. 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, default value is `1`.

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 calling `getfenv`. If the given function is not a Lua function, or if `f` is `0`, `getfenv` returns the global environment. The default for `f` is `1`.

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 file `filename` 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.

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 the `ipairs` 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.

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)

  Use to iterate over a table.

  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.

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 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, use `string.format`.

  ### 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` :

  - `v2` :

  ### 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` :

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

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.loaders` array. By changing this array, we can change how `require` looks for a module. The following explanation is based on the default configuration for `package.loaders`.

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

  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 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 `"#"`

  - `...` :

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 calling `setfenv`. `setfenv` returns the given function.
  As a special case, when `f` is 0 `setfenv` 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 for `f`.

  ### 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 returns `table`.

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

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 and `j` 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 function `f` in protected mode, using `err` as the error handler. Any error inside `f` is not propagated; instead, `xpcall` catches the error, calls the `err` 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 from `err`.

  ### Parameters

  - `f` : function to be call in protected mode.

  - `err` : function used as error handler.

  ### Return values

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

  2. #boolean, #string: false plus the result of `err` function.