pprint.lua

easy lua pretty printing, customizable and public domain!

pprint.lua is a friendly reimplementation of inspect.lua. pprint(whatever) in which whatever is anything you can find in Lua. It would dump it into a meaningful representation. Notably features:

• Limited customization through setting options.
• Sensible defaults, like not printing functions, userdatas, wrapping long lines etc.
• Printed results can be evaled (can't guaranteed to be identical as the original value).
• Tested on Lua 5.1, 5.2, 5.3, 5.4 and Luajit 2.0.2.
• Released into the Public Domain, for whatever reason.

Example:

local pprint = require('pprint')
pprint(_G)
-- dumped _G to standard output:
-- { --[[table 1]]
--   _G = [[table 1]],
--   _VERSION = 'Lua 5.1',
--   arg = {},
--   coroutine = { --[[table 11]] },
--   debug = { --[[table 6]] },
--   io = { --[[table 7]] },
--   math = { --[[table 10]]
--     huge = 1.#INF,
--     pi = 3.1415926535898
--   },
--   os = { --[[table 8]] },
--   package = { --[[table 3]]
--   ...

Usage

Grab pprint.lua and drop it into your project. Then just require and start printing:

local pprint = require('pprint')
pprint({ foo = 'bar' })

If you're on LuaRocks then just get inspect.lua instead. It's been around longer and more stable.

pprint.lua exposes pprint table with two other functions:

• pprint(...) : pretty print arguments, each argument starting on a new line.
• pprint.pformat(obj[, option[, printer]]) : return the string representation of obj. Provide option to override global settings during this invoke. printer will be called repeatedly with string segments from the output. For example pprint uses io.write as printer.
• pprint.setup(option) : setup global options, affecting all following calls.
• pprint.defaults : default settings. pprint(pprint.defaults) to see what's in it.

Options

You can configure pprint behaviors by using pprint.setup or pass a table into pformat:

pprint.setup {
    show_all = true,
    wrap_array = true,
}
print(pprint.format(pprint.defaults, {sort_keys = false}))

Available options are:

• show{type}_ : skip values of given type when set to false. This includes the type of value as key, value or array element of a table. Defaults to show only nil, boolean, number, string. In some projects type() might returns non standard types. pprint.lua treats all these as table, which in most cases should be reasonable.

• show_metatable : whether show metatable. Defaults to false.

• show_all : show everything when set to true. It overrides all other show options. Defaults to false.

• use_tostring : show table by using __tostring when available. Defaults to false.

• filter_function : provide a function and it would be called as func(v, [k, t]). v is the value. k is key or index while t is the parent, which isn't always available. Return truthy values to skip showing this value. Here's an example for hiding empty tables:

  pprint.setup{filter_function = function(v, k)
      return type(v) == 'table' and not next(v)
  end}

• object_cache : table might contain cyclic references and simply print all values would cause an infinite loop. object_cache defaults to local so pprint would refer previously seen table with a short name. Set to global will cause the cache be kept between pprint invokes. Set to false to disable, which might cause infinite loop.

  empty = {}
  d = {a=empty, b=empty, c=empty}
  pprint(d)
  -- {
  --   a = { --[[table 2]] },
  --   b = [[table 2]],
  --   c = [[table 2]]
  -- }

• indent_size : indent size for each nested table. Defaults to 2.

• level_width : max width per indent level. Defaults to 80.

• wrap_string : wrap strings longer than level_width. Defaults to true.

  pprint.setup({level_width = 12, wrap_string = true})
  pprint('these are my twisted words.')
  -- [[these are
  -- my twisted w
  -- ords.]]

• wrap_array : whether print each each array element on newline. Defaults to false.

• sort_keys : natural-sort table keys for easier reading. Defaults to true.

Bugs

Currently pprint.lua should be usable, meaning there's no obvious issues. If you've found something is wrong please do open an issue.

1. There aren't enough tests yet.
2. Combination of some settings might cause visual artifacts in the output.
3. eval pformat results might not always work, as string escaping isn't perfect atm.

TODOs

• verbose name tag printing, ie --[[table io]]
• show_custom type, option.show_foo = function(v) ... end

License

Public Domain