diff --git a/ldoc/builtin/debug.lua b/ldoc/builtin/debug.lua index 981a638..b59926f 100644 --- a/ldoc/builtin/debug.lua +++ b/ldoc/builtin/debug.lua @@ -1,124 +1,124 @@ ---- getting runtime debug information. --- @module debug - -local debug = {} ---- --- 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. -function debug.debug() end - ---- --- Returns the environment of object `o`. -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). -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 `function`, --- which means the function running at level `function` of the call stack --- of the given thread: level 0 is the current function (`getinfo` itself); --- level 1 is the function that called `getinfo`; and so on. If `function` --- is a number larger than the number of active functions, then `getinfo` --- returns nil. --- --- `thread` and `what` are optional. --- --- 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, function , what) end - ---- --- This function returns the name and the value of the local variable with --- index `local` of the function at level `level` of the stack. (The first --- parameter or local variable has index 1, and so on, until the last active --- local variable.) 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 `debug.getinfo` to check whether the level is valid.) --- Variable names starting with '`(`' (open parentheses) represent internal --- variables (loop control variables, temporaries, and C function locals). -function debug.getlocal(thread, level, local) end - ---- --- Returns the metatable of the given `object` or nil if it does not have --- a metatable. -function debug.getmetatable(object) end - ---- --- Returns the registry table (see §3.5). -function debug.getregistry() end - ---- --- This function returns the name and the value of the upvalue with index --- `up` of the function `func`. The function returns nil if there is no --- upvalue with the given index. -function debug.getupvalue(func, up) end - ---- --- Sets the environment of the given `object` to the given `table`. Returns --- `object`. -function debug.setfenv(object, table) end - ---- --- Sets the given function as a hook. The string `mask` and the number --- `count` describe when the hook will be called. The string mask may have --- 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. --- --- With a `count` different from zero, the hook is called 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"`, `"return"` (or `"tail --- return"`, when simulating a return from a tail call), `"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), unless the event is `"tail --- return"`. In this case, Lua is only simulating the return, and a call to --- `getinfo` will return invalid data. -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. -function debug.setlocal(thread, level, local, value) end - ---- --- Sets the metatable for the given `object` to the given `table` (which --- can be nil). -function debug.setmetatable(object, table) end - ---- --- This function assigns the value `value` to the upvalue with index `up` --- of the function `func`. The function returns nil if there is no upvalue --- with the given index. Otherwise, it returns the name of the upvalue. -function debug.setupvalue(func, up, value) end - -return debug +--- getting runtime debug information. +-- @module debug + +local debug = {} +--- +-- 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. +function debug.debug() end + +--- +-- Returns the environment of object `o`. +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). +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 `function`, +-- which means the function running at level `function` of the call stack +-- of the given thread: level 0 is the current function (`getinfo` itself); +-- level 1 is the function that called `getinfo`; and so on. If `function` +-- is a number larger than the number of active functions, then `getinfo` +-- returns nil. +-- +-- `thread` and `what` are optional. +-- +-- 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, function , what) end + +--- +-- This function returns the name and the value of the local variable with +-- index `local` of the function at level `level` of the stack. (The first +-- parameter or local variable has index 1, and so on, until the last active +-- local variable.) 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 `debug.getinfo` to check whether the level is valid.) +-- Variable names starting with '`(`' (open parentheses) represent internal +-- variables (loop control variables, temporaries, and C function locals). +function debug.getlocal(thread, level, local) end + +--- +-- Returns the metatable of the given `object` or nil if it does not have +-- a metatable. +function debug.getmetatable(object) end + +--- +-- Returns the registry table (see §3.5). +function debug.getregistry() end + +--- +-- This function returns the name and the value of the upvalue with index +-- `up` of the function `func`. The function returns nil if there is no +-- upvalue with the given index. +function debug.getupvalue(func, up) end + +--- +-- Sets the environment of the given `object` to the given `table`. Returns +-- `object`. +function debug.setfenv(object, table) end + +--- +-- Sets the given function as a hook. The string `mask` and the number +-- `count` describe when the hook will be called. The string mask may have +-- 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. +-- +-- With a `count` different from zero, the hook is called 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"`, `"return"` (or `"tail +-- return"`, when simulating a return from a tail call), `"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), unless the event is `"tail +-- return"`. In this case, Lua is only simulating the return, and a call to +-- `getinfo` will return invalid data. +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. +function debug.setlocal(thread, level, local, value) end + +--- +-- Sets the metatable for the given `object` to the given `table` (which +-- can be nil). +function debug.setmetatable(object, table) end + +--- +-- This function assigns the value `value` to the upvalue with index `up` +-- of the function `func`. The function returns nil if there is no upvalue +-- with the given index. Otherwise, it returns the name of the upvalue. +function debug.setupvalue(func, up, value) end + +return debug diff --git a/ldoc/builtin/global.lua b/ldoc/builtin/global.lua index c9aabe5..1234835 100644 --- a/ldoc/builtin/global.lua +++ b/ldoc/builtin/global.lua @@ -69,17 +69,17 @@ function getmetatable(object) end function ipairs(t) end --- --- Loads a chunk. +-- Loads a chunk. -- If `ld` is a string, the chunk is this string. -- If `ld` is a function, load calls it repeatedly to get the chunk pieces. Each call to `ld` must return a -- string that concatenates with previous results. A return of an empty string, nil, or no value --- signals the end of the chunk. +-- signals the end of the chunk. -- If there are no syntactic errors, returns the compiled chunk as a function; --- otherwise, returns nil plus the error message. +-- otherwise, returns nil 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). +-- if that parameter is given. When loading main chunks, the first upvalue will be the`_ENV` variable (see 2.2). -- `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 string, or to "=(load)" otherwise. +-- When absent, it defaults to `ld`, if `ld` is a string, or to "=(load)" otherwise. -- The string `mode` controls whether the chunk can be text or binary (that is, a precompiled chunk). -- It may be the string "b" (only binary chunks), "t" (only text chunks), or "bt" (both binary and text). -- The default is "bt" diff --git a/ldoc/builtin/io.lua b/ldoc/builtin/io.lua index 28253df..44a827a 100644 --- a/ldoc/builtin/io.lua +++ b/ldoc/builtin/io.lua @@ -1,159 +1,159 @@ ---- Reading and Writing Files. --- @module io - -local io = {} - ---- --- Equivalent to `file:close()`. Without a `file`, closes the default --- output file. -function io.close(file) end - ---- --- Equivalent to `file:flush` over the default output file. -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. --- 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, each time it is called, returns a new line from the file. Therefore, --- the construction --- for line in io.lines(filename) do *body* end --- will iterate over all lines of the file. When the iterator function detects --- the end of file, it returns nil (to finish the loop) and automatically --- closes the file. --- The call `io.lines()` (with no file name) is equivalent to --- `io.input():lines()`; 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. -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. --- 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. This string is exactly what --- is used in the standard C function `fopen`. -function io.open(filename , mode) end - ---- --- Similar to `io.input`, but operates over the default output file. -function io.output(file) end - ---- --- Starts 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 - ---- --- Equivalent to `io.input():read`. -function io.read(...) end - --- * `io.stderr`: Standard error. --- * `io.stdin`: Standard in. --- * `io.stdout`: Standard out. - ---- --- 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. -function io.type(obj) end - ---- --- Equivalent to `io.output():write`. -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. -function file:close() end - ---- --- Saves any written data to `file`. -function file:flush() end - ---- --- Returns an iterator function that, each time it is called, returns a --- new line from the file. Therefore, the construction --- for line in file:lines() do *body* end --- will iterate over all lines of the file. (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. When called without formats, it uses a default format that reads --- the entire next line (see below). --- The available formats are --- "*n": reads a number; this is the only format that returns a number --- instead of a string. --- "*a": reads the whole file, starting at the current position. On end of --- file, it returns the empty string. --- "*l": reads the next line (skipping the end of line), returning nil on --- end of file. This is the default format. --- *number*: reads a string with up to this number of characters, returning --- nil on end of file. If number is zero, it reads nothing and returns an --- empty string, or nil on end of file. -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; --- In case of success, function `seek` returns the final file position, --- measured in bytes from the beginning of the file. If this function 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 an output file. There are three available --- modes: --- --- * "no": no buffering; the result of any output operation appears immediately. --- * "full": full buffering; output operation is performed only when the --- buffer is full (or when you explicitly `flush` the file (see `io.flush`)). --- * "line": line buffering; output is buffered until a newline is output or --- there is any input from some special files (such as a terminal device). --- For the last two cases, `size` specifies the size of the buffer, in --- bytes. The default is an appropriate size. -function file:setvbuf(mode , size) end - ---- --- Writes the value of each of its arguments to the `file`. The arguments --- must be strings or numbers. To write other values, use `tostring` or --- `string.format` before `write`. -function file:write(...) end - -return io +--- Reading and Writing Files. +-- @module io + +local io = {} + +--- +-- Equivalent to `file:close()`. Without a `file`, closes the default +-- output file. +function io.close(file) end + +--- +-- Equivalent to `file:flush` over the default output file. +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. +-- 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, each time it is called, returns a new line from the file. Therefore, +-- the construction +-- for line in io.lines(filename) do *body* end +-- will iterate over all lines of the file. When the iterator function detects +-- the end of file, it returns nil (to finish the loop) and automatically +-- closes the file. +-- The call `io.lines()` (with no file name) is equivalent to +-- `io.input():lines()`; 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. +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. +-- 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. This string is exactly what +-- is used in the standard C function `fopen`. +function io.open(filename , mode) end + +--- +-- Similar to `io.input`, but operates over the default output file. +function io.output(file) end + +--- +-- Starts 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 + +--- +-- Equivalent to `io.input():read`. +function io.read(...) end + +-- * `io.stderr`: Standard error. +-- * `io.stdin`: Standard in. +-- * `io.stdout`: Standard out. + +--- +-- 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. +function io.type(obj) end + +--- +-- Equivalent to `io.output():write`. +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. +function file:close() end + +--- +-- Saves any written data to `file`. +function file:flush() end + +--- +-- Returns an iterator function that, each time it is called, returns a +-- new line from the file. Therefore, the construction +-- for line in file:lines() do *body* end +-- will iterate over all lines of the file. (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. When called without formats, it uses a default format that reads +-- the entire next line (see below). +-- The available formats are +-- "*n": reads a number; this is the only format that returns a number +-- instead of a string. +-- "*a": reads the whole file, starting at the current position. On end of +-- file, it returns the empty string. +-- "*l": reads the next line (skipping the end of line), returning nil on +-- end of file. This is the default format. +-- *number*: reads a string with up to this number of characters, returning +-- nil on end of file. If number is zero, it reads nothing and returns an +-- empty string, or nil on end of file. +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; +-- In case of success, function `seek` returns the final file position, +-- measured in bytes from the beginning of the file. If this function 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 an output file. There are three available +-- modes: +-- +-- * "no": no buffering; the result of any output operation appears immediately. +-- * "full": full buffering; output operation is performed only when the +-- buffer is full (or when you explicitly `flush` the file (see `io.flush`)). +-- * "line": line buffering; output is buffered until a newline is output or +-- there is any input from some special files (such as a terminal device). +-- For the last two cases, `size` specifies the size of the buffer, in +-- bytes. The default is an appropriate size. +function file:setvbuf(mode , size) end + +--- +-- Writes the value of each of its arguments to the `file`. The arguments +-- must be strings or numbers. To write other values, use `tostring` or +-- `string.format` before `write`. +function file:write(...) end + +return io diff --git a/ldoc/builtin/string.lua b/ldoc/builtin/string.lua index 73b4cc4..c80c210 100644 --- a/ldoc/builtin/string.lua +++ b/ldoc/builtin/string.lua @@ -1,191 +1,191 @@ ---- string operations like searching and matching. --- @module string - -local string = {} - ---- --- 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`. --- Note that 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. --- Note that numerical codes are not necessarily portable across platforms. -function string.char(...) end - ---- --- Returns a string containing a binary representation of the given --- function, so that a later `loadstring` on this string returns a copy of --- the function. `function` must be a Lua function without upvalues. -function string.dump(function) end - ---- --- Looks for the first match of `pattern` 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". Note that if `plain` is given, then `init` must be given as well. --- 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 `printf` family of standard C --- functions. The only differences are that the options/modifiers `*`, `l`, --- `L`, `n`, `p`, and `h` are not supported and that there is an extra option, --- `q`. The `q` option formats a string in a form suitable to be safely read --- back by the Lua interpreter: the string is written between double quotes, --- and all double quotes, newlines, embedded zeros, and backslashes in the --- string are correctly escaped when written. For instance, the call --- --- string.format('%q', 'a string with "quotes" and \n new line') --- --- will produce the string: --- --- "a string with \"quotes\" and \ --- new line" --- --- The options `c`, `d`, `E`, `e`, `f`, `g`, `G`, `i`, `o`, `u`, `X`, and --- `x` all expect a number as argument, whereas `q` and `s` expect a string. --- This function does not accept string values containing embedded zeros, --- except as arguments to the `q` option. -function string.format(formatstring, ...) end - ---- --- Returns an iterator function that, each time it is called, returns the --- next captures from `pattern` over string `s`. If `pattern` specifies no --- captures, then the whole match is produced in each call. --- As an example, the following loop --- --- s = "hello world from Lua" --- for w in string.gmatch(s, "%a+") do --- print(w) --- end --- --- will iterate over all the words from string `s`, printing one per line. 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 --- --- For this function, a '`^`' at the start of a pattern does not work as an --- anchor, as this would prevent the iteration. -function string.gmatch(s, pattern) end - ---- --- Returns a copy of `s` in which all (or the first `n`, if given) --- occurrences of the `pattern` 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. --- --- 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 `%n`, --- with *n* between 1 and 9, stands for the value of the *n*-th captured --- substring (see below). 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 the pattern specifies no captures, then --- the whole match is used 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 --- the pattern specifies no captures, then the whole match is passed as a --- sole argument. --- --- 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("4+5 = $return 4+5$", "%$(.-)%$", function (s) --- return loadstring(s)() --- end) --- --> x="4+5 = 9" --- local t = {name="lua", version="5.1"} --- x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) --- --> x="lua-5.1.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. -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. -function string.lower(s) end - ---- --- Looks for the first *match* of `pattern` 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 string that is the concatenation of `n` copies of the string --- `s`. -function string.rep(s, n) end - ---- --- Returns a string that is the string `s` reversed. -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`. -function string.sub(s, i , j) 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. -function string.upper(s) end - ---- --- (5.3) Returns a binary string containing the values v1, v2, etc. packed (that is, serialized in binary form) ---- according to the format string fmt (see 6.4.2). -function string.pack (fmt, v1, v2, ···) end - ---- --- (5.3) 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). -function string.packsize (fmt) end - ---- --- (5.3) 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. -function string.unpack (fmt, s [, pos]) end - -return string - +--- string operations like searching and matching. +-- @module string + +local string = {} + +--- +-- 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`. +-- Note that 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. +-- Note that numerical codes are not necessarily portable across platforms. +function string.char(...) end + +--- +-- Returns a string containing a binary representation of the given +-- function, so that a later `loadstring` on this string returns a copy of +-- the function. `function` must be a Lua function without upvalues. +function string.dump(function) end + +--- +-- Looks for the first match of `pattern` 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". Note that if `plain` is given, then `init` must be given as well. +-- 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 `printf` family of standard C +-- functions. The only differences are that the options/modifiers `*`, `l`, +-- `L`, `n`, `p`, and `h` are not supported and that there is an extra option, +-- `q`. The `q` option formats a string in a form suitable to be safely read +-- back by the Lua interpreter: the string is written between double quotes, +-- and all double quotes, newlines, embedded zeros, and backslashes in the +-- string are correctly escaped when written. For instance, the call +-- +-- string.format('%q', 'a string with "quotes" and \n new line') +-- +-- will produce the string: +-- +-- "a string with \"quotes\" and \ +-- new line" +-- +-- The options `c`, `d`, `E`, `e`, `f`, `g`, `G`, `i`, `o`, `u`, `X`, and +-- `x` all expect a number as argument, whereas `q` and `s` expect a string. +-- This function does not accept string values containing embedded zeros, +-- except as arguments to the `q` option. +function string.format(formatstring, ...) end + +--- +-- Returns an iterator function that, each time it is called, returns the +-- next captures from `pattern` over string `s`. If `pattern` specifies no +-- captures, then the whole match is produced in each call. +-- As an example, the following loop +-- +-- s = "hello world from Lua" +-- for w in string.gmatch(s, "%a+") do +-- print(w) +-- end +-- +-- will iterate over all the words from string `s`, printing one per line. 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 +-- +-- For this function, a '`^`' at the start of a pattern does not work as an +-- anchor, as this would prevent the iteration. +function string.gmatch(s, pattern) end + +--- +-- Returns a copy of `s` in which all (or the first `n`, if given) +-- occurrences of the `pattern` 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. +-- +-- 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 `%n`, +-- with *n* between 1 and 9, stands for the value of the *n*-th captured +-- substring (see below). 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 the pattern specifies no captures, then +-- the whole match is used 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 +-- the pattern specifies no captures, then the whole match is passed as a +-- sole argument. +-- +-- 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("4+5 = $return 4+5$", "%$(.-)%$", function (s) +-- return loadstring(s)() +-- end) +-- --> x="4+5 = 9" +-- local t = {name="lua", version="5.1"} +-- x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) +-- --> x="lua-5.1.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. +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. +function string.lower(s) end + +--- +-- Looks for the first *match* of `pattern` 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 string that is the concatenation of `n` copies of the string +-- `s`. +function string.rep(s, n) end + +--- +-- Returns a string that is the string `s` reversed. +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`. +function string.sub(s, i , j) 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. +function string.upper(s) end + +--- +-- (5.3) Returns a binary string containing the values v1, v2, etc. packed (that is, serialized in binary form) +--- according to the format string fmt (see 6.4.2). +function string.pack (fmt, v1, v2, ···) end + +--- +-- (5.3) 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). +function string.packsize (fmt) end + +--- +-- (5.3) 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. +function string.unpack (fmt, s [, pos]) end + +return string + diff --git a/ldoc/builtin/table.lua b/ldoc/builtin/table.lua index fb88fdf..94852e5 100644 --- a/ldoc/builtin/table.lua +++ b/ldoc/builtin/table.lua @@ -1,44 +1,44 @@ ---- manipulating Lua tables. --- @module table - -local table = {} - ---- --- Given an array where all elements are strings or numbers, returns --- `table[i]..sep..table[i+1] ... sep..table[j]`. The default value for --- `sep` is the empty string, the default for `i` is 1, and the default for --- `j` is the length of the table. If `i` is greater than `j`, returns the --- empty string. -function table.concat(table , sep , i , j) end - ---- --- Inserts element `value` at position `pos` in `table`, shifting up --- other elements to open space, if necessary. The default value for `pos` is --- `n+1`, where `n` is the length of the table (see §2.5.5), so that a call --- `table.insert(t,x)` inserts `x` at the end of table `t`. -function table.insert(table, pos, value) end - ---- --- Removes from `table` the element at position `pos`, shifting down other --- elements to close the space, if necessary. Returns the value of the removed --- element. The default value for `pos` is `n`, where `n` is the length of the --- table, so that a call `table.remove(t)` removes the last element of table --- `t`. -function table.remove(table , pos) 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. -function table.pack (···) end ---- --- Sorts table elements in a given order, --- *in-place*, from `table[1]` to `table[n]`, where `n` is the length of the --- table. If `comp` is given, then it must be a function that receives two --- table elements, and returns true when the first is less than the second --- (so that `not comp(a[i+1],a[i])` will be true after the sort). If `comp` --- is not given, then the '<' operator will be used. -function table.sort(table , comp) end - +--- manipulating Lua tables. +-- @module table + +local table = {} + +--- +-- Given an array where all elements are strings or numbers, returns +-- `table[i]..sep..table[i+1] ... sep..table[j]`. The default value for +-- `sep` is the empty string, the default for `i` is 1, and the default for +-- `j` is the length of the table. If `i` is greater than `j`, returns the +-- empty string. +function table.concat(table , sep , i , j) end + +--- +-- Inserts element `value` at position `pos` in `table`, shifting up +-- other elements to open space, if necessary. The default value for `pos` is +-- `n+1`, where `n` is the length of the table (see §2.5.5), so that a call +-- `table.insert(t,x)` inserts `x` at the end of table `t`. +function table.insert(table, pos, value) end + +--- +-- Removes from `table` the element at position `pos`, shifting down other +-- elements to close the space, if necessary. Returns the value of the removed +-- element. The default value for `pos` is `n`, where `n` is the length of the +-- table, so that a call `table.remove(t)` removes the last element of table +-- `t`. +function table.remove(table , pos) 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. +function table.pack (···) end +--- +-- Sorts table elements in a given order, +-- *in-place*, from `table[1]` to `table[n]`, where `n` is the length of the +-- table. If `comp` is given, then it must be a function that receives two +-- table elements, and returns true when the first is less than the second +-- (so that `not comp(a[i+1],a[i])` will be true after the sort). If `comp` +-- is not given, then the '<' operator will be used. +function table.sort(table , comp) end + --- -- Returns the elements from the given table. This function is equivalent to -- return list[i], list[i+1], ..., list[j] @@ -46,5 +46,5 @@ function table.sort(table , comp) end -- elements. By default, `i` is 1 and `j` is the length of the list, as -- defined by the length operator (see §2.5.5). function unpack(list , i , j) end - -return table + +return table diff --git a/ldoc/builtin/utf8.lua b/ldoc/builtin/utf8.lua index a96f3c6..c3af02e 100644 --- a/ldoc/builtin/utf8.lua +++ b/ldoc/builtin/utf8.lua @@ -1,48 +1,46 @@ ---- This library provides basic support for UTF-8 encoding. --- @module utf8 - -local utf8 = {} +--- This library provides basic support for UTF-8 encoding. +-- @module utf8 + +local utf8 = {} --- -- 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. -function utf8.char (...) end +function utf8.char (...) end --- -- The pattern "[\0-\x7F\xC2-\xF4][\x80-\xBF]*" , which matches exactly one -- UTF-8 byte sequence, assuming that the subject is a valid UTF-8 string. --- @field charpattern +-- @field charpattern --- --- Iterate over all characters in string. --- +-- Iterate over all characters in string. +-- -- for p, c in utf8.codes(s) do body end --- +-- -- will iterate over all 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. -function utf8.codes (s) 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. -function utf8.codepoint (s [, i [, j]]) end +-- of each character. It raises an error if it meets any invalid byte sequence. +function utf8.codes (s) end --- --- Returns the number of UTF-8 characters in string s that start between positions i and j (both inclusive). +-- 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. +function utf8.codepoint (s [, i [, j]]) 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 a false value plus --- the position of the first invalid byte. -function utf8.len (s [, i [, j]]) end +-- the position of the first invalid byte. +function utf8.len (s [, i [, j]]) 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 +-- 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. --- --- This function assumes that s is a valid UTF-8 string. -function utf8.offset (s, n [, i]) end - - +-- +-- 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. +function utf8.offset (s, n [, i]) end diff --git a/run-tests.lua b/run-tests.lua index 6d10a7d..26e4f64 100644 --- a/run-tests.lua +++ b/run-tests.lua @@ -1,18 +1,18 @@ -local run -if not arg[1] then - run = function (dir) - local cmd = 'cd '..dir..' && ldoc --testing . && diff -r doc cdocs' - print(cmd) - os.execute(cmd) - end -elseif arg[1] == 'update' then - run = function (dir) - local cmd = 'cd '..dir..' && ldoc --dir cdocs --testing .' - print(cmd) - os.execute(cmd) - end -end - -for _,d in ipairs{'tests','tests/example','tests/md-test'} do - run(d) -end +local run +if not arg[1] then + run = function (dir) + local cmd = 'cd '..dir..' && ldoc --testing . && diff -r doc cdocs' + print(cmd) + os.execute(cmd) + end +elseif arg[1] == 'update' then + run = function (dir) + local cmd = 'cd '..dir..' && ldoc --dir cdocs --testing .' + print(cmd) + os.execute(cmd) + end +end + +for _,d in ipairs{'tests','tests/example','tests/md-test'} do + run(d) +end