Penlight Documentation

# Module `pl.pretty`

Pretty-printing Lua tables.

Also provides a sandboxed Lua table reader and a function to present large numbers in human-friendly format.

Dependencies: pl.utils, pl.lexer, pl.stringx, debug

## Functions

read (s) | Read a string representation of a Lua table.
load (s[, env[, paranoid]]) | Read a Lua chunk.
write (tbl[, space[, not_clever]]) | Create a string representation of a Lua table.
dump (t[, filename]) | Dump a Lua table out to a file or stdout.
debug (...) | Dump a series of arguments to stdout for debug purposes.
number (num[, kind[, prec]]) | Format large numbers nicely for human consumption.

## Functions

read (s)
  Read a string representation of a Lua table. This function loads and runs the string as Lua code, but bails out if it contains a function definition. Loaded string is executed in an empty environment.

  ### Parameters:

  - s string string to read in `{...}` format, possibly with some whitespace before or after the curly braces. A single line comment may be present at the beginning.

  ### Returns:

  a table in case of success. If loading the string failed, return `nil` and error message. If executing loaded string failed, return `nil` and the error it raised.
load (s[, env[, paranoid]])
  Read a Lua chunk.

  ### Parameters:

  - s string Lua code.
  - env table environment used to run the code, empty by default. (optional)
  - paranoid boolean abort loading if any looping constructs a found in the code and disable string methods. (optional)

  ### Returns:

  the environment in case of success or `nil` and syntax or runtime error if something went wrong.
write (tbl[, space[, not_clever]])
  Create a string representation of a Lua table. This function never fails, but may complain by returning an extra value. Normally puts out one item per line, using the provided indent; set the second parameter to an empty string if you want output on one line.

  NOTE: this is NOT a serialization function, not a full blown debug function. Checkout out respectively the serpent or inspect Lua modules for that if you need them.

  ### Parameters:

  - tbl table Table to serialize to a string.
  - space string The indent to use. Defaults to two spaces; pass an empty string for no indentation. (optional)
  - not_clever boolean Pass `true` for plain output, e.g `{['key']=1}`. Defaults to `false`. (optional)

  ### Returns:

  1. a string
  2. an optional error message
dump (t[, filename])
  Dump a Lua table out to a file or stdout.

  ### Parameters:

  - t table The table to write to a file or stdout.
  - filename string File name to write too. Defaults to writing to stdout. (optional)
debug (...)
  Dump a series of arguments to stdout for debug purposes. This function is attached to the module table `__call` method, to make it extra easy to access. So the full:

       print(require("pl.pretty").write({...}))

  Can be shortened to:

       require"pl.pretty" (...)

  Any `nil` entries will be printed as `"<nil>"` to make them explicit.

  ### Parameters:

  - ... the parameters to dump to stdout.

  ### Usage:

      -- example debug output
      require"pl.pretty" ("hello", nil, "world", { bye = "world", true} )

      -- output:
      {
        ["arg 1"] = "hello",
        ["arg 2"] = "<nil>",
        ["arg 3"] = "world",
        ["arg 4"] = {
          true,
          bye = "world"
        }
      }

number (num[, kind[, prec]])
  Format large numbers nicely for human consumption.

  ### Parameters:

  - num number a number.
  - kind string one of `'M'` (memory in `KiB`, `MiB`, etc.), `'N'` (postfixes are `'K'`, `'M'` and `'B'`), or `'T'` (use commas as thousands separator), `'N'` by default. (optional)
  - prec integer number of digits to use for `'M'` and `'N'`, `1` by default. (optional)

generated by LDoc 1.5.0