test | ||
analyze_structure.lua | ||
function.lua | ||
init.lua | ||
library.lua | ||
number.lua | ||
pretty.lua | ||
README.md | ||
table_type.lua |
Pretty
Introduction
pretty
is an advanced pretty printer for Lua 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:
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. 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:
- Human readability.
- Lua-compatible output.
- 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 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 likeio
ormath
. - 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: One of the classic debugging pretty printers.
- pprint.lua: Reimplementation of
inspect.lua
- serpent: Advanced and fast pretty printer.
- pluto: Can serialize arbitrary parts of Lua, including functions, upvalues, and proper lexical scoping. Not written in native Lua.
- binser: Library for special purpose serialization.
Others can be found at the lua-users wiki.