Added basic README.md
This commit is contained in:
parent
f528a7853f
commit
e98487fcae
98
README.md
98
README.md
|
@ -1,2 +1,98 @@
|
|||
|
||||
README is TODO
|
||||
# Pretty #
|
||||
|
||||
## Introduction
|
||||
|
||||
`pretty` is an advanced pretty printer for [Lua](lua.org). It attempts to
|
||||
understand your datastructures and return a pretty printed string
|
||||
representation. It's primary purpose is to be a good human-readable debugging
|
||||
tool, not a speedy serialization tool.
|
||||
|
||||
Humans are flexible in their understanding of data, as long as certain
|
||||
underlying structural patterns can be found. `pretty` attempts to find those
|
||||
patterns and highlight them, often after performing huge analytical tasks.
|
||||
|
||||
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 came out of the frustration with existing pretty printers, which
|
||||
would often employ simpler heuristics, each good at displaying some specific
|
||||
structure, but bad at others. See below for other pretty printers.
|
||||
|
||||
Another aspect where `pretty` shines is in exploratory programming, when
|
||||
attempting to avoid reliance on outside documentation.
|
||||
|
||||
## 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 are displayed 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 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(?)
|
||||
|
||||
## 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
|
||||
stabilizability 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).
|
||||
|
|
Loading…
Reference in New Issue
Block a user