diff options
Diffstat (limited to 'modules/lua/lua.luadoc')
| -rw-r--r-- | modules/lua/lua.luadoc | 2166 |
1 files changed, 987 insertions, 1179 deletions
diff --git a/modules/lua/lua.luadoc b/modules/lua/lua.luadoc index 8dc89938..52d81aeb 100644 --- a/modules/lua/lua.luadoc +++ b/modules/lua/lua.luadoc @@ -3,438 +3,391 @@ -- @class table -- @name _G -- @field _G (table) --- A global variable (not a function) that holds the global environment --- (see §2.2). Lua itself does not use this variable; changing its value does --- not affect any environment, nor vice versa. +-- A global variable (not a function) that holds the global environment (see §2.2). Lua +-- itself does not use this variable; changing its value does not affect any environment, +-- nor vice versa. -- @field _VERSION (string) --- A global variable (not a function) that holds a string containing the --- running Lua version. The current value of this variable is "`Lua 5.4`". +-- A global variable (not a function) that holds a string containing the running Lua version. The +-- current value of this variable is "`Lua 5.4`". local _G --- --- Raises an error if the value of its argument `v` is false (i.e., nil or --- false); otherwise, returns all its arguments. In case of error, `message` is --- the error object; when absent, it defaults to "assertion failed!". +-- Raises an error if the value of its argument `v` is false (i.e., nil or false); otherwise, +-- returns all its arguments. In case of error, `message` is the error object; when absent, +-- it defaults to "assertion failed!". function assert(v [, message]) end --- --- 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. +-- 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. -- "restart": restarts automatic execution of the garbage collector. --- "count": returns the total memory in use by Lua in Kbytes. The value has a --- fractional part, so that it multiplied by 1024 gives the exact --- number of bytes in use by Lua. --- "step": performs a garbage-collection step. The step "size" is controlled --- by `arg`. With a zero value, the collector will perform one basic --- (indivisible) step. For non-zero values, the collector will perform --- as if that amount of memory (in Kbytes) had been allocated by Lua. --- Returns true if the step finished a collection cycle. --- "isrunning": returns a boolean that tells whether the collector is running --- (i.e., not stopped). --- "incremental": change the collector mode to incremental. This option can be --- followed by three numbers: the garbage-collector pause, the --- step multiplier, and the step size (see §2.5.1). A zero means to not --- change that value. --- "generational": change the collector mode to generational. This option can --- be followed by two numbers: the garbage-collector minor --- multiplier and the major multiplier (see §2.5.2). A zero --- means to not change that value. +-- "count": returns the total memory in use by Lua in Kbytes. The value has a fractional part, +-- so that it multiplied by 1024 gives the exact number of bytes in use by Lua. +-- "step": performs a garbage-collection step. The step "size" is controlled by `arg`. With a +-- zero value, the collector will perform one basic (indivisible) step. For non-zero values, +-- the collector will perform as if that amount of memory (in Kbytes) had been allocated +-- by Lua. Returns true if the step finished a collection cycle. +-- "isrunning": returns a boolean that tells whether the collector is running (i.e., not +-- stopped). +-- "incremental": change the collector mode to incremental. This option can be followed +-- by three numbers: the garbage-collector pause, the step multiplier, and the step size +-- (see §2.5.1). A zero means to not change that value. +-- "generational": change the collector mode to generational. This option can be followed +-- by two numbers: the garbage-collector minor multiplier and the major multiplier (see +-- §2.5.2). A zero means to not change that value. -- -- See §2.5 for more details about garbage collection and some of these options. function collectgarbage([opt [, arg]]) end --- --- Opens the named file and executes its content as a Lua chunk. When --- called without arguments, --- `dofile` executes the content 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.) +-- Opens the named file and executes its content as a Lua chunk. When called without arguments, +-- `dofile` executes the content 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 dofile([filename]) end --- --- Raises an error (see §2.3) with `message` as the error object. This function --- never returns. +-- Raises an error (see §2.3) with `message` as the error object. This function never returns. -- --- Usually, `error` adds some information about the error position at the --- beginning of the message, if the message is a string. 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. +-- Usually, `error` adds some information about the error position at the beginning of the +-- message, if the message is a string. 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 error(message [, level]) end --- --- Returns the current environment in use by the function. `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. +-- Returns the current environment in use by the function. `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. -- -- Deprecated in Lua 5.2. function getfenv([f]) end --- --- 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. +-- 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 getmetatable(object) end --- --- Returns three values (an iterator function, the table `t`, and 0) so that the --- construction +-- 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 key-value pairs (`1,t[1]`), (`2,t[2]`), ···, up to the --- first absent index. +-- will iterate over the key-value pairs (`1,t[1]`), (`2,t[2]`), ···, up to the first +-- absent index. function ipairs(t) end --- -- Loads a chunk. -- --- If `chunk` is a string, the chunk is this string. If `chunk` is a function, --- `load` calls it repeatedly to get the chunk pieces. Each call to `chunk` 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, `load` returns the compiled chunk as a --- function; otherwise, it returns nil plus the error message. --- --- When you load a main chunk, the resulting function will always have exactly --- one upvalue, the `_ENV` variable (see §2.2). However, when you load a binary --- chunk created from a function (see `string.dump`), the resulting function can --- have an arbitrary number of upvalues, and there is no guarantee that its --- first upvalue will be the `_ENV` variable. (A non-main function may not even --- have an `_ENV` upvalue.) --- --- Regardless, if the resulting function has any upvalues, its first upvalue is --- set to the value of `env`, if that parameter is given, or to the value of the --- global environment. Other upvalues are initialized with nil. All upvalues are --- fresh, that is, they are not shared with any other function. --- --- `chunkname` is used as the name of the chunk for error messages and debug --- information (see §4.7). When absent, it defaults to `chunk`, if `chunk` 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`". --- --- It is safe to load malformed binary chunks; `load` signals an appropriate --- error. However, Lua does not check the consistency of the code inside binary --- chunks; running maliciously crafted bytecode can crash the interpreter. +-- If `chunk` is a string, the chunk is this string. If `chunk` is a function, `load` calls +-- it repeatedly to get the chunk pieces. Each call to `chunk` 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, `load` returns the compiled chunk as a function; otherwise, +-- it returns nil plus the error message. +-- +-- When you load a main chunk, the resulting function will always have exactly one upvalue, the +-- `_ENV` variable (see §2.2). However, when you load a binary chunk created from a function +-- (see `string.dump`), the resulting function can have an arbitrary number of upvalues, +-- and there is no guarantee that its first upvalue will be the `_ENV` variable. (A non-main +-- function may not even have an `_ENV` upvalue.) +-- +-- Regardless, if the resulting function has any upvalues, its first upvalue is set to the +-- value of `env`, if that parameter is given, or to the value of the global environment. Other +-- upvalues are initialized with nil. All upvalues are fresh, that is, they are not shared with +-- any other function. +-- +-- `chunkname` is used as the name of the chunk for error messages and debug information (see +-- §4.7). When absent, it defaults to `chunk`, if `chunk` 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`". +-- +-- It is safe to load malformed binary chunks; `load` signals an appropriate error. However, +-- Lua does not check the consistency of the code inside binary chunks; running maliciously +-- crafted bytecode can crash the interpreter. function load(chunk [, chunkname [, mode [, env]]]) end --- --- Similar to `load`, but gets the chunk from file `filename` or from the --- standard input, if no file name is given. +-- Similar to `load`, but gets the chunk from file `filename` or from the standard input, +-- if no file name is given. function loadfile([filename [, mode [, env]]]) end --- --- 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. +-- 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. -- -- Deprecated in Lua 5.2. function loadstring(string [, chunkname]) --- --- Creates a module. If there is a table in `package.loaded[name]`, this table --- is the module. Otherwise, if there is a global table `t` with the given name, --- this table is the module. Otherwise creates a new table `t` and sets it as --- the value of the global `name` and the value of `package.loaded[name]`. This --- function also initializes `t._NAME` with the given name, `t._M` with the --- module (`t` itself), and `t._PACKAGE` with the package name (the full module --- name minus last component; see below). Finally, `module` sets `t` as the new --- environment of the current function and the new value of --- `package.loaded[name]`, so that `require` returns `t`. If `name` is a --- compound name (that is, one with components separated by dots), `module` --- creates (or reuses, if they already exist) tables for each component. For --- instance, if `name` is `a.b.c`, then `module` stores the module table in --- field `c` of field `b` of global `a`. This function can receive optional --- *options* after the module name, where each option is a function to be --- applied over the module. +-- Creates a module. If there is a table in `package.loaded[name]`, this table is the +-- module. Otherwise, if there is a global table `t` with the given name, this table is the +-- module. Otherwise creates a new table `t` and sets it as the value of the global `name` +-- and the value of `package.loaded[name]`. This function also initializes `t._NAME` with the +-- given name, `t._M` with the module (`t` itself), and `t._PACKAGE` with the package name +-- (the full module name minus last component; see below). Finally, `module` sets `t` as the +-- new environment of the current function and the new value of `package.loaded[name]`, so that +-- `require` returns `t`. If `name` is a compound name (that is, one with components separated +-- by dots), `module` creates (or reuses, if they already exist) tables for each component. For +-- instance, if `name` is `a.b.c`, then `module` stores the module table in field `c` of field +-- `b` of global `a`. This function can receive optional *options* after the module name, +-- where each option is a function to be applied over the module. -- -- Deprecated in Lua 5.2. function module(name [, ···]) end --- --- 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. A call to `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. +-- 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. A call to `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 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 set existing fields to nil. +-- 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 set existing fields to nil. function next(table [, index]) end --- --- If `t` has a metamethod `__pairs`, calls it with `t` as argument and returns --- the first three results from the call. +-- 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 +-- 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. +-- See function `next` for the caveats of modifying the table during its traversal. function pairs(t) end --- --- Calls the 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 object. Note that +-- Calls the 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 object. Note that -- errors caught by `pcall` do not call a message handler. function pcall(f [, arg1, ···]) end --- --- Receives any number of arguments and prints their values to `stdout`, --- converting each argument to a string following the same rules of `tostring`. +-- Receives any number of arguments and prints their values to `stdout`, converting each argument +-- to a string following the same rules of `tostring`. -- --- The function `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`. +-- The function `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 print(···) end --- --- Checks whether `v1` is equal to `v2`, without invoking the `__eq` --- metamethod. Returns a boolean. +-- Checks whether `v1` is equal to `v2`, without invoking the `__eq` metamethod. Returns a boolean. function rawequal(v1, v2) end --- --- Gets the real value of `table[index]`, without using the `__index` --- metavalue. `table` must be a table; `index` may be any value. +-- Gets the real value of `table[index]`, without using the `__index` metavalue. `table` must +-- be a table; `index` may be any value. function rawget(table, index) end --- --- Returns the length of the object `v`, --- which must be a table or a string, --- without invoking the `__len` metamethod. --- Returns an integer. +-- Returns the length of the object `v`, which must be a table or a string, without invoking the +-- `__len` metamethod. Returns an integer. -- -- New in Lua 5.2. function rawlen(v) end --- --- Sets the real value of `table[index]` to `value`, without using the --- `__newindex` metavalue. `table` must be a table, `index` any value different --- from nil and NaN, and `value` any Lua value. +-- Sets the real value of `table[index]` to `value`, without using the `__newindex` +-- metavalue. `table` must be a table, `index` any value different from nil and NaN, and `value` +-- any Lua value. -- -- This function returns `table`. function rawset(table, index, value) end --- --- 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. +-- 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. -- -- Deprecated in Lua 5.2. function setfenv(f, table) end --- --- If `index` is a number, returns all arguments after argument number --- `index`; a negative number indexes from the end (-1 is the last argument). --- Otherwise, `index` must be the string `"#"`, and `select` returns the total --- number of extra arguments it received. +-- If `index` is a number, returns all arguments after argument number `index`; a negative number +-- indexes from the end (-1 is the last argument). Otherwise, `index` must be the string `"#"`, +-- and `select` returns the total number of extra arguments it received. function select(index, ···) end --- --- Sets the metatable for the given table. If `metatable` is nil, removes the --- metatable of the given table. If the original metatable has a `__metatable` --- field, raises an error. +-- Sets the metatable for the given table. 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`. -- --- To change the metatable of other types from Lua code, you must use the debug --- library (see §6.10). +-- To change the metatable of other types from Lua code, you must use the debug library +-- (see §6.10). function setmetatable(table, metatable) end --- --- 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 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. -- --- The conversion of strings can result in integers or floats, according to the --- lexical conventions of Lua (see §3.1). The string may have leading and --- trailing spaces and a sign. +-- The conversion of strings can result in integers or floats, according to the lexical +-- conventions of Lua (see §3.1). The string may have leading and trailing spaces and a sign. -- --- When called with `base`, then `e` must 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, +-- When called with `base`, then `e` must 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 tonumber(e [, base]) end --- --- Receives a value of any type and converts it to a string in a human-readable --- format. Floats always produce strings with some floating-point indication --- (either a decimal dot or an exponent). +-- Receives a value of any type and converts it to a string in a human-readable format. Floats +-- always produce strings with some floating-point indication (either a decimal dot or an +-- exponent). -- --- 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. Otherwise, if the metatable of `v` has a `__name` field with a --- string value, `tostring` may use that string in its final result. +-- 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. Otherwise, if the +-- metatable of `v` has a `__name` field with a string value, `tostring` may use that string +-- in its final result. -- -- For complete control of how numbers are converted, use `string.format`. function tostring(v) end --- --- 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`", +-- 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 type(v) end --- --- 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 --- (see §2.5.5). +-- 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 (see §2.5.5). -- -- Deprecated in Lua 5.2. function unpack(list [, i [, j]]) end --- --- Emits a warning with a message composed by the concatenation of all its --- arguments (which should be strings). +-- Emits a warning with a message composed by the concatenation of all its arguments (which +-- should be strings). -- --- By convention, a one-piece message starting with '`@`' is intended to be a --- *control message*, which is a message to the warning system itself. In --- particular, the standard warning function in Lua recognizes the control --- messages "`@off`", to stop the emission of warnings, and "`@on`", to --- (re)start the emission; it ignores unknown control messages. +-- By convention, a one-piece message starting with '`@`' is intended to be a *control message*, +-- which is a message to the warning system itself. In particular, the standard warning function in +-- Lua recognizes the control messages "`@off`", to stop the emission of warnings, and "`@on`", +-- to (re)start the emission; it ignores unknown control messages. -- -- New in Lua 5.4. function warn(msg1, ···) end --- --- This function is similar to `pcall`, except that it sets a new message --- handler `msgh`. +-- This function is similar to `pcall`, except that it sets a new message handler `msgh`. function xpcall(f, msgh [, arg1, ···]) end --- --- Closes coroutine `co`, that is, closes all its pending to-be-closed variables --- and puts the coroutine in a dead state. The given coroutine must be dead or --- suspended. In case of error closing some variable, returns false plus the --- error object; otherwise returns true. +-- Closes coroutine `co`, that is, closes all its pending to-be-closed variables and puts the +-- coroutine in a dead state. The given coroutine must be dead or suspended. In case of error +-- closing some variable, returns false plus the error object; otherwise returns true. function coroutine.close(co) end --- --- Creates a new coroutine, with body `f`. `f` must be a Lua --- function. Returns this new coroutine, an object with type `"thread"`. +-- Creates a new coroutine, with body `f`. `f` must be a Lua function. Returns this new coroutine, +-- an object with type `"thread"`. function coroutine.create(f) end --- --- Returns true when the coroutine `co` can yield. The default for `co` is the --- running coroutine. +-- Returns true when the coroutine `co` can yield. The default for `co` is the running coroutine. -- --- A coroutine is yieldable if it is not the main thread and it is not inside a --- non-yieldable C function. +-- A coroutine is yieldable if it is not the main thread and it is not inside a non-yieldable +-- C function. -- -- New in Lua 5.3. function coroutine.isyieldable([co]) end --- --- Starts or continues the execution of coroutine `co`. The first time --- you resume a coroutine, it starts running its body. The values `val1`, --- ··· are passed as the arguments to the body function. If the coroutine --- has yielded, `resume` restarts it; the values `val1`, ··· are passed --- as the results from the yield. +-- Starts or continues the execution of coroutine `co`. The first time you resume a coroutine, +-- it starts running its body. The values `val1`, ··· are passed as the arguments to the body +-- function. If the coroutine has yielded, `resume` restarts it; the values `val1`, ··· are +-- passed as the results from the yield. -- --- If the coroutine runs without any errors, `resume` returns true plus any --- values passed to `yield` (when the coroutine yields) or any values returned --- by the body function (when the coroutine terminates). If there is any error, --- `resume` returns false plus the error message. +-- If the coroutine runs without any errors, `resume` returns true plus any values passed to +-- `yield` (when the coroutine yields) or any values returned by the body function (when the +-- coroutine terminates). If there is any error, `resume` returns false plus the error message. function coroutine.resume(co [, val1, ···]) end --- --- Returns the running coroutine plus a boolean, true when the running coroutine --- is the main one. +-- Returns the running coroutine plus a boolean, true when the running coroutine is the main one. function coroutine.running() end --- --- Returns the status of the coroutine `co`, as a string: `"running"`, if --- the coroutine is running (that is, it is the one that called `status`); --- `"suspended"`, if the coroutine is suspended in a call to `yield`, or if it --- has not started running yet; `"normal"` if the coroutine is active but not --- running (that is, it has resumed another coroutine); and `"dead"` if the --- coroutine has finished its body function, or if it has stopped with an error. +-- Returns the status of the coroutine `co`, as a string: `"running"`, if the coroutine is +-- running (that is, it is the one that called `status`); `"suspended"`, if the coroutine +-- is suspended in a call to `yield`, or if it has not started running yet; `"normal"` if the +-- coroutine is active but not running (that is, it has resumed another coroutine); and `"dead"` +-- if the coroutine has finished its body function, or if it has stopped with an error. function coroutine.status(co) end --- --- Creates a new coroutine, with body `f`; `f` must be a Lua --- function. Returns a function that resumes the coroutine each time it is --- called. Any arguments passed to this function behave as the extra arguments --- to `resume`. The function returns the same values returned by `resume`, --- except the first boolean. In case of error, the function closes the coroutine --- and propagates the error. +-- Creates a new coroutine, with body `f`; `f` must be a Lua function. Returns a function that +-- resumes the coroutine each time it is called. Any arguments passed to this function behave as +-- the extra arguments to `resume`. The function returns the same values returned by `resume`, +-- except the first boolean. In case of error, the function closes the coroutine and propagates +-- the error. function coroutine.wrap(f) end --- --- Suspends the execution of the calling coroutine. Any arguments to `yield` are --- passed as extra results to `resume`. +-- Suspends the execution of the calling coroutine. Any arguments to `yield` are passed as +-- extra results to `resume`. function coroutine.yield(···) end --- --- 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]`. --- (The absence of a second result in this case signals that this call did not --- have to load the module.) Otherwise, it tries to find a *loader* for the --- module. --- --- To find a loader, `require` is guided by the table `package.searchers`. Each --- item in this table is a search function, that searches for the module in a --- particular way. By changing this table, 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 must 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, a *loader data*, also returned by the searcher. --- The loader data can be any value useful to the module; for the default --- searchers, it indicates where the loader was found. (For instance, if the --- loader came from a file, this extra value is the file path.) 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]`. Besides that value, `require` also returns as a --- second result the loader data returned by the searcher, which indicates how --- `require` found the module. --- --- 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. +-- 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]`. (The absence of a second result in this case signals +-- that this call did not have to load the module.) Otherwise, it tries to find a *loader* +-- for the module. +-- +-- To find a loader, `require` is guided by the table `package.searchers`. Each item in this +-- table is a search function, that searches for the module in a particular way. By changing +-- this table, 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 must 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, a *loader data*, also returned by the searcher. The loader data can be any +-- value useful to the module; for the default searchers, it indicates where the loader +-- was found. (For instance, if the loader came from a file, this extra value is the file +-- path.) 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]`. Besides that value, +-- `require` also returns as a second result the loader data returned by the searcher, which +-- indicates how `require` found the module. +-- +-- 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 require(modname) end --- @@ -442,89 +395,93 @@ function require(modname) end -- @class table -- @name package -- @field config (string) --- A string describing some compile-time configurations for packages. This --- string is a sequence of lines: --- The first line is the directory separator string. Default is '`\`' for --- Windows and '`/`' for all other systems. --- The second line is the character that separates templates in a path. --- Default is '`;`'. --- The third line is the string that marks the substitution points in a --- template. Default is '`?`'. --- The fourth line is a string that, in a path in Windows, is replaced by --- the executable's directory. Default is '`!`'. --- The fifth line is a mark to ignore all text after it when building the --- `luaopen_` function name. Default is '`-`'. +-- A string describing some compile-time configurations for packages. This string is a sequence +-- of lines: +-- +-- * The first line is the directory separator string. Default is '`\`' for Windows and +-- '`/`' for all other systems. +-- * The second line is the character that separates templates in a path. Default is '`;`'. +-- * The third line is the string that marks the substitution points in a template. Default +-- is '`?`'. +-- * The fourth line is a string that, in a path in Windows, is replaced by the executable's +-- directory. Default is '`!`'. +-- * The fifth line is a mark to ignore all text after it when building the `luaopen_` +-- function name. Default is '`-`'. -- -- New in Lua 5.2. -- @field cpath (string) -- A string with the path used by `require` to search for a C loader. --- Lua initializes the C path `package.cpath` in the same way it initializes --- the Lua path `package.path`, using the environment variable `LUA_CPATH_5_4` --- or the environment variable `LUA_CPATH` or a default path defined in --- `luaconf.h`. +-- +-- Lua initializes the C path `package.cpath` in the same way it initializes the Lua path +-- `package.path`, using the environment variable `LUA_CPATH_5_4` or the environment variable +-- `LUA_CPATH` or a default path defined in `luaconf.h`. -- @field loaded (table) --- A table used by `require` to control which modules are already loaded. When --- you require a module `modname` and `package.loaded[modname]` is not false, --- `require` simply returns the value stored there. --- This variable is only a reference to the real table; assignments to this --- variable do not change the table used by `require`. +-- A table used by `require` to control which modules are already loaded. When you require +-- a module `modname` and `package.loaded[modname]` is not false, `require` simply returns +-- the value stored there. +-- +-- This variable is only a reference to the real table; assignments to this variable do not +-- change the table used by `require`. -- @field loaders (table) -- See `package.searchers`. -- -- Deprecated in Lua 5.2. -- @field path (string) -- A string with the path used by `require` to search for a Lua loader. --- At start-up, Lua initializes this variable with the value of the --- environment variable `LUA_PATH_5_4` or the environment variable `LUA_PATH` --- or with a default path defined in `luaconf.h`, if those environment --- variables are not defined. A "`;;`" in the value of the environment --- variable is replaced by the default path. +-- +-- At start-up, Lua initializes this variable with the value of the environment variable +-- `LUA_PATH_5_4` or the environment variable `LUA_PATH` or with a default path defined in +-- `luaconf.h`, if those environment variables are not defined. A "`;;`" in the value of the +-- environment variable is replaced by the default path. -- @field preload (table) -- A table to store loaders for specific modules (see `require`). --- This variable is only a reference to the real table; assignments to this --- variable do not change the table used by `require`. +-- +-- This variable is only a reference to the real table; assignments to this variable do not +-- change the table used by `require`. -- @field searchers (table) -- A table used by `require` to control how to find modules. --- Each entry in this table is a *searcher function*. When looking for a --- module, `require` calls each of these searchers in ascending order, with --- the module name (the argument given to `require`) as its sole argument. --- If the searcher finds the module, it returns another function, the module --- *loader*, plus an extra value, a *loader data*, that will be passed to that --- loader and returned as a second result by `require`. If it cannot find the --- module, it returns a string explaining why (or nil if it has nothing to --- say). +-- +-- Each entry in this table is a *searcher function*. When looking for a module, `require` +-- calls each of these searchers in ascending order, with the module name (the argument given +-- to `require`) as its sole argument. If the searcher finds the module, it returns another +-- function, the module *loader*, plus an extra value, a *loader data*, that will be passed +-- to that loader and returned as a second result by `require`. If it cannot find the module, +-- it returns a string explaining why (or nil if it has nothing to say). +-- -- Lua initializes this table with four functions. --- The first searcher simply looks for a loader in the `package.preload` --- table. --- The second searcher looks for a loader as a Lua library, using the path --- stored at `package.path`. The search is done as described in function --- `package.searchpath`. --- The third searcher looks for a loader as a C library, using the path given --- by the variable `package.cpath`. Again, the search is done as described in --- function `package.searchpath`. For instance, if the C path is the string +-- +-- The first searcher simply looks for a loader in the `package.preload` table. +-- +-- The second searcher looks for a loader as a Lua library, using the path stored at +-- `package.path`. The search is done as described in function `package.searchpath`. +-- +-- The third searcher looks for a loader as a C library, using the path given by the variable +-- `package.cpath`. Again, the search is done as described in function `package.searchpath`. For +-- instance, if the C path is the string +-- -- "./?.so;./?.dll;/usr/local/?/init.so" --- the searcher for module `foo` will try to open the files `./foo.so`, --- `./foo.dll`, and `/usr/local/foo/init.so`, in that order. Once it finds --- a C library, this searcher first uses a dynamic link facility to link the --- application with the library. Then it tries to find a C function inside the --- library to be used as the loader. The name of this C function is the string --- "`luaopen_`" concatenated with a copy of the module name where each dot --- is replaced by an underscore. Moreover, if the module name has a hyphen, --- its suffix after (and including) the first hyphen is removed. For instance, --- if the module name is `a.b.c-v2.1 `, the function name will be --- `luaopen_a_b_c`. The fourth searcher tries an *all-in-one loader*. It --- searches the C path for a library for the root name of the given module. --- For instance, when requiring `a.b.c`, it will search for a C library for --- `a`. If found, it looks into it for an open function for the submodule; in --- our example, that would be `luaopen_a_b_c`. With this facility, a package --- can pack several C submodules into one single library, with each submodule --- keeping its original open function. --- All searchers except the first one (preload) return as the extra value the --- file path where the module was found, as returned by `package.searchpath`. --- The first searcher always returns the string "`:preload:`". --- Searchers should raise no errors and have no side effects in Lua. (They may --- have side effects in C, for instance by linking the application with a --- library.) +-- +-- the searcher for module `foo` will try to open the files `./foo.so`, `./foo.dll`, and +-- `/usr/local/foo/init.so`, in that order. Once it finds a C library, this searcher first +-- uses a dynamic link facility to link the application with the library. Then it tries to +-- find a C function inside the library to be used as the loader. The name of this C function +-- is the string "`luaopen_`" concatenated with a copy of the module name where each dot +-- is replaced by an underscore. Moreover, if the module name has a hyphen, its suffix after +-- (and including) the first hyphen is removed. For instance, if the module name is `a.b.c-v2.1 +-- `, the function name will be `luaopen_a_b_c`. +-- +-- The fourth searcher tries an *all-in-one loader*. It searches the C path for a library for +-- the root name of the given module. For instance, when requiring `a.b.c`, it will search for +-- a C library for `a`. If found, it looks into it for an open function for the submodule; in +-- our example, that would be `luaopen_a_b_c`. With this facility, a package can pack several +-- C submodules into one single library, with each submodule keeping its original open function. +-- +-- All searchers except the first one (preload) return as the extra value the file path +-- where the module was found, as returned by `package.searchpath`. The first searcher always +-- returns the string "`:preload:`". +-- +-- Searchers should raise no errors and have no side effects in Lua. (They may have side +-- effects in C, for instance by linking the application with a library.) -- -- New in Lua 5.2. local package @@ -532,257 +489,226 @@ local package --- -- Dynamically links the host program with the C library `libname`. -- --- If `funcname` is "`*`", then it only links with the library, making the --- symbols exported by the library available to other dynamically linked --- libraries. Otherwise, it looks for a function `funcname` inside the library --- and returns this function as a C function. So, `funcname` must follow the --- `lua_CFunction` prototype (see `lua_CFunction`). --- --- This is a low-level function. It completely bypasses the package and module --- system. Unlike `require`, it does not perform any path searching and does --- not automatically adds extensions. `libname` must be the complete file name --- of the C library, including if necessary a path and an extension. `funcname` --- must be the exact name exported by the C library (which may depend on the --- C compiler and linker used). --- --- This function is not supported by Standard C. As such, it is only available --- on some platforms (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix --- systems that support the `dlfcn` standard). --- --- This function is inherently insecure, as it allows Lua to call any function --- in any readable dynamic library in the system. (Lua calls any function --- assuming the function has a proper prototype and respects a proper protocol --- (see lua_CFunction). Therefore, calling an arbitrary function in an arbitrary --- dynamic library more often than not results in an access violation.) +-- If `funcname` is "`*`", then it only links with the library, making the symbols exported +-- by the library available to other dynamically linked libraries. Otherwise, it looks for +-- a function `funcname` inside the library and returns this function as a C function. So, +-- `funcname` must follow the `lua_CFunction` prototype (see `lua_CFunction`). +-- +-- This is a low-level function. It completely bypasses the package and module system. Unlike +-- `require`, it does not perform any path searching and does not automatically adds +-- extensions. `libname` must be the complete file name of the C library, including if necessary +-- a path and an extension. `funcname` must be the exact name exported by the C library (which +-- may depend on the C compiler and linker used). +-- +-- This function is not supported by Standard C. As such, it is only available on some platforms +-- (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix systems that support the `dlfcn` +-- standard). +-- +-- This function is inherently insecure, as it allows Lua to call any function in any readable +-- dynamic library in the system. (Lua calls any function assuming the function has a proper +-- prototype and respects a proper protocol (see lua_CFunction). Therefore, calling an arbitrary +-- function in an arbitrary dynamic library more often than not results in an access violation.) function package.loadlib(libname, funcname) end --- -- Searches for the given `name` in the given `path`. -- --- A path is a string containing a sequence of _templates_ separated by --- semicolons. For each template, the function replaces each interrogation mark --- (if any) in the template with a copy of `name` wherein all occurrences of --- `sep` (a dot, by default) were replaced by `rep` (the system's directory --- separator, by default), and then tries to open the resulting file name. +-- A path is a string containing a sequence of _templates_ separated by semicolons. For each +-- template, the function replaces each interrogation mark (if any) in the template with a copy +-- of `name` wherein all occurrences of `sep` (a dot, by default) were replaced by `rep` (the +-- system's directory separator, by default), and then tries to open the resulting file name. -- For instance, if the path is the string +-- -- "./?.lua;./?.lc;/usr/local/?/init.lua" --- the search for the name `foo.a` will try to open the files `./foo/a.lua`, --- `./foo/a.lc`, and `/usr/local/foo/a/init.lua`, in that order. --- Returns the resulting name of the first file that it can open in read mode --- (after closing the file), or nil plus an error message if none succeeds. --- (This error message lists all file names it tried to open.) +-- +-- the search for the name `foo.a` will try to open the files `./foo/a.lua`, `./foo/a.lc`, and +-- `/usr/local/foo/a/init.lua`, in that order. +-- +-- Returns the resulting name of the first file that it can open in read mode (after closing +-- the file), or nil plus an error message if none succeeds. (This error message lists all file +-- names it tried to open.) -- -- New in Lua 5.2. function package.searchpath(name, path [, sep [, rep]]) end --- --- Sets a metatable for `module` with its `__index` field referring to the --- global environment, so that this module inherits values from the global --- environment. To be used as an option to function `module`. +-- Sets a metatable for `module` with its `__index` field referring to the global environment, +-- so that this module inherits values from the global environment. To be used as an option to +-- function `module`. -- -- Deprecated in Lua 5.2. function package.seeall(module) end --- --- Returns the internal numerical codes of the characters `s[i]`, `s[i+1]`, --- ···, `s[j]`. The default value for `i` is 1; the default value for `j` --- is `i`. These indices are corrected following the same rules of function --- `string.sub`. +-- Returns the internal numerical codes of the characters `s[i]`, `s[i+1]`, ···, `s[j]`. The +-- default value for `i` is 1; the default value for `j` is `i`. These indices are corrected +-- following the same rules of function `string.sub`. -- -- Numerical codes are not necessarily portable across platforms. function string.byte(s [, i [, j]]) end --- --- Receives zero or more integers. Returns a string with length equal to --- the number of arguments, in which each character has the internal numerical --- code equal to its corresponding argument. +-- Receives zero or more integers. Returns a string with length equal to the number of arguments, +-- in which each character has the internal numerical code equal to its corresponding argument. -- -- Numerical codes are not necessarily portable across platforms. function string.char(···) end --- --- Returns a string containing a binary representation (a _binary chunk_) of the --- given function, so that a later `load` on this string returns a copy of the --- function (but with new upvalues). If `strip` is a true value, the binary --- representation is created without debug information about the function (local --- variable names, lines, etc.). +-- Returns a string containing a binary representation (a _binary chunk_) of the given function, so +-- that a later `load` on this string returns a copy of the function (but with new upvalues). If +-- `strip` is a true value, the binary representation is created without debug information +-- about the function (local variable names, lines, etc.). -- --- Functions with upvalues have only their number of upvalues saved. When --- (re)loaded, those upvalues receive fresh instances. (See the `load` function --- for details about how these upvalues are initialized. You can use the debug --- library to serialize and reload the upvalues of a function in a way adequate --- to your needs.) +-- Functions with upvalues have only their number of upvalues saved. When (re)loaded, those +-- upvalues receive fresh instances. (See the `load` function for details about how these +-- upvalues are initialized. You can use the debug library to serialize and reload the upvalues +-- of a function in a way adequate to your needs.) function string.dump(function [, strip]) end --- --- Looks for the first match of `pattern` (see §6.4.1) in the string `s`. If it --- finds a match, then `find` returns the indices of `s` where this occurrence --- starts and ends; otherwise, it returns nil. A third, optional numerical --- argument `init` specifies where to start the search; its default value is 1 --- and can be negative. A value of true as a fourth, optional argument `plain` --- turns off the pattern matching facilities, so the function does a plain --- "find substring" operation, with no characters in `pattern` being considered --- magic. +-- Looks for the first match of `pattern` (see §6.4.1) in the string `s`. If it finds a match, +-- then `find` returns the indices of `s` where this occurrence starts and ends; otherwise, +-- it returns nil. A third, optional numerical argument `init` specifies where to start the +-- search; its default value is 1 and can be negative. A value of true as a fourth, optional +-- argument `plain` turns off the pattern matching facilities, so the function does a plain +-- "find substring" operation, with no characters in `pattern` being considered magic. -- --- If the pattern has captures, then in a successful match the captured values --- are also returned, after the two indices. +-- If the pattern has captures, then in a successful match the captured values are also returned, +-- after the two indices. function string.find(s, pattern [, init [, plain]]) end --- --- Returns a formatted version of its variable number of arguments following the --- description given in its first argument, which must be a string. The format --- string follows the same rules as the ISO C function `sprintf`. The only --- differences are that the conversion specifiers and modifiers `*`, `h`, `L`, --- `l`, and `n` are not supported and that there is an extra specifier, `q`. +-- Returns a formatted version of its variable number of arguments following the description +-- given in its first argument, which must be a string. The format string follows the same rules +-- as the ISO C function `sprintf`. The only differences are that the conversion specifiers and +-- modifiers `*`, `h`, `L`, `l`, and `n` are not supported and that there is an extra specifier, +-- `q`. -- --- The specifier `q` formats booleans, nil, numbers, and strings in a way that --- the result is a valid constant in Lua source code. Booleans and nil are --- written in the obvious way (`true`, `false`, `nil`). Floats are written in --- hexadecimal, to preserve full precision. A string is written between double --- quotes, using escape sequences when necessary to ensure that it can safely be --- read back by the Lua interpreter. For instance, the call +-- The specifier `q` formats booleans, nil, numbers, and strings in a way that the result is a +-- valid constant in Lua source code. Booleans and nil are written in the obvious way (`true`, +-- `false`, `nil`). Floats are written in hexadecimal, to preserve full precision. A string is +-- written between double quotes, using escape sequences when necessary to ensure that it can +-- safely be read back by the Lua interpreter. For instance, the call -- -- string.format('%q', 'a string with "quotes" and \n new line') -- -- may produce the string: -- --- "a string with \"quotes\" and \ --- new line" +-- "a string with \"quotes\" and \ new line" -- -- This specifier does not support modifiers (flags, width, length). -- --- The conversion specifiers `A` and `a` (when available), `E`, `e`, `f`, `G`, --- and `g` all expect a number as argument. The specifiers `c`, `d`, `i`, `o`, --- `u`, `X`, and `x` expect an integer. When Lua is compiled with a C89 --- compiler, the specifiers `A` and `a` (hexadecimal floats) do not support --- modifiers. +-- The conversion specifiers `A` and `a` (when available), `E`, `e`, `f`, `G`, and `g` all +-- expect a number as argument. The specifiers `c`, `d`, `i`, `o`, `u`, `X`, and `x` expect an +-- integer. When Lua is compiled with a C89 compiler, the specifiers `A` and `a` (hexadecimal +-- floats) do not support modifiers. -- --- The specifier `s` expects a string; if its argument is not a string, it is --- converted to one following the same rules of `tostring`. If the specifier has --- any modifier, the corresponding string argument should not contain zeros. +-- The specifier `s` expects a string; if its argument is not a string, it is converted to one +-- following the same rules of `tostring`. If the specifier has any modifier, the corresponding +-- string argument should not contain zeros. -- --- The specifier `p` formats the pointer returned by `lua_topointer`. That gives --- a unique string identifier for tables, userdata, threads, strings, and --- functions. For other values (numbers, nil, booleans), this specifier results --- in a string representing the pointer `NULL`. +-- The specifier `p` formats the pointer returned by `lua_topointer`. That gives a unique string +-- identifier for tables, userdata, threads, strings, and functions. For other values (numbers, +-- nil, booleans), this specifier results in a string representing the pointer `NULL`. function string.format(formatstring, ···) end --- --- Returns an iterator function that, each time it is called, returns the --- next captures from `pattern` (see §6.4.1) over the string `s`. If `pattern` --- specifies no captures, then the whole match is produced in each call. A --- third, optional argument `init` specifies where to start the search; its --- default value is 1 and can be negative. +-- Returns an iterator function that, each time it is called, returns the next captures from +-- `pattern` (see §6.4.1) over the string `s`. If `pattern` specifies no captures, then the +-- whole match is produced in each call. A third, optional argument `init` specifies where to +-- start the search; its default value is 1 and can be negative. -- --- As an example, the following loop will iterate over all the words from string --- `s`, printing one per line: +-- As an example, the following loop will iterate over all the words from string `s`, printing +-- one per line: -- --- s = "hello world from Lua" --- for w in string.gmatch(s, "%a+") do --- print(w) --- end +-- s = "hello world from Lua" for w in string.gmatch(s, "%a+") do +-- print(w) end -- --- The next example collects all pairs `key=value` from the given string into a --- table: +-- The next example collects all pairs `key=value` from the given string into a table: -- --- t = {} --- s = "from=world, to=Lua" --- for k, v in string.gmatch(s, "(%w+)=(%w+)") do --- t[k] = v --- end +-- t = {} s = "from=world, to=Lua" for k, v in string.gmatch(s, "(%w+)=(%w+)") do +-- t[k] = v end -- --- For this function, a caret '`^`' at the start of a pattern does not work as --- an anchor, as this would prevent the iteration. +-- For this function, a caret '`^`' at the start of a pattern does not work as an anchor, +-- as this would prevent the iteration. function string.gmatch(s, pattern [, init]) end --- --- Returns a copy of `s` in which all (or the first `n`, if given) --- occurrences of the `pattern` (see §6.4.1) have been replaced by a replacement --- string specified by `repl`, which can be a string, a table, or a function. --- `gsub` also returns, as its second value, the total number of matches that --- occurred. The name `gsub` comes from "Global SUBstitution". +-- Returns a copy of `s` in which all (or the first `n`, if given) occurrences of the `pattern` +-- (see §6.4.1) have been replaced by a replacement string specified by `repl`, which can be +-- a string, a table, or a function. `gsub` also returns, as its second value, the total number +-- of matches that occurred. The name `gsub` comes from "Global SUBstitution". -- --- If `repl` is a string, then its value is used for replacement. The character --- `%` works as an escape character: any sequence in `repl` of the form `%d`, --- with `d` between 1 and 9, stands for the value of the `d`-th captured --- substring; the sequence `%0` stands for the whole match; the sequence `%%` --- stands for a single `%`. +-- If `repl` is a string, then its value is used for replacement. The character `%` works as an +-- escape character: any sequence in `repl` of the form `%d`, with `d` between 1 and 9, stands +-- for the value of the `d`-th captured substring; the sequence `%0` stands for the whole match; +-- the sequence `%%` stands for a single `%`. -- --- If `repl` is a table, then the table is queried for every match, using --- the first capture as the key. +-- If `repl` is a table, then the table is queried for every match, using the first capture as +-- the key. -- --- If `repl` is a function, then this function is called every time a match --- occurs, with all captured substrings passed as arguments, in order. +-- If `repl` is a function, then this function is called every time a match occurs, with all +-- captured substrings passed as arguments, in order. -- --- In any case, if the pattern specifies no captures, then it behaves as if the --- whole pattern was inside a capture. +-- In any case, if the pattern specifies no captures, then it behaves as if the whole pattern +-- was inside a capture. -- --- If the value returned by the table query or by the function call is a --- string or a number, then it is used as the replacement string; otherwise, --- if it is false or nil, then there is no replacement (that is, the original --- match is kept in the string). +-- If the value returned by the table query or by the function call is a string or a number, +-- then it is used as the replacement string; otherwise, if it is false or nil, then there is +-- no replacement (that is, the original match is kept in the string). -- -- Here are some examples: -- --- x = string.gsub("hello world", "(%w+)", "%1 %1") --- --> x="hello hello world world" --- x = string.gsub("hello world", "%w+", "%0 %0", 1) --- --> x="hello hello world" --- x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") --- --> x="world hello Lua from" --- x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) --- --> x="home = /home/roberto, user = roberto" +-- x = string.gsub("hello world", "(%w+)", "%1 %1") --> x="hello hello world world" x = +-- string.gsub("hello world", "%w+", "%0 %0", 1) --> x="hello hello world" x = string.gsub("hello +-- world from Lua", "(%w+)%s*(%w+)", "%2 %1") --> x="world hello Lua from" x = string.gsub("home +-- = $HOME, user = $USER", "%$(%w+)", os.getenv) --> x="home = /home/roberto, user = roberto" -- x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) --- return load(s)() --- end) --- --> x="4+5 = 9" --- local t = {name="lua", version="5.4"} --- x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) --- --> x="lua-5.4.tar.gz" +-- return load(s)() end) +-- --> x="4+5 = 9" local t = {name="lua", version="5.4"} x = string.gsub("$name-$version.tar.gz", +-- "%$(%w+)", t) --> x="lua-5.4.tar.gz" function string.gsub(s, pattern, repl [, n]) end --- --- Receives a string and returns its length. The empty string `""` has --- length 0. Embedded zeros are counted, so `"a\000bc\000"` has length 5. +-- Receives a string and returns its length. The empty string `""` has length 0. Embedded zeros +-- are counted, so `"a\000bc\000"` has length 5. function string.len(s) end --- --- Receives a string and returns a copy of this string with all uppercase --- letters changed to lowercase. All other characters are left unchanged. The --- definition of what an uppercase letter is depends on the current locale. +-- Receives a string and returns a copy of this string with all uppercase letters changed to +-- lowercase. All other characters are left unchanged. The definition of what an uppercase +-- letter is depends on the current locale. function string.lower(s) end --- --- Looks for the first *match* of the `pattern` (see §6.4.1) in the string `s`. --- If it finds one, then `match` returns the captures from the pattern; --- otherwise it returns nil. If `pattern` specifies no captures, then the whole --- match is returned. A third, optional numerical argument `init` specifies --- where to start the search; its default value is 1 and can be negative. +-- Looks for the first *match* of the `pattern` (see §6.4.1) in the string `s`. If it finds one, +-- then `match` returns the captures from the pattern; otherwise it returns nil. If `pattern` +-- specifies no captures, then the whole match is returned. A third, optional numerical argument +-- `init` specifies where to start the search; its default value is 1 and can be negative. function string.match(s, pattern [, init]) end --- --- Returns a binary string containing the values `v1`, `v2`, etc. serialized in --- binary form (packed) according to the format string `fmt` (see §6.4.2). +-- Returns a binary string containing the values `v1`, `v2`, etc. serialized in binary form +-- (packed) according to the format string `fmt` (see §6.4.2). -- -- New in Lua 5.3. function string.pack(fmt, v1, v2, ···) end --- --- Returns the size of a string resulting from `string.pack` with the given --- format. The format string cannot have the variable-length options 's' or 'z' --- (see §6.4.2). +-- Returns the size of a string resulting from `string.pack` with the given format. The format +-- string cannot have the variable-length options 's' or 'z' (see §6.4.2). -- -- New in Lua 5.3. function string.packsize(fmt) end --- --- Returns a string that is the concatenation of `n` copies of the string `s` --- separated by the string `sep`. The default value for `sep` is the empty --- string (that is, no separator). Returns the empty string if `n` is not --- positive. +-- Returns a string that is the concatenation of `n` copies of the string `s` separated by the +-- string `sep`. The default value for `sep` is the empty string (that is, no separator). Returns +-- the empty string if `n` is not positive. -- --- (Note that it is very easy to exhaust the memory of your machine with a --- single call to this function.) +-- (Note that it is very easy to exhaust the memory of your machine with a single call to +-- this function.) function string.rep(s, n [, sep]) end --- @@ -790,31 +716,28 @@ function string.rep(s, n [, sep]) end function string.reverse(s) end --- --- Returns the substring of `s` that starts at `i` and continues until --- `j`; `i` and `j` can be negative. If `j` is absent, then it is assumed to --- be equal to -1 (which is the same as the string length). In particular, --- the call `string.sub(s,1,j)` returns a prefix of `s` with length `j`, and --- `string.sub(s, -i)` returns a suffix of `s` with length `i`. +-- Returns the substring of `s` that starts at `i` and continues until `j`; `i` and `j` can +-- be negative. If `j` is absent, then it is assumed to be equal to -1 (which is the same as +-- the string length). In particular, the call `string.sub(s,1,j)` returns a prefix of `s` +-- with length `j`, and `string.sub(s, -i)` returns a suffix of `s` with length `i`. -- --- If, after the translation of negative indices, `i` is less than 1, it is --- corrected to 1. If `j` is greater than the string length, it is corrected to --- that length. If, after these corrections, `i` is greater than `j`, the --- function returns the empty string. +-- If, after the translation of negative indices, `i` is less than 1, it is corrected to 1. If `j` +-- is greater than the string length, it is corrected to that length. If, after these corrections, +-- `i` is greater than `j`, the function returns the empty string. function string.sub(s, i [, j]) end --- --- Returns the values packed in string `s` (see `string.pack`) according to the --- format string `fmt` (see §6.4.2). An optional `pos` marks where to start --- reading in `s` (default is 1). After the read values, this function also --- returns the index of the first unread byte in `s`. +-- Returns the values packed in string `s` (see `string.pack`) according to the format string +-- `fmt` (see §6.4.2). An optional `pos` marks where to start reading in `s` (default is +-- 1). After the read values, this function also returns the index of the first unread byte in `s`. -- -- New in Lua 5.3. function string.unpack(fmt, s [, pos]) end --- --- Receives a string and returns a copy of this string with all lowercase --- letters changed to uppercase. All other characters are left unchanged. The --- definition of what a lowercase letter is depends on the current locale. +-- Receives a string and returns a copy of this string with all lowercase letters changed to +-- uppercase. All other characters are left unchanged. The definition of what a lowercase letter +-- is depends on the current locale. function string.upper(s) end --- @@ -822,16 +745,14 @@ function string.upper(s) end -- @class table -- @name utf8 -- @field charpattern (string) --- The pattern (a string, not a function) "[\0-\x7F\xC2-\xFD][\x80-\xBF]*" --- (see §6.4.1), which matches exactly one UTF-8 byte sequence, assuming that --- the subject is a valid UTF-8 string. +-- The pattern (a string, not a function) "[\0-\x7F\xC2-\xFD][\x80-\xBF]*" (see §6.4.1), which +-- matches exactly one UTF-8 byte sequence, assuming that the subject is a valid UTF-8 string. -- -- New in Lua 5.3. --- --- Receives zero or more integers, converts each one to its corresponding UTF-8 --- byte sequence and returns a string with the concatenation of all these --- sequences. +-- Receives zero or more integers, converts each one to its corresponding UTF-8 byte sequence +-- and returns a string with the concatenation of all these sequences. -- -- New in Lua 5.3. function utf8.char(···) end @@ -841,58 +762,52 @@ function utf8.char(···) end -- -- for p, c in utf8.codes(s) do *body* end -- --- will iterate over all UTF-8 characters in string `s`, with `p` being the --- position (in bytes) and `c` the code point of each character. It raises an --- error if it meets any invalid byte sequence. +-- will iterate over all UTF-8 characters in string `s`, with `p` being the position (in bytes) and +-- `c` the code point of each character. It raises an error if it meets any invalid byte sequence. -- --- This function only accepts valid sequences (well formed and not overlong). --- By default, it only accepts byte sequences that result in valid Unicode code --- points, rejecting values greater than `10FFFF` and surrogates. The boolean --- argument `lax` lifts these checks, so that all values up to `0x7FFFFFFF` are --- accepted. (Not well formed and overlong sequences are still rejected.) +-- This function only accepts valid sequences (well formed and not overlong). By default, it only +-- accepts byte sequences that result in valid Unicode code points, rejecting values greater than +-- `10FFFF` and surrogates. The boolean argument `lax` lifts these checks, so that all values +-- up to `0x7FFFFFFF` are accepted. (Not well formed and overlong sequences are still rejected.) -- -- New in Lua 5.3. function utf8.codes(s [, lax]) end --- --- Returns the codepoints (as integers) from all characters in `s` that start --- between byte position `i` and `j` (both included). The default for `i` is 1 --- and for `j` is `i`. It raises an error if it meets any invalid byte sequence. +-- Returns the codepoints (as integers) from all characters in `s` that start between byte +-- position `i` and `j` (both included). The default for `i` is 1 and for `j` is `i`. It raises +-- an error if it meets any invalid byte sequence. -- --- This function only accepts valid sequences (well formed and not overlong). --- By default, it only accepts byte sequences that result in valid Unicode code --- points, rejecting values greater than `10FFFF` and surrogates. The boolean --- argument `lax` lifts these checks, so that all values up to `0x7FFFFFFF` are --- accepted. (Not well formed and overlong sequences are still rejected.) +-- This function only accepts valid sequences (well formed and not overlong). By default, it only +-- accepts byte sequences that result in valid Unicode code points, rejecting values greater than +-- `10FFFF` and surrogates. The boolean argument `lax` lifts these checks, so that all values +-- up to `0x7FFFFFFF` are accepted. (Not well formed and overlong sequences are still rejected.) -- -- New in Lua 5.3. function utf8.codepoint(s [, i [, j [, lax]]]) end --- --- Returns the number of UTF-8 characters in string `s` that start between --- positions `i` and `j` (both inclusive). The default for `i` is 1 and for `j` --- is -1. If it finds any invalid byte sequence, returns nil plus the position --- of the first invalid byte. +-- Returns the number of UTF-8 characters in string `s` that start between positions `i` and `j` +-- (both inclusive). The default for `i` is 1 and for `j` is -1. If it finds any invalid byte +-- sequence, returns nil plus the position of the first invalid byte. -- --- This function only accepts valid sequences (well formed and not overlong). --- By default, it only accepts byte sequences that result in valid Unicode code --- points, rejecting values greater than `10FFFF` and surrogates. The boolean --- argument `lax` lifts these checks, so that all values up to `0x7FFFFFFF` are --- accepted. (Not well formed and overlong sequences are still rejected.) +-- This function only accepts valid sequences (well formed and not overlong). By default, it only +-- accepts byte sequences that result in valid Unicode code points, rejecting values greater than +-- `10FFFF` and surrogates. The boolean argument `lax` lifts these checks, so that all values +-- up to `0x7FFFFFFF` are accepted. (Not well formed and overlong sequences are still rejected.) -- -- New in Lua 5.3. function utf8.len(s [, i [, j [, lax]]]) end --- --- Returns the position (in bytes) where the encoding of the `n`-th character of --- `s` (counting from position `i`) starts. A negative `n` gets characters --- before position `i`. The default for `i` is 1 when `n` is non-negative and --- `#s + 1` otherwise, so that `utf8.offset(s, -n)` gets the offset of the --- `n`-th character from the end of the string. If the specified character is --- neither in the subject nor right after its end, the function returns nil. +-- Returns the position (in bytes) where the encoding of the `n`-th character of `s` (counting +-- from position `i`) starts. A negative `n` gets characters before position `i`. The default +-- for `i` is 1 when `n` is non-negative and `#s + 1` otherwise, so that `utf8.offset(s, -n)` +-- gets the offset of the `n`-th character from the end of the string. If the specified character +-- is neither in the subject nor right after its end, the function returns nil. -- --- As a special case, when `n` is 0 the function returns the start of the --- encoding of the character that contains the `i`-th byte of `s`. +-- As a special case, when `n` is 0 the function returns the start of the encoding of the +-- character that contains the `i`-th byte of `s`. -- -- This function assumes that `s` is a valid UTF-8 string. -- @@ -901,31 +816,29 @@ function utf8.offset(s, n [, i]) end --- -- Given a list where all elements are strings or numbers, returns the string --- `list[i]..sep..list[i+1] ··· sep..list[j]`. The default value for `sep` is --- the empty string, the default for `i` is 1, and the default for `j` is --- `#list`. If `i` is greater than `j`, returns the empty string. +-- `list[i]..sep..list[i+1] ··· sep..list[j]`. The default value for `sep` is the empty +-- string, the default for `i` is 1, and the default for `j` is `#list`. If `i` is greater than +-- `j`, returns the empty string. function table.concat(list [, sep [, i [, j]]]) end --- --- Inserts element `value` at position `pos` in `list`, shifting up the elements --- `list[pos], list[pos+1], ···, list[#list]`. The default value for `pos` is --- `#list+1`, so that a call `table.insert(t,x)` inserts `x` at the end of the --- list `t`. +-- Inserts element `value` at position `pos` in `list`, shifting up the elements `list[pos], +-- list[pos+1], ···, list[#list]`. The default value for `pos` is `#list+1`, so that a call +-- `table.insert(t,x)` inserts `x` at the end of the list `t`. function table.insert(list, [pos,] value) end --- --- Returns the largest positive numerical index of the given table, or zero if --- the table has no positive numerical indices. (To do its job this function --- does a linear traversal of the whole table.) +-- Returns the largest positive numerical index of the given table, or zero if the table has +-- no positive numerical indices. (To do its job this function does a linear traversal of the +-- whole table.) -- -- Deprecated in Lua 5.2. function table.maxn(table) end --- --- Moves elements from the table `a1` to the table `a2`, performing the --- equivalent to the following multiple assignment: `a2[t], ··· = a1[f], ···, --- a1[e]`. The default for `a2` is `a1`. The destination range can overlap with --- the source range. Index `f` must be positive. +-- Moves elements from the table `a1` to the table `a2`, performing the equivalent to the +-- following multiple assignment: `a2[t], ··· = a1[f], ···, a1[e]`. The default for `a2` +-- is `a1`. The destination range can overlap with the source range. Index `f` must be positive. -- -- Returns the destination table `a2`. -- @@ -933,39 +846,35 @@ function table.maxn(table) end function table.move(a1, f, e, t [,a2]) end --- --- Returns a new table with all parameters stored into keys 1, 2, etc. and with --- a field "`n`" with the total number of parameters. Note that the resulting --- table may not be a sequence, if some arguments are nil. +-- Returns a new table with all parameters stored into keys 1, 2, etc. and with a field "`n`" +-- with the total number of parameters. Note that the resulting table may not be a sequence, +-- if some arguments are nil. -- -- New in Lua 5.2. function table.pack(···) end --- --- Removes from `list` the element at position `pos`, returning the value of the --- removed element. When `pos` is an integer between 1 and `#list`, it shifts --- down the elements `list[pos+1], list[pos+2], ···, list[#list]` and erases --- element `list[#list]`; The index `pos` can also be 0 when `#list` is 0, or --- `#list + 1`. +-- Removes from `list` the element at position `pos`, returning the value of the removed +-- element. When `pos` is an integer between 1 and `#list`, it shifts down the elements +-- `list[pos+1], list[pos+2], ···, list[#list]` and erases element `list[#list]`; The index +-- `pos` can also be 0 when `#list` is 0, or `#list + 1`. -- --- The default value for `pos` is `#list`, so that a call `table.remove(l)` --- removes the last element of the list `l`. +-- The default value for `pos` is `#list`, so that a call `table.remove(l)` removes the last +-- element of the list `l`. function table.remove(list [, pos]) end --- --- Sorts the list elements in a given order, *in-place*, from `list[1]` to --- `list[#list]`. If `comp` is given, then it must be a function that receives --- two list elements and returns true when the first element must come before --- the second in the final order (so that, after the sort, `i < j` implies --- `not comp(list[j],list[i])` will be true after the sort). If `comp` is not --- given, then the standard Lua operator `<` is used instead. +-- Sorts the list elements in a given order, *in-place*, from `list[1]` to `list[#list]`. If +-- `comp` is given, then it must be a function that receives two list elements and returns true +-- when the first element must come before the second in the final order (so that, after the +-- sort, `i < j` implies `not comp(list[j],list[i])` will be true after the sort). If `comp` +-- is not given, then the standard Lua operator `<` is used instead. -- --- Note that the `comp` function must not define a string partial order over the --- elements in the list; that is, it must be asymmetric and transitive. --- Otherwise, no valid sort may be possible. +-- Note that the `comp` function must not define a string partial order over the elements in the +-- list; that is, it must be asymmetric and transitive. Otherwise, no valid sort may be possible. -- --- The sort algorithm is not stable; that is, elements not comparable by the --- given order (e.g., equal elements) may have their relative positions changed --- by the sort. +-- The sort algorithm is not stable; that is, elements not comparable by the given order (e.g., +-- equal elements) may have their relative positions changed by the sort. function table.sort(list [, comp]) end --- @@ -1009,18 +918,15 @@ function math.acos(x) end function math.asin(x) end --- --- Returns the arc tangent of `y/x` (in radians), but uses the signs --- of both parameters to find the quadrant of the result. It also handles --- correctly the case of `x` being zero. +-- Returns the arc tangent of `y/x` (in radians), but uses the signs of both parameters to find +-- the quadrant of the result. It also handles correctly the case of `x` being zero. -- --- The default value for `x` is 1, so that the call `math.atan(y)` returns the --- arc tangent of `y`. +-- The default value for `x` is 1, so that the call `math.atan(y)` returns the arc tangent of `y`. function math.atan(y [, x]) end --- --- Returns the arc tangent of `y/x` (in radians), but uses the signs --- of both parameters to find the quadrant of the result. (It also handles --- correctly the case of `x` being zero.) +-- Returns the arc tangent of `y/x` (in radians), but uses the signs of both parameters to find +-- the quadrant of the result. (It also handles correctly the case of `x` being zero.) -- -- Deprecated in Lua 5.3. function math.atan2(y, x) end @@ -1052,13 +958,13 @@ function math.exp(x) end function math.floor(x) end --- --- Returns the remainder of the division of `x` by `y` that rounds the --- quotient towards zero. (integer/float) +-- Returns the remainder of the division of `x` by `y` that rounds the quotient towards +-- zero. (integer/float) function math.fmod(x, y) end --- --- Returns `m` and `e` such that 'x = m2^e', `e` is an integer and the --- absolute value of `m` is in the range *[0.5, 1)* (or zero when `x` is zero). +-- Returns `m` and `e` such that 'x = m2^e', `e` is an integer and the absolute value of `m` +-- is in the range *[0.5, 1)* (or zero when `x` is zero). -- -- Deprecated in Lua 5.3. function math.frexp(x) end @@ -1070,8 +976,8 @@ function math.frexp(x) end function math.ldexp(m, e) end --- --- Returns the logarithm of `x` in the given base. The default for `base` is 'e' --- (so that the function returns the natural logarithm of `x`). +-- Returns the logarithm of `x` in the given base. The default for `base` is 'e' (so that the +-- function returns the natural logarithm of `x`). function math.log(x [, base]) end --- @@ -1081,23 +987,20 @@ function math.log(x [, base]) end function math.log10(x) end --- --- Returns the argument with the maximum value, according to the Lua operator --- `<`. +-- Returns the argument with the maximum value, according to the Lua operator `<`. function math.max(x, ···) end --- --- Returns the argument with the minimum value, according to the Lua operator --- `<`. +-- Returns the argument with the minimum value, according to the Lua operator `<`. function math.min(x, ···) end --- --- Returns the integral part of `x` and the fractional part of `x`. Its second --- result is always a float. +-- Returns the integral part of `x` and the fractional part of `x`. Its second result is always +-- a float. function math.modf(x) end --- --- Returns *x^y*. (You can also use the expression `x^y` to compute this --- value.) +-- Returns *x^y*. (You can also use the expression `x^y` to compute this value.) -- -- Deprecated in Lua 5.3. function math.pow(x, y) end @@ -1107,37 +1010,34 @@ function math.pow(x, y) end function math.rad(x) end --- --- When called without arguments, returns a pseudo-random float with uniform --- distribution in the range [0,1). When called with two integers `m` and `n`, --- `math.random` returns a pseudo-random integer with uniform distribution in --- the range `[m, n]. The call `math.random(n)`, for a positive `n`, is --- equivalent to `math.random(1,n)`. The call `math.random(0)` produces an +-- When called without arguments, returns a pseudo-random float with uniform distribution in the +-- range [0,1). When called with two integers `m` and `n`, `math.random` returns a pseudo-random +-- integer with uniform distribution in the range `[m, n]. The call `math.random(n)`, for a +-- positive `n`, is equivalent to `math.random(1,n)`. The call `math.random(0)` produces an -- integer with all bits (pseudo)random. -- --- This function uses the `xoshiro256**` algorithm to produce pseudo-random --- 64-bit integers, which are the results of calls with argument 0. Other --- results (ranges and floats) are unbiased extracted from these integers. +-- This function uses the `xoshiro256**` algorithm to produce pseudo-random 64-bit integers, +-- which are the results of calls with argument 0. Other results (ranges and floats) are unbiased +-- extracted from these integers. -- --- Lua initializes its pseudo-random generator with the equivalent of a call to --- `math.randomseed` with no arguments, so that `math.random` should generate --- different sequences of results each time the program runs. +-- Lua initializes its pseudo-random generator with the equivalent of a call to `math.randomseed` +-- with no arguments, so that `math.random` should generate different sequences of results each +-- time the program runs. function math.random([m [, n]]) end --- --- When called with at least one argument, the integer parameters `x` and `y` --- are joined into a 128-bit *seed* that is used to reinitialize the --- pseudo-random generator; equal seeds produce equal sequences of numbers. The --- default for `y` is zero. +-- When called with at least one argument, the integer parameters `x` and `y` are joined into a +-- 128-bit *seed* that is used to reinitialize the pseudo-random generator; equal seeds produce +-- equal sequences of numbers. The default for `y` is zero. -- --- When called with no arguments, Lua generates a seed with a weak attempt for --- randomness. +-- When called with no arguments, Lua generates a seed with a weak attempt for randomness. -- --- This function returns the two seed components that were effectively used, so --- that setting them again repeats the sequence. +-- This function returns the two seed components that were effectively used, so that setting +-- them again repeats the sequence. -- --- To ensure a required level of randomness to the initial state (or contrarily, --- to have a deterministic sequence, for instance when debugging a program), you --- should call `math.randomseed` with explicit arguments. +-- To ensure a required level of randomness to the initial state (or contrarily, to have +-- a deterministic sequence, for instance when debugging a program), you should call +-- `math.randomseed` with explicit arguments. function math.randomseed([x [, y]]) end --- @@ -1151,8 +1051,7 @@ function math.sin(x) end function math.sinh(x) end --- --- Returns the square root of `x`. (You can also use the expression `x^0.5` --- to compute this value.) +-- Returns the square root of `x`. (You can also use the expression `x^0.5` to compute this value.) function math.sqrt(x) end --- @@ -1166,101 +1065,88 @@ function math.tan(x) end function math.tanh(x) end --- --- If the value `x` is convertible to an integer, returns that integer. --- Otherwise, returns nil. +-- If the value `x` is convertible to an integer, returns that integer. Otherwise, returns nil. -- -- New in Lua 5.3. function math.tointeger(x) end --- --- Returns "integer" if `x` is an integer, "float" if it is a float, or nil if --- x is not a number. +-- Returns "integer" if `x` is an integer, "float" if it is a float, or nil if x is not a number. -- -- New in Lua 5.3. function math.type(x) end --- --- Returns a boolean, true if integer `m` is below integer `n` when they are --- compared as unsigned integers. +-- Returns a boolean, true if integer `m` is below integer `n` when they are compared as +-- unsigned integers. -- -- New in Lua 5.3. function math.ult(m, n) end --- --- Returns the number `x` shifted `disp` bits to the right. The number `disp` --- may be any representable integer. Negative displacements shift to the left. +-- Returns the number `x` shifted `disp` bits to the right. The number `disp` may be any +-- representable integer. Negative displacements shift to the left. -- --- This shift operation is what is called arithmetic shift. Vacant bits on the --- left are filled with copies of the higher bit of `x`; vacant bits on the --- right are filled with zeros. In particular, displacements with absolute --- values higher than 31 result in zero or `0xFFFFFFFF` (all original bits are --- shifted out). +-- This shift operation is what is called arithmetic shift. Vacant bits on the left are filled +-- with copies of the higher bit of `x`; vacant bits on the right are filled with zeros. In +-- particular, displacements with absolute values higher than 31 result in zero or `0xFFFFFFFF` +-- (all original bits are shifted out). -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.arshift(x, disp) end --- -- Returns the bitwise "and" of its operands. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.band(...) end --- --- Returns the bitwise negation of `x`. For any integer `x`, the following --- identity holds: +-- Returns the bitwise negation of `x`. For any integer `x`, the following identity holds: -- -- assert(bit32.bnot(x) == (-1 - x) % 2^32) -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.bnot(x) end --- -- Returns the bitwise "or" of its operands. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.bor(...) end --- --- Returns a boolean signaling whether the bitwise "and" of its operands is --- different from zero. +-- Returns a boolean signaling whether the bitwise "and" of its operands is different from zero. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.btest(...) end --- -- Returns the bitwise "exclusive or" of its operands. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.xor(...) end --- --- Returns the unsigned number formed by the bits `field` to `field + width - 1` --- from `n`. Bits are numbered from 0 (least significant) to 31 (most --- significant). All accessed bits must be in the range [0, 31]. +-- Returns the unsigned number formed by the bits `field` to `field + width - 1` from `n`. Bits +-- are numbered from 0 (least significant) to 31 (most significant). All accessed bits must be +-- in the range [0, 31]. -- -- The default for `width` is 1. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.extract(n, field [, width]) end --- --- Returns a copy of `n` with the bits `field` to `field + width - 1` replaced --- by the value `v`. See `bit32.extract` for details about `field` and `width`. +-- Returns a copy of `n` with the bits `field` to `field + width - 1` replaced by the value +-- `v`. See `bit32.extract` for details about `field` and `width`. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.replace(n, v, field [, width]) end --- --- Returns the number `x` rotated `disp` bits to the left. The number `disp` may --- be any representable integer. +-- Returns the number `x` rotated `disp` bits to the left. The number `disp` may be any +-- representable integer. -- -- For any valid displacement, the following identity holds: -- @@ -1268,28 +1154,25 @@ function bit32.replace(n, v, field [, width]) end -- -- In particular, negative displacements rotate to the right. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.lrotate(x, disp) end --- --- Returns the number `x` shifted `disp` bits to the left. The number `disp` may --- be any representable integer. Negative displacements shift to the right. In --- any direction, vacant bits are filled with zeros. In particular, --- displacements with absolute values higher than 31 result in zero (all bits --- are shifted out). +-- Returns the number `x` shifted `disp` bits to the left. The number `disp` may be any +-- representable integer. Negative displacements shift to the right. In any direction, vacant +-- bits are filled with zeros. In particular, displacements with absolute values higher than +-- 31 result in zero (all bits are shifted out). -- -- For positive displacements, the following equality holds: -- -- assert(bit32.lshift(b, disp) == (b * 2^disp) % 2^32) -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.lshift(x, disp) end --- --- Returns the number `x` rotated `disp` bits to the right. The number `disp` --- may be any representable integer. +-- Returns the number `x` rotated `disp` bits to the right. The number `disp` may be any +-- representable integer. -- -- For any valid displacement, the following identity holds: -- @@ -1297,16 +1180,14 @@ function bit32.lshift(x, disp) end -- -- In particular, negative displacements rotate to the left. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.rrotate(x, disp) end --- --- Returns the number `x` shifted `disp` bits to the right. The number `disp` --- may be any representable integer. Negative displacements shift to the left. --- In any direction, vacant bits are filled with zeros. In particular, --- displacements with absolute values higher than 31 result in zero (all bits --- are shifted out). +-- Returns the number `x` shifted `disp` bits to the right. The number `disp` may be any +-- representable integer. Negative displacements shift to the left. In any direction, vacant +-- bits are filled with zeros. In particular, displacements with absolute values higher than +-- 31 result in zero (all bits are shifted out). -- -- For positive displacements, the following equality holds: -- @@ -1314,8 +1195,7 @@ function bit32.rrotate(x, disp) end -- -- This shift operation is what is called logical shift. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.rshift(x, disp) end --- @@ -1331,8 +1211,7 @@ function bit32.rshift(x, disp) end local io --- --- Equivalent to `file:close()`. Without a `file`, closes the default --- output file. +-- Equivalent to `file:close()`. Without a `file`, closes the default output file. function io.close([file]) end --- @@ -1340,47 +1219,44 @@ function io.close([file]) end function io.flush() end --- --- When called with a file name, it opens the named file (in text mode), --- and sets its handle as the default input file. When called with a file --- handle, it simply sets this file handle as the default input file. When --- called without parameters, it returns the current default input file. +-- When called with a file name, it opens the named file (in text mode), and sets its handle as +-- the default input file. When called with a file handle, it simply sets this file handle as the +-- default input file. When called without parameters, it returns the current default input file. -- --- In case of errors this function raises the error, instead of returning an --- error code. +-- In case of errors this function raises the error, instead of returning an error code. function io.input([file]) end --- --- Opens the given file name in read mode and returns an iterator function that --- works like `file:lines(···)` over the opened file. When the iterator function --- fails to read any value, it automatically closes the file. Besides the --- iterator function, `io.lines` returns three other values: two nil values as --- placeholders, plus the created file handle. Therefore, when used in a generic --- for loop, the file is closed also if the loop is interrupted by an error or a --- `break`. +-- Opens the given file name in read mode and returns an iterator function that works like +-- `file:lines(···)` over the opened file. When the iterator function fails to read any value, +-- it automatically closes the file. Besides the iterator function, `io.lines` returns three other +-- values: two nil values as placeholders, plus the created file handle. Therefore, when used in +-- a generic for loop, the file is closed also if the loop is interrupted by an error or a `break`. -- --- The call `io.lines()` (with no file name) is equivalent to --- `io.input():lines("l")`; that is, it iterates over the lines of the default --- input file. In this case it does not close the file when the loop ends. +-- The call `io.lines()` (with no file name) is equivalent to `io.input():lines("l")`; that is, +-- it iterates over the lines of the default input file. In this case it does not close the +-- file when the loop ends. -- --- In case of errors opening the file, this function raises the error, instead --- of returning an error code. +-- In case of errors opening the file, this function raises the error, instead of returning an +-- error code. function io.lines([filename, ···]) end --- --- This function opens a file, in the mode specified in the string `mode`. It --- returns a new file handle, or, in case of errors, nil plus an error message. +-- This function opens a file, in the mode specified in the string `mode`. It returns a new +-- file handle, or, in case of errors, nil plus an error message. -- -- The `mode` string can be any of the following: --- "r": read mode (the default); --- "w": write mode; --- "a": append mode; --- "r+": update mode, all previous data is preserved; --- "w+": update mode, all previous data is erased; --- "a+": append update mode, previous data is preserved, writing is only --- allowed at the end of file. --- --- The `mode` string can also have a '`b`' at the end, which is needed in --- some systems to open the file in binary mode. +-- +-- * "r": read mode (the default); +-- * "w": write mode; +-- * "a": append mode; +-- * "r+": update mode, all previous data is preserved; +-- * "w+": update mode, all previous data is erased; +-- * "a+": append update mode, previous data is preserved, writing is only allowed at the +-- end of file. +-- +-- The `mode` string can also have a '`b`' at the end, which is needed in some systems to open +-- the file in binary mode. function io.open(filename [, mode]) end --- @@ -1388,9 +1264,9 @@ function io.open(filename [, mode]) end function io.output([file]) end --- --- Starts the program `prog` in a separated process and returns a file handle --- that you can use to read data from this program (if `mode` is `"r"`, --- the default) or to write data to this program (if `mode` is `"w"`). +-- Starts the program `prog` in a separated process and returns a file handle that you can use +-- to read data from this program (if `mode` is `"r"`, the default) or to write data to this +-- program (if `mode` is `"w"`). -- -- This function is system dependent and is not available on all platforms. function io.popen(prog [, mode]) end @@ -1400,14 +1276,14 @@ function io.popen(prog [, mode]) end function io.read(···) end --- --- In case of success, returns a handle for a temporary file. This file is --- opened in update mode and it is automatically removed when the program ends. +-- In case of success, returns a handle for a temporary file. This file is opened in update +-- mode and it is automatically removed when the program ends. function io.tmpfile() end --- --- Checks whether `obj` is a valid file handle. Returns the string `"file"` --- if `obj` is an open file handle, `"closed file"` if `obj` is a closed file --- handle, or nil if `obj` is not a file handle. +-- Checks whether `obj` is a valid file handle. Returns the string `"file"` if `obj` is an +-- open file handle, `"closed file"` if `obj` is a closed file handle, or nil if `obj` is not +-- a file handle. function io.type(obj) end --- @@ -1415,12 +1291,11 @@ function io.type(obj) end function io.write(···) end --- --- Closes `file`. Note that files are automatically closed when their --- handles are garbage collected, but that takes an unpredictable amount of --- time to happen. +-- Closes `file`. Note that files are automatically closed when their handles are garbage +-- collected, but that takes an unpredictable amount of time to happen. -- --- When closing a file handle created with `io.popen`, `file:close` returns the --- same values returned by `os.execute`. +-- When closing a file handle created with `io.popen`, `file:close` returns the same values +-- returned by `os.execute`. function file:close() end --- @@ -1428,228 +1303,210 @@ function file:close() end function file:flush() end --- --- Returns an iterator function that, each time it is called, reads the file --- according to the given formats. When no format is given, uses "l" as a --- default. As an example, the construction +-- Returns an iterator function that, each time it is called, reads the file according to the +-- given formats. When no format is given, uses "l" as a default. As an example, the construction -- -- for c in file:lines(1) do *body* end -- --- will iterate over all characters of the file, starting at the current --- position. Unlike `io.lines`, this function does not close the file when the --- loop ends. +-- will iterate over all characters of the file, starting at the current position. Unlike +-- `io.lines`, this function does not close the file when the loop ends. function file:lines(···) end --- --- Reads the file `file`, according to the given formats, which specify --- what to read. For each format, the function returns a string or a number --- with the characters read, or nil if it cannot read data with the specified --- format. (In this latter case, the function does not read subsequent formats.) --- When called without arguments, it uses a default format that reads the next --- line (see below). +-- Reads the file `file`, according to the given formats, which specify what to read. For each +-- format, the function returns a string or a number with the characters read, or nil if it +-- cannot read data with the specified format. (In this latter case, the function does not read +-- subsequent formats.) When called without arguments, it uses a default format that reads +-- the next line (see below). -- -- The available formats are --- "n": reads a numeral and returns it as a float or an integer, following the --- lexical conventions of Lua. (The numeral may have leading whitespaces --- and a sign.) This format always reads the longest input sequence that --- is a valid prefix for a number; if that prefix does not form a valid --- number (e.g., an empty string, "0x", or "3.4e-") or it is too long --- (more than 200 characters), it is discarded and the format returns --- nil. --- "a": reads the whole file, starting at the current position. On end of --- file, it returns the empty string; this format never fails. --- "l": reads the next line skipping the end of line, returning nil on --- end of file. This is the default format. --- "L": reads the next line keeping the end-of-line character (if present), --- returning nil on end of file. --- *number*: reads a string with up to this number of bytes, returning nil on --- end of file. If *number* is zero, it reads nothing and returns an --- empty string, or nil on end of file. +-- +-- * "n": reads a numeral and returns it as a float or an integer, following the lexical +-- conventions of Lua. (The numeral may have leading whitespaces and a sign.) This format +-- always reads the longest input sequence that is a valid prefix for a number; if that +-- prefix does not form a valid number (e.g., an empty string, "0x", or "3.4e-") or it is +-- too long (more than 200 characters), it is discarded and the format returns nil. +-- * "a": reads the whole file, starting at the current position. On end of file, it returns +-- the empty string; this format never fails. +-- * "l": reads the next line skipping the end of line, returning nil on end of file. This +-- is the default format. +-- * "L": reads the next line keeping the end-of-line character (if present), returning nil +-- on end of file. +-- * *number*: reads a string with up to this number of bytes, returning nil on end of file. If +-- *number* is zero, it reads nothing and returns an empty string, or nil on end of file. -- -- The formats "l" and "L" should be used only for text files. function file:read(···) end --- --- Sets and gets the file position, measured from the beginning of the --- file, to the position given by `offset` plus a base specified by the string --- `whence`, as follows: --- "set": base is position 0 (beginning of the file); --- "cur": base is current position; --- "end": base is end of file; +-- Sets and gets the file position, measured from the beginning of the file, to the position +-- given by `offset` plus a base specified by the string `whence`, as follows: -- --- In case of success, function `seek` returns the final file position, --- measured in bytes from the beginning of the file. If `seek` fails, it returns --- nil, plus a string describing the error. +-- * "set": base is position 0 (beginning of the file); +-- * "cur": base is current position; +-- * "end": base is end of file; -- --- The default value for `whence` is `"cur"`, and for `offset` is 0. Therefore, --- the call `file:seek()` returns the current file position, without changing --- it; the call `file:seek("set")` sets the position to the beginning of the --- file (and returns 0); and the call `file:seek("end")` sets the position --- to the end of the file, and returns its size. +-- In case of success, function `seek` returns the final file position, measured in bytes from +-- the beginning of the file. If `seek` fails, it returns nil, plus a string describing the error. +-- +-- The default value for `whence` is `"cur"`, and for `offset` is 0. Therefore, the +-- call `file:seek()` returns the current file position, without changing it; the call +-- `file:seek("set")` sets the position to the beginning of the file (and returns 0); and the +-- call `file:seek("end")` sets the position to the end of the file, and returns its size. function file:seek([whence [, offset]]) end --- -- Sets the buffering mode for a file. There are three available modes: --- "no": no buffering --- "full": full buffering --- "line": line buffering -- --- For the last two cases, `size` is a hint for the size of the buffer, in --- bytes. The default is an appropriate size. +-- * "no": no buffering +-- * "full": full buffering +-- * "line": line buffering +-- +-- For the last two cases, `size` is a hint for the size of the buffer, in bytes. The default +-- is an appropriate size. -- --- The specific behavior of each mode is non portable; check the underlying --- ISO C function `setvbuf` in your platform for more details. +-- The specific behavior of each mode is non portable; check the underlying ISO C function +-- `setvbuf` in your platform for more details. function file:setvbuf(mode [, size]) end --- --- Writes the value of each of its arguments to `file`. The arguments must be --- strings or numbers. +-- Writes the value of each of its arguments to `file`. The arguments must be strings or numbers. -- --- In case of success, this function returns `file`. Otherwise it returns nil --- plus a string describing the error. +-- In case of success, this function returns `file`. Otherwise it returns nil plus a string +-- describing the error. function file:write(···) end --- --- Returns an approximation of the amount in seconds of CPU time used by --- the program, as returned by the underlying ISO C function `clock`. +-- Returns an approximation of the amount in seconds of CPU time used by the program, as returned +-- by the underlying ISO C function `clock`. function os.clock() end --- --- Returns a string or a table containing date and time, formatted according --- to the given string `format`. +-- Returns a string or a table containing date and time, formatted according to the given string +-- `format`. -- --- If the `time` argument is present, this is the time to be formatted --- (see the `os.time` function for a description of this value). Otherwise, --- `date` formats the current time. +-- If the `time` argument is present, this is the time to be formatted (see the `os.time` +-- function for a description of this value). Otherwise, `date` formats the current time. -- --- If `format` starts with '`!`', then the date is formatted in Coordinated --- Universal Time. After this optional character, if `format` is the string --- "`*t`", then `date` returns a table with the following fields: `year`, --- `month` (1-12), `day` (1-31), `hour` (0-23), `min` (0-59), `sec` (0-61, due --- to leap seconds), `wday` (weekday, 1-7, Sunday is 1), `yday` (day of the --- year, 1-366), and `isdst` (daylight saving flag, a boolean). This last field --- may be absent if the information is not available. +-- If `format` starts with '`!`', then the date is formatted in Coordinated Universal Time. After +-- this optional character, if `format` is the string "`*t`", then `date` returns a table with +-- the following fields: `year`, `month` (1-12), `day` (1-31), `hour` (0-23), `min` (0-59), +-- `sec` (0-61, due to leap seconds), `wday` (weekday, 1-7, Sunday is 1), `yday` (day of the +-- year, 1-366), and `isdst` (daylight saving flag, a boolean). This last field may be absent +-- if the information is not available. -- --- If `format` is not "`*t`", then `date` returns the date as a string, --- formatted according to the same rules as the ISO C function `strftime`. +-- If `format` is not "`*t`", then `date` returns the date as a string, formatted according to +-- the same rules as the ISO C function `strftime`. -- --- If `format` is absent, it defaults to "`%c`", which gives a human-readable --- date and time representation using the current locale. +-- If `format` is absent, it defaults to "`%c`", which gives a human-readable date and time +-- representation using the current locale. -- --- On non-POSIX systems, this function may be not thread safe because of its --- reliance on C function `gmtime` and C function `localtime`. +-- On non-POSIX systems, this function may be not thread safe because of its reliance on C +-- function `gmtime` and C function `localtime`. function os.date([format [, time]]) end --- --- Returns the difference, in seconds, from time `t1` to time `t2` (where the --- times are values returned by `os.time`). In POSIX, Windows, and some other --- systems, this value is exactly `t2`*-*`t1`. +-- Returns the difference, in seconds, from time `t1` to time `t2` (where the times are values +-- returned by `os.time`). In POSIX, Windows, and some other systems, this value is exactly +-- `t2`*-*`t1`. function os.difftime(t2, t1) end --- --- This function is equivalent to the ISO C function `system`. It passes --- `command` to be executed by an operating system shell. Its first result is --- `true` if the command terminated successfully, or `nil` otherwise. After this --- first result the function returns a string plus a number, as follows: --- "exit": the command terminated normally; the following number is the exit --- status of the command. --- "signal": the command was terminated by a signal; the following number is --- the signal that terminated the command. +-- This function is equivalent to the ISO C function `system`. It passes `command` to be +-- executed by an operating system shell. Its first result is `true` if the command terminated +-- successfully, or `nil` otherwise. After this first result the function returns a string plus +-- a number, as follows: -- --- When called without a `command`, `os.execute` returns a boolean that is true --- if a shell is available. +-- * "exit": the command terminated normally; the following number is the exit status of +-- the command. +-- * "signal": the command was terminated by a signal; the following number is the signal +-- that terminated the command. +-- +-- When called without a `command`, `os.execute` returns a boolean that is true if a shell +-- is available. function os.execute([command]) end --- --- Calls the ISO C function `exit` to terminate the host program. If `code` is --- `true`, the returned status is `EXIT_SUCCESS`; if `code` is `false`, the --- returned status is `EXIT_FAILURE`; if `code` is a number, the returned status --- is this number. The default value for `code` is `true`. +-- Calls the ISO C function `exit` to terminate the host program. If `code` is `true`, the returned +-- status is `EXIT_SUCCESS`; if `code` is `false`, the returned status is `EXIT_FAILURE`; if +-- `code` is a number, the returned status is this number. The default value for `code` is `true`. -- --- If the optional second argument `close` is true, closes the Lua state before --- exiting. +-- If the optional second argument `close` is true, closes the Lua state before exiting. function os.exit([code [, close]]) end --- --- Returns the value of the process environment variable `varname`, or --- nil if the variable is not defined. +-- Returns the value of the process environment variable `varname`, or nil if the variable is +-- not defined. function os.getenv(varname) end --- --- Deletes the file (or empty directory, on POSIX systems) with the given name. --- If this function fails, it returns nil, plus a string describing the error --- and the error code. +-- Deletes the file (or empty directory, on POSIX systems) with the given name. If this function +-- fails, it returns nil, plus a string describing the error and the error code. function os.remove(filename) end --- --- Renames file or directory named `oldname` to `newname`. If this function --- fails, it returns nil, plus a string describing the error and the error code. +-- Renames file or directory named `oldname` to `newname`. If this function fails, it returns +-- nil, plus a string describing the error and the error code. function os.rename(oldname, newname) end --- --- Sets the current locale of the program. `locale` is a system-dependent string --- specifying a locale; `category` is an optional string describing which --- category to change: `"all"`, `"collate"`, `"ctype"`, `"monetary"`, --- `"numeric"`, or `"time"`; the default category is `"all"`. The function --- returns the name of the new locale, or nil if the request cannot be honored. +-- Sets the current locale of the program. `locale` is a system-dependent string specifying +-- a locale; `category` is an optional string describing which category to change: `"all"`, +-- `"collate"`, `"ctype"`, `"monetary"`, `"numeric"`, or `"time"`; the default category is +-- `"all"`. The function returns the name of the new locale, or nil if the request cannot +-- be honored. -- --- If `locale` is the empty string, the current locale is set to an --- implementation-defined native locale. If `locale` is the string "`C`", --- the current locale is set to the standard C locale. +-- If `locale` is the empty string, the current locale is set to an implementation-defined native +-- locale. If `locale` is the string "`C`", the current locale is set to the standard C locale. -- --- When called with nil as the first argument, this function only returns --- the name of the current locale for the given category. +-- When called with nil as the first argument, this function only returns the name of the +-- current locale for the given category. -- --- This function may not be thread safe because of its reliance on C function --- `setlocale`. +-- This function may not be thread safe because of its reliance on C function `setlocale`. function os.setlocale(locale [, category]) end --- --- Returns the current time when called without arguments, or a time --- representing the date and time specified by the given table. This table --- must have fields `year`, `month`, and `day`, and may have fields `hour` --- (default is 12), `min` (default is 0), `sec` (default is 0), and `isdst` --- (default is nil). For a description of these fields, see the `os.date` --- function. +-- Returns the current time when called without arguments, or a time representing the date and +-- time specified by the given table. This table must have fields `year`, `month`, and `day`, +-- and may have fields `hour` (default is 12), `min` (default is 0), `sec` (default is 0), and +-- `isdst` (default is nil). For a description of these fields, see the `os.date` function. -- --- When the function is called, the values in these fields do not need to be --- inside their valid ranges. For instance, if `sec` is -10, it means 10 seconds --- before the time specified by the other fields; if `hour` is 1000, it means --- 1000 hours after the time specified by the other fields. +-- When the function is called, the values in these fields do not need to be inside their +-- valid ranges. For instance, if `sec` is -10, it means 10 seconds before the time specified +-- by the other fields; if `hour` is 1000, it means 1000 hours after the time specified by the +-- other fields. -- --- The returned value is a number, whose meaning depends on your system. In --- POSIX, Windows, and some other systems, this number counts the number of --- seconds since some given start time (the "epoch"). In other systems, the --- meaning is not specified, and the number returned by `time` can be used only --- as an argument to `os.date` and `os.difftime`. +-- The returned value is a number, whose meaning depends on your system. In POSIX, Windows, +-- and some other systems, this number counts the number of seconds since some given start time +-- (the "epoch"). In other systems, the meaning is not specified, and the number returned by +-- `time` can be used only as an argument to `os.date` and `os.difftime`. -- --- When called with a table, `os.time` also normalizes all the fields documented --- in the `os.date` function, so that they represent the same time as before the --- call but with values inside their valid ranges. +-- When called with a table, `os.time` also normalizes all the fields documented in the `os.date` +-- function, so that they represent the same time as before the call but with values inside +-- their valid ranges. function os.time([table]) end --- --- Returns a string with a file name that can be used for a temporary --- file. The file must be explicitly opened before its use and explicitly --- removed when no longer needed. +-- Returns a string with a file name that can be used for a temporary file. The file must be +-- explicitly opened before its use and explicitly removed when no longer needed. -- --- On POSIX systems, this function also creates a file with that name, to avoid --- security risks. (Someone else might create the file with wrong permissions in --- the time between getting the name and creating the file.) You still have to --- open the file to use it and to remove it (even if you do not use it). +-- On POSIX systems, this function also creates a file with that name, to avoid security +-- risks. (Someone else might create the file with wrong permissions in the time between getting +-- the name and creating the file.) You still have to open the file to use it and to remove it +-- (even if you do not use it). -- --- When possible, you may prefer to use `io.tmpfile`, which automatically --- removes the file when the program ends. +-- When possible, you may prefer to use `io.tmpfile`, which automatically removes the file when +-- the program ends. function os.tmpname() end --- --- Enters an interactive mode with the user, running each string that --- the user enters. Using simple commands and other debug facilities, --- the user can inspect global and local variables, change their values, --- evaluate expressions, and so on. A line containing only the word `cont` +-- Enters an interactive mode with the user, running each string that the user enters. Using +-- simple commands and other debug facilities, the user can inspect global and local variables, +-- change their values, evaluate expressions, and so on. A line containing only the word `cont` -- finishes this function, so that the caller continues its execution. -- --- Note that commands for `debug.debug` are not lexically nested within any --- function and so have no direct access to local variables. +-- Note that commands for `debug.debug` are not lexically nested within any function and so +-- have no direct access to local variables. function debug.debug() end --- @@ -1659,60 +1516,54 @@ function debug.debug() end function debug.getfenv(o) end --- --- Returns the current hook settings of the thread, as three values: the --- current hook function, the current hook mask, and the current hook count, --- as set by the `debug.sethook` function. +-- Returns the current hook settings of the thread, as three values: the current hook function, +-- the current hook mask, and the current hook count, as set by the `debug.sethook` function. -- -- Returns nil if there is no active hook. function debug.gethook([thread]) end --- --- Returns a table with information about a function. You can give the --- function directly or you can give a number as the value of `f`, which means --- the function running at level `f` of the call stack of the given thread: --- level 0 is the current function (`getinfo` itself); level 1 is the function --- that called `getinfo` (except for tail calls, which do not count in the --- stack); and so on. If `f` is a number greater than the number of active --- functions, then `getinfo` returns nil. --- --- The returned table can contain all the fields returned by `lua_getinfo`, --- with the string `what` describing which fields to fill in. The default for --- `what` is to get all information available, except the table of valid --- lines. If present, the option '`f`' adds a field named `func` with --- the function itself. If present, the option '`L`' adds a field named --- `activelines` with the table of valid lines. --- --- For instance, the expression `debug.getinfo(1,"n").name` returns a table --- with a name for the current function, if a reasonable name can be found, --- and the expression `debug.getinfo(print)` returns a table with all available --- information about the `print` function. +-- Returns a table with information about a function. You can give the function directly or +-- you can give a number as the value of `f`, which means the function running at level `f` +-- of the call stack of the given thread: level 0 is the current function (`getinfo` itself); +-- level 1 is the function that called `getinfo` (except for tail calls, which do not count in +-- the stack); and so on. If `f` is a number greater than the number of active functions, then +-- `getinfo` returns nil. +-- +-- The returned table can contain all the fields returned by `lua_getinfo`, with the string +-- `what` describing which fields to fill in. The default for `what` is to get all information +-- available, except the table of valid lines. If present, the option '`f`' adds a field named +-- `func` with the function itself. If present, the option '`L`' adds a field named `activelines` +-- with the table of valid lines. +-- +-- For instance, the expression `debug.getinfo(1,"n").name` returns a table with a name for the +-- current function, if a reasonable name can be found, and the expression `debug.getinfo(print)` +-- returns a table with all available information about the `print` function. function debug.getinfo([thread,] f [, what]) end --- --- This function returns the name and the value of the local variable with index --- `local` of the function at level `f` of the stack. This function accesses not --- only explicit local variables, but also parameters and temporary values. +-- This function returns the name and the value of the local variable with index `local` of the +-- function at level `f` of the stack. This function accesses not only explicit local variables, +-- but also parameters and temporary values. -- --- The first parameter or local variable has index 1, and so on, following the --- order that they are declared in the code, counting only the variables that --- are active in the current scope of the function. Compile-time constants may --- not appear in this listing, if they were optimized away by the compiler. --- Negative indices refer to vararg parameters; -1 is the first vararg --- parameter. The function returns nil if there is no variable with the given --- index, and raises an error when called with a level out of range. (You can --- call `debug.getinfo` to check whether the level is valid.) +-- The first parameter or local variable has index 1, and so on, following the order that +-- they are declared in the code, counting only the variables that are active in the current +-- scope of the function. Compile-time constants may not appear in this listing, if they were +-- optimized away by the compiler. Negative indices refer to vararg parameters; -1 is the first +-- vararg parameter. The function returns nil if there is no variable with the given index, +-- and raises an error when called with a level out of range. (You can call `debug.getinfo` +-- to check whether the level is valid.) -- --- Variable names starting with '(' (open parenthesis) represent variables with --- no known names (internal variables such as loop control variables, and --- variables from chunks saved without debug information). +-- Variable names starting with '(' (open parenthesis) represent variables with no known names +-- (internal variables such as loop control variables, and variables from chunks saved without +-- debug information). -- --- The parameter `f` may also be a function. In that case, `getlocal` returns --- only the name of function parameters. +-- The parameter `f` may also be a function. In that case, `getlocal` returns only the name of +-- function parameters. function debug.getlocal([thread,] f, local) end --- --- Returns the metatable of the given `value` or nil if it does not have --- a metatable. +-- Returns the metatable of the given `value` or nil if it does not have a metatable. function debug.getmetatable(value) end --- @@ -1720,82 +1571,77 @@ function debug.getmetatable(value) end function debug.getregistry() end --- --- This function returns the name and the value of the upvalue with index --- `up` of the function `f`. The function returns nil if there is no upvalue --- with the given index. +-- This function returns the name and the value of the upvalue with index `up` of the function +-- `f`. The function returns nil if there is no upvalue with the given index. -- --- (For Lua functions, upvalues are the external local variables that the --- function uses, and that are consequently included in its closure.) +-- (For Lua functions, upvalues are the external local variables that the function uses, and +-- that are consequently included in its closure.) -- --- For C functions, this function uses the empty string `""` as a name for all --- upvalues. +-- For C functions, this function uses the empty string `""` as a name for all upvalues. -- --- Variable name '`?`' (interrogation mark) represents variables with no known --- names (variables from chunks saved without debug information). +-- Variable name '`?`' (interrogation mark) represents variables with no known names (variables +-- from chunks saved without debug information). function debug.getupvalue(f, up) end --- --- Returns the `n`-th user value associated to the userdata `u` plus a boolean, --- false, if the userdata does not have that value. +-- Returns the `n`-th user value associated to the userdata `u` plus a boolean, false, if the +-- userdata does not have that value. -- -- New in Lua 5.2. function debug.getuservalue(u, n) end --- --- Sets the environment of the given `object` to the given `table`. Returns --- `object`. +-- Sets the environment of the given `object` to the given `table`. Returns `object`. -- -- Deprecated in Lua 5.2. function debug.setfenv(object, table) end --- --- Sets the given function as the debug hook. The string `mask` and the number --- `count` describe when the hook will be called. The string mask may have any --- combination of the following characters, with the given meaning: --- "c": the hook is called every time Lua calls a function; --- "r": the hook is called every time Lua returns from a function; --- "l": the hook is called every time Lua enters a new line of code. +-- Sets the given function as the debug hook. The string `mask` and the number `count` describe +-- when the hook will be called. The string mask may have any combination of the following +-- characters, with the given meaning: +-- +-- * "c": the hook is called every time Lua calls a function; +-- * "r": the hook is called every time Lua returns from a function; +-- * "l": the hook is called every time Lua enters a new line of code. -- --- Moreover, with a `count` different from zero, the hook is called also after --- every `count` instructions. +-- Moreover, with a `count` different from zero, the hook is called also after every `count` +-- instructions. -- -- When called without arguments, `debug.sethook` turns off the hook. -- --- When the hook is called, its first parameter is a string describing --- the event that has triggered its call: `"call"`, `"tail call"`, `"return"`, --- `"line"`, and `"count"`. For line events, the hook also gets the new line --- number as its second parameter. Inside a hook, you can call `getinfo` with --- level 2 to get more information about the running function. (Level 0 is the --- `getinfo` function, and level 1 is the hook function.) +-- When the hook is called, its first parameter is a string describing the event that has +-- triggered its call: `"call"`, `"tail call"`, `"return"`, `"line"`, and `"count"`. For line +-- events, the hook also gets the new line number as its second parameter. Inside a hook, you +-- can call `getinfo` with level 2 to get more information about the running function. (Level +-- 0 is the `getinfo` function, and level 1 is the hook function.) function debug.sethook([thread,] hook, mask [, count]) end --- --- This function assigns the value `value` to the local variable with --- index `local` of the function at level `level` of the stack. The function --- returns nil if there is no local variable with the given index, and raises --- an error when called with a `level` out of range. (You can call `getinfo` --- to check whether the level is valid.) Otherwise, it returns the name of --- the local variable. +-- This function assigns the value `value` to the local variable with index `local` of the +-- function at level `level` of the stack. The function returns nil if there is no local variable +-- with the given index, and raises an error when called with a `level` out of range. (You can +-- call `getinfo` to check whether the level is valid.) Otherwise, it returns the name of the +-- local variable. -- -- See `debug.getlocal` for more information about variable indices and names. function debug.setlocal([thread,] level, local, value) end --- --- Sets the metatable for the given `value` to the given `table` (which --- can be nil). +-- Sets the metatable for the given `value` to the given `table` (which can be nil). function debug.setmetatable(value, table) end --- --- This function assigns the value `value` to the upvalue with index `up` --- of the function `f`. The function returns nil if there is no upvalue with the --- given index. Otherwise, it returns the name of the upvalue. +-- This function assigns the value `value` to the upvalue with index `up` of the function +-- `f`. The function returns nil if there is no upvalue with the given index. Otherwise, it +-- returns the name of the upvalue. -- -- See `debug.getupvalue` for more information about upvalues. function debug.setupvalue(f, up, value) end --- --- Sets the given `value` as the `n`-th user value associated to the given --- `udata`. `udata` must be a full userdata. +-- Sets the given `value` as the `n`-th user value associated to the given `udata`. `udata` +-- must be a full userdata. -- -- Returns `udata`, or nil if the userdata does not have that value. -- @@ -1803,29 +1649,27 @@ function debug.setupvalue(f, up, value) end function debug.setuservalue(udata, value, n) end --- --- If `message` is present but is neither a string nor nil, this function --- returns `message` without further processing. Otherwise, it returns a string --- with a traceback of the call stack. The optional `message` string is appended --- at the beginning of the traceback. An optional `level` number tells at which --- level to start the traceback (default is 1, the function calling +-- If `message` is present but is neither a string nor nil, this function returns `message` +-- without further processing. Otherwise, it returns a string with a traceback of the call +-- stack. The optional `message` string is appended at the beginning of the traceback. An optional +-- `level` number tells at which level to start the traceback (default is 1, the function calling -- `traceback`). function debug.traceback([thread,] [message] [,level]) end --- --- Returns a unique identifier (as a light userdata) for the upvalue numbered --- `n` from the given function. +-- Returns a unique identifier (as a light userdata) for the upvalue numbered `n` from the +-- given function. -- --- These unique identifiers allow a program to check whether different closures --- share upvalues. Lua closures that share an upvalue (that is, that access a --- same external local variable) will return identical ids for those upvalue --- indices. +-- These unique identifiers allow a program to check whether different closures share upvalues. Lua +-- closures that share an upvalue (that is, that access a same external local variable) will +-- return identical ids for those upvalue indices. -- -- New in Lua 5.2. function debug.upvalueid(f, n) end --- --- Make the `n1`-th upvalue of the Lua closure `f1` refer to the `n2`-th upvalue --- of the Lua closure `f2`. +-- Make the `n1`-th upvalue of the Lua closure `f1` refer to the `n2`-th upvalue of the Lua +-- closure `f2`. -- -- New in Lua 5.2. function debug.upvaluejoin(f1, n1, f2, n2) end @@ -1835,26 +1679,22 @@ function debug.upvaluejoin(f1, n1, f2, n2) end -- LPeg. --- --- The matching function. It attempts to match the given pattern against the --- subject string. If the match succeeds, returns the index in the subject of --- the first character after the match, or the captured values (if the pattern --- captured any value). +-- The matching function. It attempts to match the given pattern against the subject string. If +-- the match succeeds, returns the index in the subject of the first character after the match, +-- or the captured values (if the pattern captured any value). -- --- An optional numeric argument `init` makes the match start at that position in --- the subject string. As usual in Lua libraries, a negative value counts from --- the end. +-- An optional numeric argument `init` makes the match start at that position in the subject +-- string. As usual in Lua libraries, a negative value counts from the end. -- --- Unlike typical pattern-matching functions, match works only in anchored mode; --- that is, it tries to match the pattern with a prefix of the given subject --- string (at position `init`), not with an arbitrary substring of the subject. --- So, if we want to find a pattern anywhere in a string, we must either write a --- loop in Lua or write a pattern that matches anywhere. This second approach is --- easy and quite efficient; see examples. +-- Unlike typical pattern-matching functions, match works only in anchored mode; that is, it +-- tries to match the pattern with a prefix of the given subject string (at position `init`), +-- not with an arbitrary substring of the subject. So, if we want to find a pattern anywhere in +-- a string, we must either write a loop in Lua or write a pattern that matches anywhere. This +-- second approach is easy and quite efficient; see examples. function lpeg.match(pattern, subject [, init]) end --- --- If the given value is a pattern, returns the string "pattern". Otherwise --- returns nil. +-- If the given value is a pattern, returns the string "pattern". Otherwise returns nil. function lpeg.type(value) end --- @@ -1862,129 +1702,116 @@ function lpeg.type(value) end function lpeg.version() end --- --- Sets the maximum size for the backtrack stack used by LPeg to track calls and --- choices. Most well-written patterns need little backtrack levels and --- therefore you seldom need to change this maximum; but a few useful patterns --- may need more space. Before changing this maximum you should try to rewrite --- your pattern to avoid the need for extra space. +-- Sets the maximum size for the backtrack stack used by LPeg to track calls and choices. Most +-- well-written patterns need little backtrack levels and therefore you seldom need to change +-- this maximum; but a few useful patterns may need more space. Before changing this maximum +-- you should try to rewrite your pattern to avoid the need for extra space. function lpeg.setmaxstack(max) end --- --- Converts the given value into a proper pattern, according to the following --- rules: +-- Converts the given value into a proper pattern, according to the following rules: +-- -- * If the argument is a pattern, it is returned unmodified. --- * If the argument is a string, it is translated to a pattern that matches --- the string literally. --- * If the argument is a non-negative number n, the result is a pattern that --- matches exactly n characters. --- * If the argument is a negative number -n, the result is a pattern that --- succeeds only if the input string has less than n characters left: --- `lpeg.P(-n)` is equivalent to `-lpeg.P(n)` (see the unary minus --- operation). --- * If the argument is a boolean, the result is a pattern that always --- succeeds or always fails (according to the boolean value), without --- consuming any input. --- * If the argument is a table, it is interpreted as a grammar (see --- Grammars). --- * If the argument is a function, returns a pattern equivalent to a --- match-time capture over the empty string. +-- * If the argument is a string, it is translated to a pattern that matches the string +-- literally. +-- * If the argument is a non-negative number n, the result is a pattern that matches exactly +-- n characters. +-- * If the argument is a negative number -n, the result is a pattern that succeeds only if the +-- input string has less than n characters left: `lpeg.P(-n)` is equivalent to `-lpeg.P(n)` +-- (see the unary minus operation). +-- * If the argument is a boolean, the result is a pattern that always succeeds or always fails +-- (according to the boolean value), without consuming any input. +-- * If the argument is a table, it is interpreted as a grammar (see Grammars). +-- * If the argument is a function, returns a pattern equivalent to a match-time capture over +-- the empty string. function lpeg.P(value) end --- --- Returns a pattern that matches only if the input string at the current --- position is preceded by `patt`. Pattern `patt` must match only strings with --- some fixed length, and it cannot contain captures. +-- Returns a pattern that matches only if the input string at the current position is preceded +-- by `patt`. Pattern `patt` must match only strings with some fixed length, and it cannot +-- contain captures. -- --- Like the and predicate, this pattern never consumes any input, independently --- of success or failure. +-- Like the and predicate, this pattern never consumes any input, independently of success +-- or failure. function lpeg.B(patt) end --- --- Returns a pattern that matches any single character belonging to one of the --- given ranges. Each `range` is a string xy of length 2, representing all --- characters with code between the codes of x and y (both inclusive). +-- Returns a pattern that matches any single character belonging to one of the given ranges. Each +-- `range` is a string xy of length 2, representing all characters with code between the codes +-- of x and y (both inclusive). -- --- As an example, the pattern `lpeg.R("09")` matches any digit, and --- `lpeg.R("az", "AZ")` matches any ASCII letter. +-- As an example, the pattern `lpeg.R("09")` matches any digit, and `lpeg.R("az", "AZ")` +-- matches any ASCII letter. function lpeg.R({range}) end --- --- Returns a pattern that matches any single character that appears in the given --- string. (The S stands for Set.) +-- Returns a pattern that matches any single character that appears in the given string. (The +-- S stands for Set.) -- -- As an example, the pattern `lpeg.S("+-*/")` matches any arithmetic operator. -- --- Note that, if `s` is a character (that is, a string of length 1), then --- `lpeg.P(s)` is equivalent to `lpeg.S(s)` which is equivalent to --- `lpeg.R(s..s)`. Note also that both `lpeg.S("")` and `lpeg.R()` are patterns --- that always fail. +-- Note that, if `s` is a character (that is, a string of length 1), then `lpeg.P(s)` is equivalent +-- to `lpeg.S(s)` which is equivalent to `lpeg.R(s..s)`. Note also that both `lpeg.S("")` and +-- `lpeg.R()` are patterns that always fail. function lpeg.S(string) end --- --- This operation creates a non-terminal (a variable) for a grammar. The created --- non-terminal refers to the rule indexed by `v` in the enclosing grammar. (See --- Grammars for details.) +-- This operation creates a non-terminal (a variable) for a grammar. The created non-terminal +-- refers to the rule indexed by `v` in the enclosing grammar. (See Grammars for details.) function lpeg.V(v) end --- --- Returns a table with patterns for matching some character classes according --- to the current locale. The table has fields named `alnum`, `alpha`, `cntrl`, --- `digit`, `graph`, `lower`, `print`, `punct`, `space`, `upper`, and `xdigit`, --- each one containing a correspondent pattern. Each pattern matches any single --- character that belongs to its class. +-- Returns a table with patterns for matching some character classes according to the current +-- locale. The table has fields named `alnum`, `alpha`, `cntrl`, `digit`, `graph`, `lower`, +-- `print`, `punct`, `space`, `upper`, and `xdigit`, each one containing a correspondent +-- pattern. Each pattern matches any single character that belongs to its class. -- --- If called with an argument `table`, then it creates those fields inside the --- given table and returns that table. +-- If called with an argument `table`, then it creates those fields inside the given table and +-- returns that table. function lpeg.locale([table]) end --- --- Creates a simple capture, which captures the substring of the subject that --- matches `patt`. The captured value is a string. If `patt` has other captures, --- their values are returned after this one. +-- Creates a simple capture, which captures the substring of the subject that matches `patt`. The +-- captured value is a string. If `patt` has other captures, their values are returned after +-- this one. function lpeg.C(patt) end --- --- Creates an argument capture. This pattern matches the empty string and --- produces the value given as the nth extra argument given in the call to --- `lpeg.match`. +-- Creates an argument capture. This pattern matches the empty string and produces the value +-- given as the nth extra argument given in the call to `lpeg.match`. function lpeg.Carg(n) end --- --- Creates a back capture. This pattern matches the empty string and produces --- the values produced by the most recent group capture named `name`. +-- Creates a back capture. This pattern matches the empty string and produces the values produced +-- by the most recent group capture named `name`. -- --- Most recent means the last complete outermost group capture with the given --- name. A Complete capture means that the entire pattern corresponding to the --- capture has matched. An Outermost capture means that the capture is not --- inside another complete capture. +-- Most recent means the last complete outermost group capture with the given name. A Complete +-- capture means that the entire pattern corresponding to the capture has matched. An Outermost +-- capture means that the capture is not inside another complete capture. -- --- In the same way that LPeg does not specify when it evaluates captures, it --- does not specify whether it reuses values previously produced by the group or --- re-evaluates them. +-- In the same way that LPeg does not specify when it evaluates captures, it does not specify +-- whether it reuses values previously produced by the group or re-evaluates them. function lpeg.Cb(name) end --- --- Creates a constant capture. This pattern matches the empty string and --- produces all given values as its captured values. +-- Creates a constant capture. This pattern matches the empty string and produces all given +-- values as its captured values. function lpeg.Cc([value, ...]) end --- --- Creates a fold capture. If patt produces a list of captures C1 C2 ... Cn, --- this capture will produce the value func(...func(func(C1, C2), C3)..., Cn), --- that is, it will fold (or accumulate, or reduce) the captures from `patt` --- using function `func`. +-- Creates a fold capture. If patt produces a list of captures C1 C2 ... Cn, this capture will +-- produce the value func(...func(func(C1, C2), C3)..., Cn), that is, it will fold (or accumulate, +-- or reduce) the captures from `patt` using function `func`. -- --- This capture assumes that `patt` should produce at least one capture with at --- least one value (of any type), which becomes the initial value of an --- accumulator. (If you need a specific initial value, you may prefix a constant --- capture to `patt`.) For each subsequent capture, LPeg calls `func` with this --- accumulator as the first argument and all values produced by the capture as --- extra arguments; the first result from this call becomes the new value for --- the accumulator. The final value of the accumulator becomes the captured --- value. +-- This capture assumes that `patt` should produce at least one capture with at least one value +-- (of any type), which becomes the initial value of an accumulator. (If you need a specific +-- initial value, you may prefix a constant capture to `patt`.) For each subsequent capture, +-- LPeg calls `func` with this accumulator as the first argument and all values produced by +-- the capture as extra arguments; the first result from this call becomes the new value for +-- the accumulator. The final value of the accumulator becomes the captured value. -- --- As an example, the following pattern matches a list of numbers separated by --- commas and returns their addition: +-- As an example, the following pattern matches a list of numbers separated by commas and +-- returns their addition: -- -- -- matches a numeral and captures its numerical value -- number = lpeg.R"09"^1 / tonumber @@ -1999,84 +1826,72 @@ function lpeg.Cc([value, ...]) end function lpeg.Cf(patt, func) end --- --- Creates a group capture. It groups all values returned by `patt` into a --- single capture. The group may be anonymous (if no name is given) or named --- with the given name. +-- Creates a group capture. It groups all values returned by `patt` into a single capture. The +-- group may be anonymous (if no name is given) or named with the given name. -- --- An anonymous group serves to join values from several captures into a single --- capture. A named group has a different behavior. In most situations, a named --- group returns no values at all. Its values are only relevant for a following --- back capture or when used inside a table capture. +-- An anonymous group serves to join values from several captures into a single capture. A named +-- group has a different behavior. In most situations, a named group returns no values at all. Its +-- values are only relevant for a following back capture or when used inside a table capture. function lpeg.Cg(patt [, name]) end --- --- Creates a position capture. It matches the empty string and captures the --- position in the subject where the match occurs. The captured value is a --- number. +-- Creates a position capture. It matches the empty string and captures the position in the +-- subject where the match occurs. The captured value is a number. function lpeg.Cp() end --- --- Creates a substitution capture, which captures the substring of the subject --- that matches `patt`, with substitutions. For any capture inside `patt` with a --- value, the substring that matched the capture is replaced by the capture --- value (which should be a string). The final captured value is the string --- resulting from all replacements. +-- Creates a substitution capture, which captures the substring of the subject that matches +-- `patt`, with substitutions. For any capture inside `patt` with a value, the substring that +-- matched the capture is replaced by the capture value (which should be a string). The final +-- captured value is the string resulting from all replacements. function lpeg.Cs(patt) end --- --- Creates a table capture. This capture returns a table with all values from --- all anonymous captures made by `patt` inside this table in successive integer --- keys, starting at 1. Moreover, for each named capture group created by --- `patt`, the first value of the group is put into the table with the group --- name as its key. The captured value is only the table. +-- Creates a table capture. This capture returns a table with all values from all anonymous +-- captures made by `patt` inside this table in successive integer keys, starting at 1. Moreover, +-- for each named capture group created by `patt`, the first value of the group is put into +-- the table with the group name as its key. The captured value is only the table. function lpeg.Ct(patt) end --- --- Creates a match-time capture. Unlike all other captures, this one is --- evaluated immediately when a match occurs (even if it is part of a larger --- pattern that fails later). It forces the immediate evaluation of all its --- nested captures and then calls `function`. +-- Creates a match-time capture. Unlike all other captures, this one is evaluated immediately +-- when a match occurs (even if it is part of a larger pattern that fails later). It forces +-- the immediate evaluation of all its nested captures and then calls `function`. -- --- The given function gets as arguments the entire subject, the current position --- (after the match of `patt`), plus any capture values produced by `patt`. +-- The given function gets as arguments the entire subject, the current position (after the +-- match of `patt`), plus any capture values produced by `patt`. -- --- The first value returned by `function` defines how the match happens. If the --- call returns a number, the match succeeds and the returned number becomes the --- new current position. (Assuming a subject s and current position i, the --- returned number must be in the range [i, len(s) + 1].) If the call returns --- true, the match succeeds without consuming any input. (So, to return true is --- equivalent to return i.) If the call returns false, nil, or no value, the --- match fails. +-- The first value returned by `function` defines how the match happens. If the call returns a +-- number, the match succeeds and the returned number becomes the new current position. (Assuming +-- a subject s and current position i, the returned number must be in the range [i, len(s) + +-- 1].) If the call returns true, the match succeeds without consuming any input. (So, to return +-- true is equivalent to return i.) If the call returns false, nil, or no value, the match fails. -- --- Any extra values returned by the function become the values produced by the --- capture. +-- Any extra values returned by the function become the values produced by the capture. function lpeg.Cmt(patt, function) end -- LuaFileSystem. --- --- Returns a table with the file attributes corresponding to filepath (or nil --- followed by an error message in case of error). If the second optional --- argument is given and is a string, then only the value of the named attribute --- is returned (this use is equivalent to lfs.attributes(filepath)[aname], but --- the table is not created and only one attribute is retrieved from the O.S.). --- If a table is passed as the second argument, it is filled with attributes and --- returned instead of a new table. The attributes are described as follows; --- attribute mode is a string, all the others are numbers, and the time related --- attributes use the same time reference of os.time: --- dev: on Unix systems, this represents the device that the inode resides on. --- On Windows systems, represents the drive number of the disk containing --- the file --- ino: on Unix systems, this represents the inode number. On Windows systems --- this has no meaning --- mode: string representing the associated protection mode (the values could --- be file, directory, link, socket, named pipe, char device, block --- device or other) +-- Returns a table with the file attributes corresponding to filepath (or nil followed by +-- an error message in case of error). If the second optional argument is given and is a +-- string, then only the value of the named attribute is returned (this use is equivalent to +-- lfs.attributes(filepath)[aname], but the table is not created and only one attribute is +-- retrieved from the O.S.). If a table is passed as the second argument, it is filled with +-- attributes and returned instead of a new table. The attributes are described as follows; +-- attribute mode is a string, all the others are numbers, and the time related attributes use +-- the same time reference of os.time: +-- +-- dev: on Unix systems, this represents the device that the inode resides on. On Windows +-- systems, represents the drive number of the disk containing the file +-- ino: on Unix systems, this represents the inode number. On Windows systems this has no meaning +-- mode: string representing the associated protection mode (the values could be file, +-- directory, link, socket, named pipe, char device, block device or other) -- nlink: number of hard links to the file -- uid: user-id of owner (Unix only, always 0 on Windows) -- gid: group-id of owner (Unix only, always 0 on Windows) --- rdev: on Unix systems, represents the device type, for special file inodes. --- On Windows systems represents the same as dev +-- rdev: on Unix systems, represents the device type, for special file inodes. On Windows +-- systems represents the same as dev -- access: time of last access -- modification: time of last data modification -- change: time of last file status change @@ -2085,10 +1900,10 @@ function lpeg.Cmt(patt, function) end -- blocks: block allocated for file; (Unix only) -- blksize: optimal file system I/O blocksize; (Unix only) -- --- This function uses stat internally thus if the given filepath is a symbolic --- link, it is followed (if it points to another link the chain is followed --- recursively) and the information is about the file it refers to. To obtain --- information about the link itself, see function lfs.symlinkattributes. +-- This function uses stat internally thus if the given filepath is a symbolic link, it is +-- followed (if it points to another link the chain is followed recursively) and the information +-- is about the file it refers to. To obtain information about the link itself, see function +-- lfs.symlinkattributes. function lfs.attributes(filepath [, aname | atable]) end --- @@ -2098,93 +1913,86 @@ function lfs.attributes(filepath [, aname | atable]) end function lfs.chdir(path) end --- --- Creates a lockfile (called lockfile.lfs) in path if it does not exist and --- returns the lock. If the lock already exists checks if it's stale, using the --- second parameter (default for the second parameter is INT_MAX, which in --- practice means the lock will never be stale. To free the the lock call --- lock:free(). +-- Creates a lockfile (called lockfile.lfs) in path if it does not exist and returns the lock. If +-- the lock already exists checks if it's stale, using the second parameter (default for the +-- second parameter is INT_MAX, which in practice means the lock will never be stale. To free +-- the the lock call lock:free(). -- --- In case of any errors it returns nil and the error message. In particular, --- if the lock exists and is not stale it returns the "File exists" message. +-- In case of any errors it returns nil and the error message. In particular, if the lock exists +-- and is not stale it returns the "File exists" message. function lfs.lock_dir(path, [seconds_stale]) end --- --- Returns a string with the current working directory or nil plus an error --- string. +-- Returns a string with the current working directory or nil plus an error string. function lfs.currentdir() end --- --- Lua iterator over the entries of a given directory. Each time the iterator is --- called with dir_obj it returns a directory entry's name as a string, or nil --- if there are no more entries. You can also iterate by calling dir_obj:next(), --- and explicitly close the directory before the iteration finished with --- dir_obj:close(). Raises an error if path is not a directory. +-- Lua iterator over the entries of a given directory. Each time the iterator is called +-- with dir_obj it returns a directory entry's name as a string, or nil if there are no more +-- entries. You can also iterate by calling dir_obj:next(), and explicitly close the directory +-- before the iteration finished with dir_obj:close(). Raises an error if path is not a directory. function lfs.dir(path) end --- --- Locks a file or a part of it. This function works on open files; the file --- handle should be specified as the first argument. The string mode could be --- either r (for a read/shared lock) or w (for a write/exclusive lock). The --- optional arguments start and length can be used to specify a starting point --- and its length; both should be numbers. +-- Locks a file or a part of it. This function works on open files; the file handle should be +-- specified as the first argument. The string mode could be either r (for a read/shared lock) +-- or w (for a write/exclusive lock). The optional arguments start and length can be used to +-- specify a starting point and its length; both should be numbers. -- --- Returns true if the operation was successful; in case of error, it returns --- nil plus an error string. +-- Returns true if the operation was successful; in case of error, it returns nil plus an +-- error string. function lfs.lock(filehandle, mode[, start[, length]]) end --- --- Creates a link. The first argument is the object to link to and the second is --- the name of the link. If the optional third argument is true, the link will --- be a symbolic link (by default, a hard link is created). +-- Creates a link. The first argument is the object to link to and the second is the name of the +-- link. If the optional third argument is true, the link will be a symbolic link (by default, +-- a hard link is created). function lfs.link(old, new[, symlink]) end --- -- Creates a new directory. The argument is the name of the new directory. -- --- Returns true in case of success or nil, an error message and a --- system-dependent error code in case of error. +-- Returns true in case of success or nil, an error message and a system-dependent error code +-- in case of error. function lfs.mkdir(dirname) end --- -- Removes an existing directory. The argument is the name of the directory. -- --- Returns true in case of success or nil, an error message and a --- system-dependent error code in case of error. +-- Returns true in case of success or nil, an error message and a system-dependent error code +-- in case of error. function lfs.rmdir(dirname) end --- --- Sets the writing mode for a file. The mode string can be either "binary" or --- "text". Returns true followed by the previous mode string for the file, or --- nil followed by an error string in case of errors.. On non-Windows platforms, --- where the two modes are identical, setting the mode has no effect, and the --- mode is always returned as binary. +-- Sets the writing mode for a file. The mode string can be either "binary" or "text". Returns +-- true followed by the previous mode string for the file, or nil followed by an error string +-- in case of errors. On non-Windows platforms, where the two modes are identical, setting +-- the mode has no effect, and the mode is always returned as binary. function lfs.setmode(file, mode) end --- --- Identical to lfs.attributes except that it obtains information about the link --- itself (not the file it refers to). It also adds a target field, containing --- the file name that the symlink points to. On Windows this function does not --- yet support links, and is identical to lfs.attributes. +-- Identical to lfs.attributes except that it obtains information about the link itself (not +-- the file it refers to). It also adds a target field, containing the file name that the +-- symlink points to. On Windows this function does not yet support links, and is identical +-- to lfs.attributes. function lfs.symlinkattributes(filepath [, aname]) end --- --- Set access and modification times of a file. This function is a bind to utime --- function. The first argument is the filename, the second argument (atime) is --- the access time, and the third argument (mtime) is the modification time. --- Both times are provided in seconds (which should be generated with Lua --- standard function os.time). If the modification time is omitted, the access --- time provided is used; if both times are omitted, the current time is used. +-- Set access and modification times of a file. This function is a bind to utime function. The +-- first argument is the filename, the second argument (atime) is the access time, and the +-- third argument (mtime) is the modification time. Both times are provided in seconds (which +-- should be generated with Lua standard function os.time). If the modification time is omitted, +-- the access time provided is used; if both times are omitted, the current time is used. -- --- Returns true in case of success or nil, an error message and a --- system-dependent error code in case of error. +-- Returns true in case of success or nil, an error message and a system-dependent error code +-- in case of error. function lfs.touch(filepath [, atime [, mtime]]) end --- --- Unlocks a file or a part of it. This function works on open files; the file --- handle should be specified as the first argument. The optional arguments --- start and length can be used to specify a starting point and its length; both --- should be numbers. +-- Unlocks a file or a part of it. This function works on open files; the file handle should +-- be specified as the first argument. The optional arguments start and length can be used to +-- specify a starting point and its length; both should be numbers. -- --- Returns true if the operation was successful; in case of error, it returns --- nil plus an error string. +-- Returns true if the operation was successful; in case of error, it returns nil plus an +-- error string. function lfs.unlock(filehandle[, start[, length]]) end |