Pretty

Introduction

pretty is an advanced pretty printer for Lua aiming primarily for human readability. It does this by looking for patterns in the input data, and creating an output string utilizing and highlighting those patterns. Thus it's a primarily a debugging tool, not a speedy serialization tool.

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 default Xenoterm pretty printer is much simpler than pretty, but the enhancements compared to other pretty printers, inspired me to create pretty. See the bottom of the page for other pretty printers.

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. And if some structure cannot be represented in Lua, I will 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.

Readability Methods

Here we outline the methods we use when formatting.

The simplest method is to align keys, equals-sign and values, of a table. Thus we separate them, and make it easier to distinguish them from each. Compare:

	bad = {
		a = 'hello world',
		hello = 'hi'
	}
	good = {
		a      =  'hello world',
		hello  =  'hi'
	}

Performance

As specified in the introduction, pretty is not a performance oriented library. Expected usage is in error conditions and debugging, not in tight inner loops.

Don't use pretty.lua if you want fast serialization. Use one of the pretty printers specified below.

TODO

I'm looking into implementing following features:

Improve display of medium-long lists with short elements. One option is something analog to the default results of ls on Linux.
Add support for setmetatable, and exploring the values accessible through it.
Provide nice formatting for cdata datatype in LuaJIT.
Expand on the comment output in output, for __tostring methods, and global namespaces like io or math.
Look into using concat operation to improve appearance of overly long non-breaking strings. Attempt to break near whitespace.
Attempt to fit output within a predefined width limit. Default to 80.
Find a better name than pretty.
Add option for colored output. Primarily syntax highlighting, but also BlueJ-style scope highlighting, with some faint background colors.
Look more into string.dump in the core library.
Better support upvalues for in functions. Complete support is impossible without traversing the original code or inspecting the intermediate representation, due to lexical scoping. (Pluto does it, but it's written in C.)

Other 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 other options. Lua has a large library of pretty printers and serialization libraries:

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.

Find others at the lua-users wiki.

4.7 KiB Raw Blame History