Module:Inspect/doc

Inspect transforms Lua into a human-readable representation. The objective here is human understanding (i.e. for debugging), not serialization or compactness. The consistent reconstruction of Lua values is not possible from the string representation, because of items appearing as <table>, <metatable> or <function> in certain cases.

Historically, this module could serve as a polyfill for the mw.dumpObject function which was available in Scribunto core but was missing on Fandom. That function is now available on Fandom as well, though the Inspect library still provides a few additional features.

Forked from https://dev.fandom.com/wiki/Module:Inspect which was a fork of https://github.com/kikito/inspect

Documentation

Package items

inspect(root, options) (function)

Transforms any Lua value into a human-readable representation.

Parameters:

root Lua value to transform into string. (table|function|number|string|boolean)

options Configuration options for transformation. (table; optional)

options.depth Maximum depth to print inside a table before table truncation occurs in the form {...}. Default: math.huge. (number; optional)

options.newline Newline character to insert before dictionary keys. Default: "\n". (number; optional)

options.indent Indentation to insert before keys or sequential values. Default: " ". (number; optional)

options.process Returns the item if the inspected table is displayed. Signature: function(item, path).

• • item Either a key or value on the table/subtables.
  • path Sequence representing root index keys used to reach item.
    • Values have a regular list of keys. Example: to index 1 in {a = {b = 1}}, the path is {'a', 'b'}.
    • Keys have a list of keys followed by the enum inspect.KEY. Example: to index c in {a = {b = {c=1}}}, the path is {'a', 'b', 'c', inspect.KEY }.
    • Metatables have a list of keys followed by the enum inspect.METATABLE. Example: to index {b=1}'s metatable in {a = {b=1}}, the path's {'a', {b=1}, inspect.METATABLE}.

(function; optional)

Returns: Human-readable representation of root.

• Primitives (boolean or nil) are converted into an executable string representation of the value.
• Strings are converted into quoted strings with backslash escapes if they contain special characters.
• Tables are converted into a human-readable representation. The keys will be sorted alphanumerically when possible.
  • Array keys are rendered horizontally.
  • Dictionary keys are rendered one element per line.
  • Metatables are rendered with the <metatable> field.
  • Repeated tables are serialised as <%d> first, then <table %d>.
  • Recursive table loops are serialised as <table %d>.
• Functions are serialised as <function %d>.

(string)

Usage:

-- Primitives.
assert(inspect(nil) == "nil")
assert(inspect(1) == "1")
assert(inspect("Hello") == '"Hello"')

-- Array-like table.
assert(inspect({1,2,3,4}) == "{ 1, 2, 3, 4 }")

-- Dictionary-like table.
assert(inspect({a=1,b=2}) == [[{
  a = 1,
  b = 2
}]])

-- Hybrid dictionary-array table.
assert(inspect({1,2,3,b=2,a=1}) == [[{ 1, 2, 3,
  a = 1,
  b = 2
}]])

-- Table with a subtable and function.
assert(inspect({a={f=tostring}}) == [[{
  a = {
    f = <function 1>
  }
}]])

-- Table with a metatable.
assert(inspect(setmetatable({a=1}, {b=2}) == [[{
  a = 1
  <metatable> = {
    b = 2
  }
}]]))

-- Table with a recursive loop.
local a = {1, 2}
local b = {3, 4, a}
a[3] = b -- a references b, and b references a
assert(inspect(a) == "<1>{ 1, 2, { 3, 4, <table 1> } }")

-- <code><nowiki>options.depth</nowiki></code>.
assert(inspect(t5, {depth = 2}) == [[{
  a = {
    b = {...}
  }
}]])

-- <code><nowiki>options.newline</nowiki></code> & <code><nowiki>options.indent</nowiki></code>.
assert(inspect(
    t,
    {newline='@', indent="++"}),
    "{@++a = {@++++b = 1@++}@}"
)

-- <code><nowiki>options.process</nowiki></code> metatable removal.
local account = { 'peter', 'GlaHquq0' }
local account_mt = { __tostring = inspect }
setmetatable(account, account_mt)

local remove_mt = function(item) -- removes specific metatable
    if item ~= account_mt then return item end
end

assert(inspect(t, {process = remove_mt}) == "{ 'peter', 'GlaHquq0' }")

local remove_all_metatables = function(item, path)
    if path[#path] ~= inspect.METATABLE then return item end
end

assert(inspect(t, {process = remove_all_metatables}) == "{ 'peter', 'GlaHquq0' }")

-- <code><nowiki>options.process</nowiki></code> item filtering.
local anonymize_password = function(item, path)
  if path[#path] == 2 then return item:gsub('.', '●') end
  return item
end

assert(inspect(info, {process = anonymize_password}) == "{ 'peter', '●●●●●●●●' }" )

inspect.KEY (member; table)

Processing enumerable for a key in inspection paths.

inspect.METATABLE (member; table)

Processing enumerable for a metatable in inspection paths.

See also

Original module on Github.

---

Created with Docbunto