global.lua

-------------------------------------------------------------------------------
-- 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. 
-- @module global

------------------------------------------------------------------------------
-- This library provides generic functions for bitwise manipulation.
-- This is a global variable which hold the preloaded @{bit32} module.
-- @field[parent = #global] bit32#bit32 bit32 preloaded module

------------------------------------------------------------------------------
-- This library provides generic functions for coroutine manipulation.
-- This is a global variable which hold the preloaded @{coroutine} module.
-- @field[parent = #global] coroutine#coroutine coroutine preloaded module

------------------------------------------------------------------------------
-- The package library provides basic facilities for loading and building modules in Lua.
-- This is a global variable which hold the preloaded @{package} module.
-- @field[parent = #global] package#package package preloaded module

------------------------------------------------------------------------------
-- This library provides generic functions for string manipulation.
-- This is a global variable which hold the preloaded @{string} module.
-- @field[parent = #global] string#string string preloaded module

------------------------------------------------------------------------------
-- This library provides generic functions for table manipulation.
-- This is a global variable which hold the preloaded @{table} module.
-- @field[parent = #global] table#table table preloaded module

------------------------------------------------------------------------------
-- This library is an interface to the standard C math library.
-- This is a global variable which hold the preloaded @{math} module.
-- @field[parent = #global] math#math math preloaded module

------------------------------------------------------------------------------
-- This library is an interface to the standard C math library.
-- This is a global variable which hold the preloaded @{math} module.
-- @field[parent = #global] Buff#Buff Buff preloaded module

------------------------------------------------------------------------------
-- This library is an interface to the standard C math library.
-- This is a global variable which hold the preloaded @{math} module.
-- @field[parent = #global] CSprite#CSprite CSprite preloaded module

------------------------------------------------------------------------------
-- The I/O library provides function for file manipulation.
-- This is a global variable which hold the preloaded @{io} module.
-- @field[parent = #global] io#io io preloaded module

------------------------------------------------------------------------------
-- Operating System Facilities.
-- This is a global variable which hold the preloaded @{os} module.
-- @field[parent = #global] os#os os preloaded module

------------------------------------------------------------------------------
-- The Debug Library.
-- This is a  global variable which hold the preloaded @{debug} module.
-- @field[parent = #global] debug#debug debug preloaded module

-------------------------------------------------------------------------------
-- 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!"*.
-- @function [parent=#global] assert
-- @param v if this argument is false an error is issued.
-- @param #string message an error message (optional, *"assertion failed"* by default)
-- @return All its arguments.

-------------------------------------------------------------------------------
-- 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.
-- @function [parent=#global] collectgarbage
-- @param #string opt the command to send (optional, "collect" by default)
-- @param arg the argument of the command (optional).

-------------------------------------------------------------------------------
-- 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).
-- @function [parent=#global] dofile
-- @param #string filename the path to the file. (optional)
-- @return values returned by the chunk

-------------------------------------------------------------------------------
-- 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.
-- @function [parent=#global] error
-- @param #string message an error message.
-- @param #number level specifies how to get the error position (optional, `1` by default).

-------------------------------------------------------------------------------
-- 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.
-- @field [parent = #global] #table _G

-------------------------------------------------------------------------------
-- 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.
-- @function [parent=#global] getmetatable
-- @param object
-- @return #table the metatable of object.
-- @return #nil if no metatable was found

-------------------------------------------------------------------------------
-- 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. 
-- @function [parent=#global] ipairs
-- @param #table t a table by index.
-- @return iterator function, table `t`, the value `0`

-------------------------------------------------------------------------------
-- 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"`. 
-- @function [parent=#global] load
-- @param ld string or function representing the chunk.
-- @param #string source used as source code (optional, by default `ld` if `ld` is a
-- string, or to `"=(load)"`otherwise.
-- @param #string mode `"b"` for only binary chunk, `"t"` for only text chunks,
-- `bt` for both binary and text (optional, "bt" by default).
-- @param env environment where to set the first upvalue if any.
-- @return compiled chunk as a function
-- @return #nil, #string error message

-------------------------------------------------------------------------------
-- Similar to `load`, but gets the chunk from file `filename` or from the
-- standard input, if no file name is given.
-- @function [parent=#global] loadfile
-- @param #string filename the path to the file. (optional)
-- @param #string mode `"b"` for only binary chunk, `"t"` for only text chunks,
-- `bt` for both binary and text (optional, "bt" by default).
-- @param env environment where to set the first upvalue if any.
-- @return compiled chunk as a function
-- @return #nil, #string error message

-------------------------------------------------------------------------------
-- 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.
-- @function [parent=#global] next
-- @param #table table table to traverse.
-- @param index initial index (optional).
-- @return index, value
-- @return #nil if called on the last index or on an empty table

-------------------------------------------------------------------------------
-- 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. 
-- @function [parent=#global] pairs
-- @param #table t table to traverse.
-- @return iterator function, table `t`, the value `0`

-------------------------------------------------------------------------------
-- 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.
-- @function [parent=#global] pcall
-- @param f function to be call in *protected mode*.
-- @param ... function arguments.
-- @return #boolean true plus the result of `f` function if its call succeeds without errors.
-- @return #boolean,#string false plus the error message in case of any error.

-------------------------------------------------------------------------------
-- 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`. 
-- @function [parent=#global] print
-- @param ... values to print to `stdout`.

-------------------------------------------------------------------------------
-- Checks whether `v1` is equal to `v2`, without invoking any
-- metamethod. Returns a boolean.
-- @function [parent=#global] rawequal
-- @param v1 first operand
-- @param v2 second operand
-- @return #boolean true if `v1` is equal to `v2`. 

-------------------------------------------------------------------------------
-- Gets the real value of `table[index]`, without invoking any
-- metamethod. `table` must be a table; `index` may be any value.
-- @function [parent=#global] rawget
-- @param #table table table to looking for
-- @param index index in the table
-- @return The real value of `table[index]`, without invoking any
-- metamethod.

-------------------------------------------------------------------------------
-- Returns the length of the object `v`, which must be a table or a string, without
-- invoking any metamethod. Returns an integer number. 
-- @function [parent=#global] rawlen
-- @param v table or a string
-- @return #number length of `v`

-------------------------------------------------------------------------------
-- 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`.
-- @function [parent=#global] rawset
-- @param #table table
-- @param index any value different from nil.
-- @param value any Lua value.
-- @return #table the given table

-------------------------------------------------------------------------------
-- 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.
-- @function [parent=#global] select
-- @param index a number or the string `"#"`
-- @param ...
-- @return all arguments after argument number `index`
-- @return total number of extra arguments

-------------------------------------------------------------------------------
-- 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`.
-- @function [parent=#global] setmetatable
-- @param #table table 
-- @param #table metatable
-- @return #table The first argument `table`.

-------------------------------------------------------------------------------
-- 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**. 
-- @function [parent=#global] tonumber
-- @param e a number or string to convert to a number.
-- @param #number base the base to interpret the numeral, any integer between `2` and `36` (optional, `10` by default).
-- @return #number converted number
-- @return #nil if convertion fail.

-------------------------------------------------------------------------------
-- 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.
-- @function [parent=#global] tostring
-- @param v an argument of any type.
-- @return #string a string in a reasonable format.

-------------------------------------------------------------------------------
-- 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`".
-- @function [parent=#global] type
-- @param v any value.
-- @return #string the type of `v`.

-------------------------------------------------------------------------------
-- 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`".
-- @field [parent = #global] #string _VERSION

-------------------------------------------------------------------------------
-- This function is similar to pcall, except that it sets a new message handler msgh. 
-- @param f function to be call in *protected mode*.
-- @param msgh error message handler
-- @param ... function arguments.
-- @return #boolean true plus the result of `f` function if its call succeeds without errors.
-- @return #boolean false if the call raise an error

-------------------------------------------------------------------------------
-- 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. 
-- @function [parent=#global] require
-- @param #string modname name of module to load.
-- @return loaded module

return nil