Class Models for Lua

# 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)

Copyright (C) 2004-2008 Tecgraf, PUC-Rio

This project is currently being maintained by Tecgraf at PUC-Rio.