1
0
pretty/README.md

110 lines
3.5 KiB
Markdown
Raw Normal View History

<!--- 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.
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.
## 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 18:39:12 +00:00
$ print(pretty( { hello = 'world', num = 42 } ))
{
num = 42
hello = 'world'
}
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 18:39:12 +00:00
$ print(pretty( math.abs ))
builtin function (x)
-- math.abs
-- Returns the absolute value of x
2024-07-10 18:39:12 +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.
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.
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.
## 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+.
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
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:
**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.
**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 18:39:12 +00:00
## API Documentation
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.
# 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
```