diff options
Diffstat (limited to 'modules/lua/lua.luadoc')
| -rw-r--r-- | modules/lua/lua.luadoc | 128 |
1 files changed, 74 insertions, 54 deletions
diff --git a/modules/lua/lua.luadoc b/modules/lua/lua.luadoc index a3ed8b41..374bfdb2 100644 --- a/modules/lua/lua.luadoc +++ b/modules/lua/lua.luadoc @@ -95,9 +95,11 @@ function ipairs(t) end -- otherwise, returns <b>nil</b> plus the error message. -- -- If the resulting function has upvalues, the first upvalue is set to the value --- of the global environment or to `env`, if that parameter is given. When --- loading main chunks, the first upvalue will be the `_ENV` variable --- (see §2.2). +-- of `env`, if that parameter is given, or to the value of the global +-- environment. (When you load a main chunk, the resulting function will always +-- have exactly one upvalue, the `_ENV` variable (see §2.2). When you load a +-- binary chunk created from a function (see `string.dump`), the resulting +-- function can have arbitrary upvalues.) -- -- `source` is used as the source of the chunk for error messages and debug -- information (see §4.9). When absent, it defaults to `ld`, if `ld` is a @@ -356,8 +358,8 @@ function require(modname) end -- 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 --- prototype `lua_CFunction`). +-- 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 @@ -479,7 +481,7 @@ 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 C function `sprintf`. The only +-- string follows the same rules as the ANSI C function `sprintf`. The only -- differences are that the options/modifiers `*`, `h`, `L`, `l`, `n`, and `p` -- are not supported and that there is an extra option, `q`. The `q` option -- formats a string between double quotes, using escape sequences when necessary @@ -623,7 +625,7 @@ function string.sub(s, i [, j]) end function string.upper(s) end --- --- Given a list where all elements are strings or numbers, returns +-- 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. @@ -643,11 +645,14 @@ function table.insert(list, [pos,] value) end function table.pack(···) end --- --- Removes from `list` the element at position `pos`, shifting down the elements --- `list[pos+1], list[pos+2], ···, list[#list]` and erasing element --- `list[#list]`. Returns the value of the removed element. The default value --- for `pos` is `#list`, so that a call `table.remove(t)` removes the last --- element of list `t`. +-- 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`; in those cases, the function erases the element `list[pos]`. +-- +-- The default value for `pos` is `#list`, so that a call `table.remove(t)` +-- removes the last element of list `t`. function table.remove(list [, pos]) end --- @@ -1099,13 +1104,14 @@ function os.clock() end -- 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 C function `strftime`. +-- formatted according to the same rules as the ANSI C function `strftime`. -- -- When called without arguments, `date` returns a reasonable date and time -- representation that depends on the host system and on the current locale -- (that is, `os.date()` is equivalent to `os.date("%c")`). -- --- On some systems, this function may be not thread safe. +-- 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 --- @@ -1114,7 +1120,7 @@ function os.date([format [, time]]) end function os.difftime(t2, t1) end --- --- This function is equivalent to the C function `system`. It passes +-- This function is equivalent to the ANSI 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 and a number, as follows: @@ -1128,7 +1134,7 @@ function os.difftime(t2, t1) end function os.execute([command]) end --- --- Calls the C function `exit` to terminate the host program. If `code` is +-- Calls the ANSI 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`. @@ -1166,6 +1172,9 @@ function os.rename(oldname, newname) end -- -- 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`. function os.setlocale(locale [, category]) end --- @@ -1246,7 +1255,7 @@ function debug.getinfo([thread,] f [, what]) end -- 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 parentheses) represent internal +-- Variable names starting with '`(`' (open parenthesis) represent internal -- variables (loop control variables, temporaries, varargs, and C function -- locals). -- @@ -1358,13 +1367,13 @@ function debug.upvaluejoin(f1, n1, f2, n2) end -- the first character after the match, or the captured values (if the pattern -- captured any value). -- --- An optional numeric argument init makes the match starts at that position in +-- 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. +-- 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. @@ -1392,12 +1401,13 @@ function lpeg.setmaxstack(max) end -- 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 --- literally the string. +-- 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 does not have n characters: lpeg.P(-n) --- is equivalent to -lpeg.P(n) (see the unary minus operation). +-- 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. @@ -1408,57 +1418,67 @@ function lpeg.setmaxstack(max) end 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. +-- +-- 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 +-- 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.) -- --- As an example, the pattern lpeg.S("+-*/") matches any arithmetic operator. +-- 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 +-- 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. +-- 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 +-- 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, +-- 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. +-- `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. +-- 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 @@ -1474,24 +1494,24 @@ 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. +-- 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 +-- 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 +-- 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 value returned by this call becomes the new value for +-- 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: -- --- -- matches a numeral and captures its value +-- -- matches a numeral and captures its numerical value -- number = lpeg.R"09"^1 / tonumber --- -- matches a list of numbers, captures their values +-- -- matches a list of numbers, capturing their values -- list = number * ("," * number)^0 -- -- auxiliary function to add two numbers -- function add (acc, newvalue) return acc + newvalue end @@ -1502,9 +1522,9 @@ 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 @@ -1520,7 +1540,7 @@ 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 +-- 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. @@ -1528,21 +1548,21 @@ function lpeg.Cs(patt) end --- -- Creates a table capture. This capture creates a table and puts all values --- from all anonymous captures made by patt inside this table in successive +-- 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 +-- 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. It forces the immediate evaluation --- of all its nested captures and then calls function. +-- 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. +-- (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 +-- 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 |