Value Viewer

`loop.debug.Viewer`

Class of objects that generate human-readable textual representation of Lua values. This class is typically used to print out value of variables, data structures or objects in a Lua application using a syntax similar to the Lua language. It is useful for implementation of command line debug mechanisms. This class can also be used as a simple serialization mechanism for a restricted set of Lua values.

Basically, each object provides an operation to print values and holds some information that defines how values should be displayed like the output used.

Behavior

Fields

indentation: String used to add an indentation level when writing nested tables. To write tables without indentation or in a single line use the empty string. The default value of this field is a string with two blank spaces i.e. ' '.
labels: Table mapping values to their labels that are the strings that represent each value. The default value of this field is a table with all packages loaded at the moment this class is first required properly labeled.
linebreak: String used to add line breaks when writing tables. To write tables in a single line use a string with a space. The default value of this field is the string '\n'.
maxdepth: Maximum number of levels of nested tables that should be visualized. When this value is negative all levels of nested tables are visualized. The default value of this field is -1.
output: Object used to write visualization of values. The object must provide the operation write that receives strings to be written. The default value of this field is the standard output file.
prefix: String written at the start of each new line of the visualization. The default value of this field is an empty string.

Methods

label(value): Method used to generate a label for a given value not already labeled in field labels. By default this method generates labels using the tostring method of Lua base library. If the value defines the __tostring meta-method then the original string representation is shown between parenthesis. This method may be redefined for each object in order to define other labeling policy.
package(name, pack): Method that adds labels for the package named name and defined by table pack as well as all its functions or userdata fields.
print(...): Method that writes the textual representation of all arguments to field output. However, string values are written directly without any transformation.
tostring(...): Method that returns a string with the textual representation of all the values passed as argument. The representations of each argument are separated by commas in the final representation.
write(...): Method that writes the textual representation of all arguments to field output. The representations of each argument are separated by commas in the final representation.
writeto(output, ...): Method that writes to object output the textual representation of all other arguments. The object output must provide the operation write that receives strings to be written. The representations of each argument are separated by commas in the final representation.

Remarks

This class can be used as an instance of itself, therefore all methods can be executed over the class itself.
May be used to serialize into Lua code any value of type nil, boolean, number, string and table. However, serialized tables may not contain circular reference, other values that do not match this description, or string keys that match the name of a Lua keyword. To serialize values of other types, you should label them with a chunk of Lua code that is able to restore the value.

Examples

Show part of the global state of Lua

local Viewer = require "loop.debug.Viewer"
viewer = Viewer{
 maxdepth = 3,
 indentation = "| "
}
viewer:write(_G)