plugins/org.eclipse.ldt.support.lua52/src-ee/lua-5.2/api/debug.doclua

-------------------------------------------------------------------------------
-- The Debug Library.
-- This library provides the functionality of the debug interface to Lua programs.
-- You should exert care when using this library. Several of its functions violate
-- basic assumptions about Lua code (e.g., that variables local to a function
-- cannot be accessed from outside; that userdata metatables cannot be changed
-- by Lua code; that Lua programs do not crash) and therefore can compromise
-- otherwise secure code. Moreover, some functions in this library may be slow.
--  
-- All functions in this library are provided inside the `debug` table.
-- All functions that operate over a thread have an optional first argument
-- which is the thread to operate over. The default is always the current thread. 
-- @module 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 [parent=#debug] debug

-------------------------------------------------------------------------------
-- 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 [parent=#debug] gethook
-- @param #thread thread thread to handle (optional).

-------------------------------------------------------------------------------
-- Returns a table with information about a function. You can give the
-- function directly, or you can give a number as the value of `func`,
-- which means the function running at level `func` 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**.
-- 
-- 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 [parent=#debug] getinfo
-- @param #thread thread thread to handle (optional).
-- @param func the function or a number which means the function running at level `func`.
-- @param #string what used to precise information returned (optional).
-- @return #table with information about the function `func`.

-------------------------------------------------------------------------------
-- 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
-- xplicit local variables, but also parameters, temporaries, etc.
-- 
-- The first parameter or local variable has index `1`, and so on, until the last
-- active variable. 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 internal
-- variables (loop control variables, temporaries, varargs, and C function locals).
-- 
-- The parameter `f` may also be a function. In that case, getlocal returns
-- only the name of function parameters. 
-- @function [parent=#debug] getlocal
-- @param #thread thread thread which owns the local variable (optional).
-- @param f the stack level or a function
-- @param #number local the index of the local variable.
-- @return #string The name and the value of the local variable with
-- index `local` of the function at level `level` of the stack.
-- @return #nil if no variable was found

-------------------------------------------------------------------------------
-- Returns the metatable of the given `value` or **nil** if it does not have
-- a metatable.
-- @function [parent=#debug] getmetatable
-- @param value value to handle.
-- @return #table the metatable of the given `object` or nil if it does not have
-- a metatable.

-------------------------------------------------------------------------------
-- Returns the registry table.
-- @function [parent=#debug] getregistry
-- @return #table The registry table

-------------------------------------------------------------------------------
-- 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.
-- @function [parent=#debug] getupvalue
-- @param f function which owns the upvalue.
-- @param #number up index of upvalue.
-- @return The name and the value of the upvalue of the function `f`.
-- @return #nil no upvalue found.

-------------------------------------------------------------------------------
-- Returns the Lua value associated to `u`. If `u` is not a userdata, returns **nil**. 
-- @function [parent=#debug] getuservalue
-- @param #userdata u userdata
-- @return the value of the userdata
-- @return #nil no userdata found

-------------------------------------------------------------------------------
-- 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).
-- @function [parent=#debug] sethook
-- @param #thread thread thread on which the hook is set (optional).
-- @param hook a function which takes two argument : event as string and line number. 
-- @param #string mask could be `"c"`, `"r"` or `"l"`.
-- @param #number count the hook is called after every `count` instructions (optional).

-------------------------------------------------------------------------------
-- 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 [parent=#debug] setlocal
-- @param #thread thread thread which owns the local variable (optional). 
-- @param #number level the stack level.
-- @param #number local the index of the local variable.
-- @param value the new value.
-- @return #string the name of the variable if it succeed.
-- @return #nil no local variable with the given index.

-------------------------------------------------------------------------------
-- Sets the metatable for the given `value` to the given `table` (which
-- can be **nil**). Returns `value`. 
-- @function [parent=#debug] setmetatable
-- @param value value to handle.
-- @param #table table the metatable for `object`.
-- @return the given value 

-------------------------------------------------------------------------------
-- 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.
-- @function [parent=#debug] setupvalue
-- @param func function which owns the upvalue.
-- @param #number up index of the upvalue.
-- @param value the new value.
-- @return #string the name of the upvalue if it succeed.
-- @return #nil if there no upvalue with the given index.

-------------------------------------------------------------------------------
-- 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. An 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 [parent=#debug] traceback
-- @param #thread thread thread which owns the local variable (optional). 
-- @param #string message  original message (optional).
-- @param #number level (1 by default, optional).
-- @return #string message with additional traceback informations.

 
-------------------------------------------------------------------------------
--  Returns an unique identifier (as a light userdata) for the upvalue `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. 
-- @function [parent=#debug] upvalueid
-- @param f function which owns the upvalue.
-- @param #number n index of the upvalue.
-- @return #userdata id of the upvalue 


-------------------------------------------------------------------------------
-- Make the `n1`-th upvalue of the Lua closure `f1` refer to the `n2`-th upvalue of the Lua closure `f2`. 
-- @function [parent=#debug] upvaluejoin
-- @param f1 function.
-- @param #number n1 upvalue index in the function.
-- @param f2 targeted function.
-- @param #number n2  upvalue index in the targeted function.

return nil