Pretty

pretty is an advanced pretty printer for Lua. It's primarily a debugging tool, aiming for human readability, by detecting pattern in the input data, and creating an output string utilizing and highlighting those patterns.

Code Example

Setup is simple, use pretty = require 'pretty', and you're good to go.

> print(pretty( { 1, 2, 3 } ))
{ 1, 2, 3 }

> print(pretty( { hello = 'world', num = 42 } ))
{
	num   = 42
	hello = 'world'
}

> print(pretty( { abs = math.abs, max = math.max, some = function() end } ))
{
	abs  = builtin function (x)      ... end
	max  = builtin function (x, ...) ... end
	some =         function ()       ... end
}

> print(pretty( math.abs ))
builtin function (x)
    -- math.abs
	-- Returns the absolute value of x

	...
end

Motivation

This project is the outcome of my frustration with existing pretty printers, and a desire to expand upon the pretty printer I developed for Xenoterm. The original Xenoterm pretty printer was much simpler than pretty - and the current is even simpler - but the enhancements I make, when compared to other pretty printers, inspired me to create pretty.

pretty sorts it's priorities like so:

Human readability.
Lua-compatible output.
Customization.

I'd rather have good defaults than provide a ton of customization options. If an structure avoids easy representation in Lua, I'd rather extend the syntax, than lose the info.

Another aspect where pretty shines is in exploratory programming, when attempting to avoid reliance on outside documentation. The amount of information pretty exposes varies by the data you are inspecting. If you're inspecting a list of functions, their function signatures are visible, but if you're inspecting a single function, documentation and source location may appear if available.

Features

Written in good-old pureblood Lua, with support for PUC Lua 5.0+ and LuaJIT 2.0+.
Redefining what it means to be "human readable":
- Is multi-line centric, to aid readablitiy.
- Indention and alignment of keys-value pairs.
- Keys-value pairs are properly sorted by key type and thereafter alphabetically.
- The format and structure of output changes depending upon the input. Maps appear differently to deeply nested tables to long sequences with short strings to short lists.
- Uses the standard debug library to gain information about functions and other advanced structures.

Installation

pretty is loadable directly with require. Either clone or download this repository. Where you place it, depends upon what you want to do:

You want pretty in a specific project: Place the pretty folder somewhere in your project, and require it from one of your project files.
You want pretty on your system: Place the pretty folder such that it's visible from your Lua-path. On my system this might be /usr/local/share/lua/5.1/. Now you can require it from anywhere.

API Documentation

pretty exposes a single function, the pretty function itself. It's function signature is pretty(value, options). value can be any Lua value. options must be a table.

List of options

pretty is sure to complain if you give it an unknown option, or if you give an option a bad value.

indent: string: The string to indent with. Four spaces by default.

TODO

Tasks to be done before pretty can be called version 1.0.0, in order of priority:

Add a dedicated unicode submodule, to handle some minor alignment and character escaping issues. pretty should escape all malformed unicode sequences.
Align numbers towards right for tabular views.
Add support for setmetatable, and exploring values in metatables.
Provide nice formatting for cdata datatype in LuaJIT.
Find a better name than pretty.
Enhance internal structure some amount. See TODO markers in files.

It would be nice to have the following, but these are secondary:

Add option for colored output. Primarily syntax highlighting, but also BlueJ-style scope highlighting, with some faint background colors.
Expand on the comment output in output, for __tostring methods, and global namespaces like io or math.
Fit output within a predefined width limit. Default to 80.
Look into tool for understanding complex structures with recursive definitions. Whatever modes are thought up, they should be automatic modes, not an options. Should at least include modes for self-referential tables and Directed-Acyclic-Graphs.

Alternative pretty printers

pretty is large, slow, and requires the debug library to work. It's not designed for serialization purposes, nor is it concerned with offering the same level of customization as other libraries do.

If you want a sleek, fast, customizable or embeddable library, there are thankfully other options.

inspect.lua: One of the classic debugging pretty printers.
pprint.lua: Reimplementation of inspect.lua
serpent: Advanced and fast pretty printer.
pluto: Can serialize arbitrary parts of Lua, including functions, upvalues, and proper lexical scoping. Not written in native Lua.
binser: Library for special purpose serialization.

Even more are available at the lua-users wiki.

Contact

The author is available at jonjmaa (at) gmail.com. Be sure to send an email if you have ideas for improvements, or find an issue.

License

The license is the BeerWare license - Please see the LICENSE.txt file for details.

5.7 KiB Raw Blame History