# debug

This is an expansion to the existing Lua debug library.
This allows you to create many ways of accessing data that would be otherwise impossible.
As well as providing security features for safety of instrusions to lua-based APIs not from the Interstellar Engine.

• Returns the environment of object obj.
• 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.

• Returns the current hook settings as three values: Hook Function, Mask, Count

• Returns a table with information about a function or stack level

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

• Returns the name and value of the local variable with the index 'local' of the function at 'level' on the stack.

• Returns the metatable of the given object or nil if it does not have a metatable.

• Returns the registry table, which is a special table used by C functions to store information it wants to keep isolated from Lua functions.
• This can act as permanent storage for variables to be retreived later on.

• Similar to debug.getlocal, returns the names and values of the upvalues for the nominated function.

• Sets the environment of the given object to the given table, returns the object.

• Sets the value of the local variable with the index 'local' of the function at 'level' on the stack.

• 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.
• The function f is called with its first parameter being a string, which can be one of: call, return, tail return, line, count

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

• Sets the metatable for the given object to the given table (which can be nil).
• Bypasses the check for the "__metatable" entry.
• Returns the object.

• Similar to debug.setlocal, sets the values of the upvalue for the nominated function.

• Returns a string with a traceback of the stack call.
• An optional message string is prepended to the beginning of the traceback message.

• Gets the true debug registry table.
• This table is used to keep permanent objects, preventing GC from removing them.

• Gets the true global table.

• Gets the current stack's environment.

• Creates a memory-based hook towards a target lua function or C function.

• If a function has a memory-mapping to another function.

• If a function has a memory-mapping, this will return the original.

• Restores the memory-mapped function.

local original
original = debug.detour(print, function(...)
       MsgC( Color( 255, 0, 0 ), "[Detour working!]" )
       return original(...)
end)

print("This is a test!") -- Outputs: [Detour working!]This is a test!

if debug.isdetour(print) then
    print("The `print` function has been detoured.")
else
    print("The `print` function is not detoured.")
end

local original_print = debug.original(print)
original_print("This bypasses the detour!")

debug.restore(print) -- Restores the original `print` function.
print("Detour has been restored!") -- Outputs normally without detour.

• Copys a value in memory, creating a completely new value but with the same characteristics.

local original_func = function(a, b) return a + b end
local cloned_func = debug.clone(original_func)

print(original_func(5, 3))  -- Output: 8
print(cloned_func(5, 3))    -- Output: 8 (cloned function has the same behavior)

• Replaces a value by reference in memory, effectively replacing all occurences of it.

local original = function() print("original call!") end
local replaced = function() print("replaced call!") end 
original()
debug.replace(original, replaced) --  replace, now its gonna print "replaced call!" instead of "original call!"
original()

• Creates a new cfunction closure which is untraceable.

• Gets the garbage collector table.
• This has iterator functionality in foreach-loops.
• Do note this contains every value in existance.

• Converts a datatype into it's absolute pointer location.
• Output looks like this: "0xd8ad9caa" or 3635244450

• Scans memory to find the pointer association.

• Converts an function to a prototype object

• Converts an prototype into a function handle
• Do note this creates a completely new function

• Gets a function's constant by their index

• Gets all constants from a function

• Sets a constant in a function at an index
• Returns a boolean on if it was able to do so

• Checks if the provided function is made by "C"

• Checks if the provided function is made by "Lua"

• Changes a cfunction to be a Fast Function with an ID.
• This will make them appear as "builtin: xx"
• Use newcclosure if you plan to make a detour with this.

• Gets the ffid number of a cfunction.

• Gets a list of upvalues and that a function has.

local a, b, c = 1, 2, 3
local f = function() print(a, b, c) end
PrintTable(debug.getupvalues(f))
-- prints: {"a" = 1, "b" = 2, "c" = 3}

• Fetches a list of the current stack memory.
• This is used to debug and print out what it looks like.

• Fetchs directly from the lua stack.
• This can be used to get values in stack memory.

• Sets a value at an index in stack memory.
• Warning: this is rather dangerous and can poison the lua stack.

• Gets the true debug registry table, pushing it onto the stack.
• This table is used to keep permanent objects, preventing GC from removing them.

• Gets the true global table, pushing it onto the stack.

• Gets the current stack's environment, pushing it onto the stack.

• Gets the garbage collector table, pushing it onto the stack.
• Do note this contains every value in existance.

• Creates a new cfunction closure which is untraceable.

• Creates a new cfunction closure which is untraceable.

• Copys a value in memory, creating a completely new value but with the same characteristics.

• Replaces a value by reference in memory, effectively replacing all occurences of it.

• Converts a datatype into it's absolute pointer location.
• Output looks like this: "0xd8ad9caa" or 3635244450

• Scans memory to find the pointer association, pushing it onto the stack.