pretty/README.md

# Pretty #

`pretty` is an advanced pretty printer for [Lua](lua.org). 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.

```lua
> 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](https://gitfub.space/takunomi/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:

1.	Human readability.
2.	Lua-compatible output.
3.	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](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 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:

1.	**You want `pretty` in a specific project**: Place the `pretty` folder
	somewhere in your project, and `require` it from one of your project files.
2.	**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](www.bluej.org/about.html) 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](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.

Even more are available at [the lua-users wiki](lua-users.org/wiki/TableSerialization).

## 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](https://gitfub.space/Jmaa/pretty/blob/master/LICENSE.txt) file for
details.