2024-07-10 17:25:23 +00:00
|
|
|
<!--- WARNING --->
|
|
|
|
<!--- THIS IS AN AUTO-GENERATED FILE --->
|
|
|
|
<!--- MANUAL CHANGES CAN AND WILL BE OVERWRITTEN --->
|
|
|
|
|
2024-07-10 18:39:12 +00:00
|
|
|
# pretty is an advanced pretty printer for Lua.
|
2024-07-10 17:25:23 +00:00
|
|
|
|
|
|
|
It's primarily a
|
2024-07-10 18:39:12 +00:00
|
|
|
debugging tool, aiming for human readability, by detecting pattern in the input
|
|
|
|
data, and creating an output string utilizing and highlighting those patterns.
|
2024-07-10 17:25:23 +00:00
|
|
|
|
|
|
|
## Code Example
|
|
|
|
|
|
|
|
Setup is simple, use pretty = require 'pretty', and you're good to go.
|
|
|
|
|
2024-07-10 18:39:12 +00:00
|
|
|
$ print(pretty( { 1, 2, 3 } ))
|
|
|
|
{ 1, 2, 3 }
|
2024-07-10 17:25:23 +00:00
|
|
|
|
2024-07-10 18:39:12 +00:00
|
|
|
$ print(pretty( { hello = 'world', num = 42 } ))
|
|
|
|
{
|
|
|
|
num = 42
|
|
|
|
hello = 'world'
|
2024-07-10 17:25:23 +00:00
|
|
|
}
|
|
|
|
|
2024-07-10 18:39:12 +00:00
|
|
|
$ print(pretty( { abs = math.abs, max = math.max, some = function() end } ))
|
|
|
|
{
|
|
|
|
abs = builtin function (x) ... end
|
|
|
|
max = builtin function (x, ...) ... end
|
|
|
|
some = function () ... end
|
2024-07-10 17:25:23 +00:00
|
|
|
}
|
|
|
|
|
2024-07-10 18:39:12 +00:00
|
|
|
$ print(pretty( math.abs ))
|
|
|
|
builtin function (x)
|
|
|
|
-- math.abs
|
|
|
|
-- Returns the absolute value of x
|
2024-07-10 17:25:23 +00:00
|
|
|
|
2024-07-10 18:39:12 +00:00
|
|
|
...
|
2024-07-10 17:25:23 +00:00
|
|
|
end
|
|
|
|
|
|
|
|
## Motivation
|
|
|
|
|
|
|
|
This project is the outcome of my frustration with existing pretty printers, and
|
2024-07-10 18:39:12 +00:00
|
|
|
a desire to expand upon the pretty printer I developed for
|
|
|
|
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.
|
2024-07-10 17:25:23 +00:00
|
|
|
|
|
|
|
pretty sorts it's priorities like so:
|
|
|
|
|
|
|
|
Human readability.
|
|
|
|
Lua-compatible output.
|
|
|
|
Customization.
|
|
|
|
|
|
|
|
I'd rather have good defaults than provide a ton of customization options. If an
|
2024-07-10 18:39:12 +00:00
|
|
|
structure avoids easy representation in Lua, I'd rather extend the syntax, than
|
|
|
|
lose the info.
|
2024-07-10 17:25:23 +00:00
|
|
|
|
|
|
|
Another aspect where pretty shines is in exploratory programming, when
|
2024-07-10 18:39:12 +00:00
|
|
|
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.
|
2024-07-10 17:25:23 +00:00
|
|
|
|
|
|
|
## Features
|
|
|
|
|
2024-07-10 18:39:12 +00:00
|
|
|
Written in good-old pure-blood Lua, with support for PUC Lua 5.0+ and LuaJIT 2.0+.
|
2024-07-10 17:25:23 +00:00
|
|
|
Redefining what it means to be "human readable":
|
2024-07-10 18:39:12 +00:00
|
|
|
Is multi-line centric, to aid readability.
|
|
|
|
Indention and alignment of keys-value pairs.
|
|
|
|
Keys-value pairs are
|
|
|
|
alpha-numerically 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
|
2024-07-10 17:25:23 +00:00
|
|
|
|
|
|
|
pretty is loadable directly with require. Either clone or download this
|
2024-07-10 18:39:12 +00:00
|
|
|
repository. Where you place it, depends upon what you want to do:
|
2024-07-10 17:25:23 +00:00
|
|
|
|
|
|
|
**You want pretty in a specific project**: Place the pretty folder
|
2024-07-10 18:39:12 +00:00
|
|
|
somewhere in your project, and require it from one of your project files.
|
2024-07-10 17:25:23 +00:00
|
|
|
**You want pretty on your system**: Place the pretty folder such that
|
2024-07-10 18:39:12 +00:00
|
|
|
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.
|
2024-07-10 17:25:23 +00:00
|
|
|
|
2024-07-10 18:39:12 +00:00
|
|
|
## API Documentation
|
2024-07-10 17:25:23 +00:00
|
|
|
|
|
|
|
pretty exposes a single function, the pretty function itself. It's function
|
2024-07-10 18:39:12 +00:00
|
|
|
signature is pretty(value, options). value can be any Lua value. options
|
|
|
|
must be a table.
|
2024-07-10 17:25:23 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# License
|
|
|
|
|
|
|
|
```
|
|
|
|
"THE BEER-WARE LICENSE" (Revision 42):
|
|
|
|
|
|
|
|
<jonjmaa@gmail.com> wrote this program. As long as you retain this notice you
|
|
|
|
can do whatever you want with this stuff. If we meet some day, and you think
|
|
|
|
this stuff is worth it, you can buy me a beer in return.
|
|
|
|
|
|
|
|
Jon Michael Aanes
|
|
|
|
```
|