12 — Standard Library Deep-Dive

-- debug.getinfo(level, what): get info about a stack frame
local info = debug.getinfo(1, "Slnu")
-- info.source    — "@script.lua" (or "stdin", or "=[C]" for C functions)
-- info.short_src — "script.lua" (abbreviated)
-- info.currentline — current line in that frame
-- info.linedefined — first line of the function
-- info.lastlinedefined — last line
-- info.what      — "Lua", "C", "main"
-- info.name      — function name (may be nil for anonymous)
-- info.namewhat  — "global", "local", "method", "field", "upvalue", ""
-- info.nups      — number of upvalues
-- info.isvararg  — true if function is vararg (with "u" flag)

-- debug.getlocal(level, index): get local variable by index in a frame
local function dump_frame(level)
  level = level or 1
  local i = 1
  while true do
    local name, value = debug.getlocal(level, i)
    if not name then break end
    print(string.format("  [%d] %s = %s", i, name, tostring(value)))
    i = i + 1
  end
end

-- debug.setlocal(level, index, value): SET a local variable (powerful debugging)
-- debug.getupvalue(fn, index) / debug.setupvalue(fn, index, value): upvalue access

-- debug.traceback(msg, level): stack trace string
print(debug.traceback("here", 2))  -- skip this function and the caller

-- debug.sethook(callback, events, count?): execution hooks
-- Events: "c" call, "r" return, "l" line, "c" + count = every N instructions
local function profile(fn)
  local counts = {}
  debug.sethook(function(event, line)
    local info = debug.getinfo(2, "Sl")
    local key = info.source .. ":" .. line
    counts[key] = (counts[key] or 0) + 1
  end, "l")
  fn()
  debug.sethook()  -- remove hook
  return counts
end

-- Production: simple line profiler
local function simple_profiler(fn)
  local start = os.clock()
  local ok, result = pcall(fn)
  local elapsed = os.clock() - start
  if not ok then error(result, 2) end
  return result, elapsed  -- return result + CPU time
end

package — Module System Internals

-- package.loaded: cache of loaded modules (table name → module value)
print(package.loaded.string)  -- the string library table
package.loaded["my_module"] = nil  -- evict (force reload on next require)

-- package.preload: programmatic module registration (checked before filesystem)
package.preload["injected"] = function()
  return {hello = function() return "injected" end}
end
require("injected").hello()  -- "injected" (no file needed)

-- package.searchers (5.2+): ordered list of loader functions
-- Each: function(name) → loader_fn | error_string | nil
-- Default: [preload, path searcher, cpath searcher, all-in-one]

-- Add a custom searcher (insert at position 1 to check first):
table.insert(package.searchers, 1, function(name)
  local source = my_embedded_modules[name]  -- your custom source map
  if not source then return nil end  -- not found, try next searcher
  local fn, err = load(source, name, "t")
  if not fn then return err end
  return fn
end)

-- package.searchpath(name, path, sep, rep): find a file on a path
local found = package.searchpath("mymod.utils", package.path)
-- Returns "/path/to/mymod/utils.lua" or nil + "tried paths" error

local start = os.clock()
for i = 1, 1000000 do end  -- CPU-bound
print(string.format("%.4fs CPU", os.clock() - start))