1
0
pretty/README.md

155 lines
5.2 KiB
Markdown
Raw Normal View History

2017-04-30 20:40:24 +00:00
2017-06-05 19:49:23 +00:00
# Pretty #
2017-06-05 20:08:33 +00:00
`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
2017-06-05 20:08:33 +00:00
creating an output string utilizing and highlighting those patterns. Thus it's
a primarily a debugging tool, not a speedy serialization tool.
2017-06-05 19:49:23 +00:00
2017-07-15 17:21:21 +00:00
## 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
2017-06-11 11:53:06 +00:00
This project is the outcome of my frustration with existing pretty printers, and
a desire to expand upon the pretty printer I developed for
2017-07-15 17:21:21 +00:00
[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`.
2017-06-05 19:49:23 +00:00
`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.
2017-06-05 19:49:23 +00:00
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.
2017-06-05 19:49:23 +00:00
## Features
- Written in good-old pureblood Lua, with support for PUC Lua 5.0+ and
LuaJIT 2.0+.
2017-06-05 19:49:23 +00:00
- 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
2017-06-05 19:49:23 +00:00
with short strings to short lists.
* Uses the standard `debug` library to gain information about functions
and other advanced structures.
2017-07-15 17:21:21 +00:00
## Installation
2017-07-15 17:21:21 +00:00
TODO
2017-07-15 17:21:21 +00:00
## API Documentation
2017-07-15 17:21:21 +00:00
TODO
## Tests
TODO
2017-06-05 19:49:23 +00:00
## 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. One option is
something analog to the default results of `ls` on Linux.
2017-06-05 19:49:23 +00:00
- 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`.
2017-06-25 11:16:34 +00:00
- 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.)
2017-06-05 19:49:23 +00:00
## Other pretty printers
2017-06-25 11:16:34 +00:00
`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.
2017-06-05 19:49:23 +00:00
2017-06-25 11:16:34 +00:00
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:
2017-06-05 19:49:23 +00:00
- [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.
2017-06-25 11:16:34 +00:00
Find others at [the lua-users wiki](lua-users.org/wiki/TableSerialization).
2017-07-15 17:21:21 +00:00
## 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
TODO[LICENSE.txt][./LICENSE.txt] file for details.