115 lines
4.4 KiB
Markdown
115 lines
4.4 KiB
Markdown
|
|
# 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.
|
|
|
|
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 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 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:
|
|
|
|
1. Human readability.
|
|
2. Lua-compatible output.
|
|
3. Customization support.
|
|
|
|
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 - 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 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.
|
|
|
|
## 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 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.)
|
|
- 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`.
|
|
- Add options for colored output, and allow custom formatting.
|
|
|
|
## 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
|
|
customization 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).
|