149 lines
5.2 KiB
Markdown
149 lines
5.2 KiB
Markdown
|
|
# 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. 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
|
|
|
|
`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
|
|
|
|
I'm looking into implementing following features:
|
|
|
|
- Add a dedicated unicode submodule, to handle a bunch of cases.
|
|
- 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`.
|
|
- Attempt to fit output within a predefined width limit. Default to 80.
|
|
- Add option for colored output. Primarily syntax highlighting, but also
|
|
[BlueJ-style](www.bluej.org/about.html) scope highlighting, with some faint
|
|
background colors.
|
|
- Find a better name than `pretty`.
|
|
|
|
## 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
|
|
|
|
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.
|