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