152 lines
5.2 KiB
Markdown
152 lines
5.2 KiB
Markdown
# Pretty #
|
|
|
|
`pretty` is an advanced pretty printer for [Lua](lua.org) 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.
|
|
|
|
## Code Example
|
|
|
|
Setup is simple, just `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. 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](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
|
|
|
|
TODO
|
|
|
|
## API Documentation
|
|
|
|
TODO
|
|
|
|
## Tests
|
|
|
|
TODO
|
|
|
|
## 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:
|
|
|
|
- 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](www.bluej.org/about.html) 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](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.
|
|
|
|
Find others 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, find an issue, or even an unintuitive result.
|
|
|
|
## License
|
|
|
|
This project is licensed under the BeerWare license - Please see the
|
|
[LICENSE.txt](https://gitfub.space/Jmaa/pretty/blob/master/LICENSE.txt) file for details.
|