Lua debug functions
Lua debug functions These are the functions in the "debug" table. The debug functions are not optimized for speed, they are designed to help debug your programs. debug.debug () Enters interactive debugging. MUSHclient has an interactive debug dialog box which lets you inspect local variables and upvalues, do a traceback, enter debugging commands, and then continue or abort the script.
    debug.debug () -- enter debugger
debug.getfenv (o) Returns the environment of object o. This differs a bit from the base function getfenv, which takes a function or a level number, and converts the level number into a function. The debug version simply returns the environment of the argument, which is only meaningful for objects of type function, userdata or thread. debug.gethook (thread) Returns the current hook settings as three values: Hook function Mask Count See debug.sethook for more details. The thread argument is optional and defaults to the current thread.
    f, mask, count = debug.gethook ()
    print (f) --> nil
    print (mask) --> ""
    print (count) --> 0
debug.getinfo (thread, f, what) Returns a table with information about a function. The optional field "what" is a string indicating which values to return (can be more than one). If omitted, all is returned. The thread argument is optional and defaults to the current thread. What fields can be one or more of the following concatenated together: f - returns "func" field l - returns "currentline" field L - returns a table whose indices are the numbers of the lines that are valid on the function. (A valid line is a line with some associated code, that is, a line where you can put a break point. Non-valid lines include empty lines and comments.) n - returns "name" and "namewhat" fields S - returns "source", "short_src", "linedefined" and "what" fields u - returns "nups" field The function name can be an integer representing the stack level, where 0 is debug.getinfo itself, 1 is the function that called debug.getinfo, 2 is the function that called that, and so on. Returns nil if the function number is larger than the number of functions on the stack. Field meanings of the returned table are: source - where the function was defined. If in a file, it is the file name prefixed by "@". If the function was defined in a string (through loadstring) then "source" is this string. If the function was defined interactively (through the lua.exe program) then source will be "stdin". If the function was defined in a C program, then source will be "[C]". short_src - a shorter version of "source" (up to 60 characters), useful for error messages linedefined - the first line number, in the source, where this function was defined (for Lua functions). lastlinedefined - the last line number, in the source, where this function was defined (for Lua functions). what - what this function is. Can be "Lua" for a regular Lua function, "C" if it is a C function, or "main" if it is part of the main Lua chunk (ie. outside any function). name - an attempt to find the name of the function - may be nil. Since functions can have many names (by assigning a function to many variables) or no name, the name cannot always be determined. Lua tries to find the name of the function by inspecting the call stack to find how the function was called. This can only work if debug.getinfo was called with a stack level number, not a function itself. namewhat - what the "name" field means. It can be "global", "local", "method", "field", or the empty string (""). The empty string means Lua did not find the name, and thus the name field will not be present. nups - the number of upvalues that this function has. activelines - a table of the active lines of the function, that is ones which have code on them, as opposed to blank lines or comments. Each entry in table contains the line number as a key, and true as the value. currentline - the line that is currently active (only applies to active functions, that is if the call to debug.getinfo is for a stack level). func - the function that is active at that stack level (if called with a stack level).
    t = debug.getinfo (table.sort)
    table.foreach (t, print)

     -->

    source =[C]
    what C
    func function: 02061360
    short_src [C]
    currentline -1
    namewhat
    linedefined -1
    nups 0

    -- another example, this time a user-defined function --

    function f (a, b, c) print "hi" end
    t = debug.getinfo (f, "flnSu")  --> 'what' options explicitly mentioned
    table.foreach (t, print)

     -->

    source  =stdin
    what    Lua
    func    function: 0x8079a40
    name    f
    nups    0
    currentline     -1
    namewhat        global
    linedefined     1
    short_src       stdin

    -- this example prints the name of the currently-running function --

    function myfunc () print (debug.getinfo (1, "n").name) end
    myfunc ()  --> myfunc

    -- this example shows the active lines:

    function f (a, b, c)
    print "hi"
    a = b + c
    end
    t = debug.getinfo (f, "L")
    table.foreach (t.activelines, print)

     -->

    2	true
    3	true
    4	true
debug.getlocal (level, local) Returns the name and value of the local variable with the index 'local' of the function at 'level' on the stack. See also debug.setlocal .
    function f (a, b)
    local c = 11
    local i = 1

    repeat
      name, val = debug.getlocal (1, i)
      if name then
        print ("index", i, name, "=", val)
        i = i + 1
      end -- if
    until not name

    end -- function f

    f (22, 33)

     -->

    index 1 a = 22
    index 2 b = 33
    index 3 c = 11
    index 4 i = 4
debug.getmetatable (o) Returns the metatable of the given object or nil if it does not have a metatable. Bypasses the check for the "__metatable" entry. debug.getregistry () Returns the registry table. This is a special table used by C functions to store information it wants to keep isolated from Lua functions.
    table.foreach (debug.getregistry (), print)

      -->

    FILE* table: 01B43F50
    _LOADLIB table: 01B42BC0
    mushclient.world table: 01B4BBC0
    _LOADED table: 01B418C0
    mushclient.document userdata: 017A8C58
    pcre_regex_handle table: 01B4E830
debug.getupvalue (level, upvalue) Similar to debug.getlocal, returns the names and values of the upvalues for the nominated function. See also debug.setupvalue.
    function newCounter ()
      local n = 0
      return function ()  -- anonymous function
        n = n + 1
        return n
        end -- function
    end -- newCounter

    c = newCounter ()
    c ()  -- count a couple of times
    c ()

    -- show upvalues in c

    local i = 1

    repeat
      name, val = debug.getupvalue (c, i)
      if name then
        print ("index", i, name, "=", val)
        i = i + 1
      end -- if
    until not name

     -->

     index 1 n = 2
In this example the function c is a closure (with associated upvalue "n"). NOTE: Lua does not let you see or change upvalues for C functions (eg. string.gfind). debug.setfenv (object, table) Sets the environment of the given object to the given table. Returns object. Similarly to debug.getfenv, this function takes a raw object (unlike the base setfenv function which can also take a function level). debug.sethook (thread, f, mask, count) Sets the function f as a hook to be called when the "mask" condition is satisfied. If count is non-zero, it is called after every "count" instructions. The thread argument is optional and defaults to the current thread. If called without arguments, turns off the hook. Mask can be one or more of: c - called every time Lua calls a function r - called every time Lua returns from a function l - called every time Lua enters a new line of code The mask can be the empty string if you simply want to hook after "count" instructions. The function f is called with its first parameter being a string, which can be one of: call return tail return line count In the case of "line" events it gets a second parameter, being the new line number. Inside the hook you can use debug.getinfo with level 2 to find information about the running function. (Level 0 is getinfo, and level 1 is the hook function). In the case of "tail return" however debug.getinfo will not return valid information. Here is an example of setting a hook to stop a runaway function from executing for too long:
    function test ()
      a = 0
      for i = 0, 1000 do
        a = a + i
      end -- for
    end -- test

    function hook (why)
      error ("hook reached: " .. why)
    end -- hook

    debug.sethook (hook, "", 100)

    test () --> error:  hook reached: count
In this case, the hook stopped execution after 100 instructions. This second example uses a "call" hook to display when each new function is entered:
    function f ()
      function g ()
      end -- g

     g ()
     g ()
    end -- f

    function hook (why)
      print ("hook reached: ", why)
      print ("function =", debug.getinfo (2, "n").name)
    end -- hook

    debug.sethook (hook, "c", 0)

    f ()

     -->

    hook reached:  call
    function = f
    hook reached:  call
    function = g
    hook reached:  call
    function = g
debug.setlocal (level, local, value) Sets the value of the local variable with the index 'local' of the function at 'level' on the stack. See also debug.getlocal. debug.setmetatable (object, table) Sets the metatable for the given object to the given table (which can be nil). Bypasses the check for the "__metatable" entry. debug.setupvalue (function, upvalue, value) Similar to debug.setlocal, sets the values of the upvalue for the nominated function. See also debug.getupvalue. debug.traceback (message) Returns a string with a traceback of the stack call. An optional message string is prepended to the beginning of the traceback message.
    function f ()
      function g ()
      print (debug.traceback ("traceback in g"))
      end -- g
      g ()
    end -- f

    f ()

     -->

    traceback in g
    stack traceback:
            stdin:3: in function `g'
            stdin:6: in function `f'
            stdin:1: in main chunk
            [C]: ?
See Also ... Topics Lua base functions Lua coroutine functions Lua io functions Lua math functions Lua os functions Lua package functions Lua script extensions Lua string functions Lua table functions (Help topic: general=lua_debug) Documentation contents page