pretty/README.md

# Pretty #

## Introduction

`pretty` is an advanced pretty printer for [Lua](lua.org) aiming primarily for
human readability. This is done 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.

Humans are flexible in their understanding of data, as long as certain
underlying structural patterns can be found. `pretty` attempts to find those
patterns and highlight them, often after performing huge analytical tasks.

Sometimes just aligning elements are enough to easy the burden on the eyes.
Contrast the two following pieces of code:

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

This project came out of the frustration with existing pretty printers, which
would often employ simpler heuristics, each good at displaying some specific
structure, but bad at others. See below for other pretty printers.

Another aspect where `pretty` shines is in exploratory programming, when
attempting to avoid reliance on outside documentation.

## Features

-	Written in good-old pureblood Lua, with support for PUC Lua 5.0 - 5.3 and
	LuaJIT 2.0 and up.
-	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](http://www.davekoelle.com/alphanum.html)
		sorted by key type and thereafter alphabetically.
	*	The format and structure of output changes depending upon the input.
		Maps are displayed 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.

## 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 better. One option
	would be to implement something analog to the default results of `ls` on
	Linux.
-	Add support for `setmetatable`, and exploring the values accessible through
	it.
-	Nice formatting for `cdata` datatype in LuaJIT.
-	Add possibility of comments in output, for stuff like `__tostring` methods,
	and global namespaces like `io` or `math`.
-	Better support upvalues 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.)
-	Look more into `string.dump` in the core library.
-	Look into using concat operation to improve appearance of overly long
	non-breaking strings. Maybe even attempt to break near whitespace.
-	Attempt to fit output within a predefined width limit. Default to 80(?)
-	Find a better name than `pretty`.

## Other pretty printers

`pretty` is a large and slow library, and is not designed for serialization
purposes, nor is `pretty` concerned with offering the same level of
stabilizability as other libraries do.

Luckily Lua has a large library of pretty printers and serialization libraries:

-	[inspect.lua](github.com/kikito/inspect.lua): One of the classic debugging
	pretty printers.
-	[pprint.lua](github.com/jagt/pprint.lua): Reimplementation of `inspect.lua`
-	[serpent](github.com/pkulchenko/serpent): Advanced and fast pretty printer.
-	[pluto](lua-users.org/wiki/PlutoLibrary): Can serialize arbitrary parts of
	Lua, including functions, upvalues, and proper lexical scoping. Not written
	in native Lua.
-	[binser](github.com/bakpakin/binser): Library for special purpose
	serialization.

Others can be found at [the lua-users wiki](lua-users.org/wiki/TableSerialization).