1
0

Fixed readme
Some checks failed
LÖVE/Lua Library / Test (push) Failing after 6s
LÖVE/Lua Library / Static-Analysis (push) Failing after 3s

This commit is contained in:
Jon Michael Aanes 2024-07-10 20:39:12 +02:00
parent 748fe7835e
commit 779fa2884c
Signed by: Jmaa
SSH Key Fingerprint: SHA256:Ab0GfHGCblESJx7JRE4fj4bFy/KRpeLhi41y4pF3sNA
2 changed files with 53 additions and 225 deletions

208
README.md
View File

@ -2,9 +2,7 @@
<!--- THIS IS AN AUTO-GENERATED FILE ---> <!--- THIS IS AN AUTO-GENERATED FILE --->
<!--- MANUAL CHANGES CAN AND WILL BE OVERWRITTEN ---> <!--- MANUAL CHANGES CAN AND WILL BE OVERWRITTEN --->
# Pretty # pretty is an advanced pretty printer for Lua.
pretty is an advanced pretty printer for Lua.
It's primarily a It's primarily a
debugging tool, aiming for human readability, by detecting pattern in the input debugging tool, aiming for human readability, by detecting pattern in the input
@ -14,37 +12,29 @@ It's primarily a
Setup is simple, use pretty = require 'pretty', and you're good to go. Setup is simple, use pretty = require 'pretty', and you're good to go.
```lua $ print(pretty( { 1, 2, 3 } ))
> print(pretty( { 1, 2, 3 } ))
{ 1, 2, 3 } { 1, 2, 3 }
> print(pretty( { hello = 'world', num = 42 } )) $ print(pretty( { hello = 'world', num = 42 } ))
{ {
num = 42 num = 42
hello = 'world' hello = 'world'
} }
> print(pretty( { abs = math.abs, max = math.max, some = function() end } )) $ print(pretty( { abs = math.abs, max = math.max, some = function() end } ))
{ {
abs = builtin function (x) ... end abs = builtin function (x) ... end
max = builtin function (x, ...) ... end max = builtin function (x, ...) ... end
some = function () ... end some = function () ... end
} }
> print(pretty( math.abs )) $ print(pretty( math.abs ))
builtin function (x) builtin function (x)
-- math.abs -- math.abs
-- Returns the absolute value of x -- Returns the absolute value of x
... ...
end end
```
## Motivation ## Motivation
@ -74,198 +64,36 @@ Another aspect where pretty shines is in exploratory programming, when
## Features ## Features
Written in good-old pureblood Lua, with support for PUC Lua 5.0+ and Written in good-old pure-blood Lua, with support for PUC Lua 5.0+ and LuaJIT 2.0+.
LuaJIT 2.0+.
Redefining what it means to be "human readable": Redefining what it means to be "human readable":
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
* 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
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 pretty is loadable directly with require. Either clone or download this
repository. Where you place it, depends upon what you want to do: repository. Where you place it, depends upon what you want to do:
**You want pretty in a specific project**: Place the pretty folder **You want pretty in a specific project**: Place the pretty folder
somewhere in your project, and require it from one of your project files. 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 **You want pretty on your system**: Place the pretty folder such that
it's visible from your Lua-path. On my system this might be 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. /usr/local/share/lua/5.1/. Now you can require it from anywhere.
API Documentation ## API Documentation
pretty exposes a single function, the pretty function itself. It's function pretty exposes a single function, the pretty function itself. It's function
signature is pretty(value, options). value can be any Lua value. options signature is pretty(value, options). value can be any Lua value. options
must be a table. must be a table.
### List of options
pretty is sure to complain if you give it an unknown option, or if you give an
option a bad value.
indent: string: The string to indent with. Four spaces by default.
## TODO
Tasks to be done before pretty can be called version 1.0.0, in order of
priority:
Add a dedicated unicode submodule, to handle some minor alignment and
character escaping issues. pretty should escape all malformed unicode
sequences.
Align numbers towards right for tabular views.
Add support for setmetatable, and exploring values in metatables.
Provide nice formatting for cdata datatype in LuaJIT.
Find a better name than pretty.
Enhance internal structure some amount. See TODO markers in files.
It would be nice to have the following, but these are secondary:
Add option for colored output. Primarily syntax highlighting, but also
[BlueJ-style](www.bluej.org/about.html) scope highlighting, with some faint
background colors.
Expand on the comment output in output, for __tostring methods, and global
namespaces like io or math.
Fit output within a predefined width limit. Default to 80.
Look into tool for understanding complex structures with recursive
definitions. Whatever modes are thought up, they should be automatic modes,
not an options. Should at least include modes for self-referential tables
and Directed-Acyclic-Graphs.
Alternative pretty printers
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.
If you want a sleek, fast, customizable or embeddable library, there are
thankfully other options.
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.
Even more are available at the lua-users wiki.
## Thoughts on displaying tables in an intuitive way.
Lua's table data-structure is likely to be the most concise data structure ever
invented. (If not, please send me a link!) Lists, maps, objects, classes,
proxies, etc. This obviously brings about it some difficulty when attempting to
represent these tables. What do we want to highlight, and what do we choose to
avoid?
One notable issue is whether to show every key that a table answers (to lift
some Smalltalk terms) to, or to just display those it contains. That is, do we
think about __index in the table's metatable and what it returns, or do we
ignore __index? For cases where __index is a function, we cannot say
anything about the keys that the table answers to. If __index is a table, we
have a better idea, but it would be cluttered to display both types of keys side
by side.
Native representation: Lua's native representation includes the type and
address of the table. It allows for distinguishing between unique tables,
but won't tell us anything about the contents.
Omission: By representing tables as the pseudo-parsable {...}, it's
clear we are talking about a table. We disregard the ability to
distinguish between tables.
2A. If the table is empty, we could represent it as {}. But what if the table
has a metatable with __index defined? We could continue to represent it as
{}, but {...} would be more "honest".
Single-line: TODO
Multi-line: TODO
Columns: For some highly-regular structures, like lists of short strings,
giving each string it's own line would be too long, but formatting them as a
single-line list would be too cluttered. Thus we can take inspiration from
the classic ls unix tool, and place the output into columns, to help guide
the eyes.
Tabular: Other structures are formatted like actual tables of data, e.g. a
sequence of tuples, like one would see in an SQL database. For these
structures it's an obvious choice to align them based on the keys.
Pseudo-Tabular: Some structures are almost tabular, e.g. they are sequences
of tuples, but some of the tuples differ in their structure. For these
structures it's still useful to tabulate the keys that all tuples share. To
do this we should sort the key order descending by the number of tuples with
the key.
But what do we do about the the outlier keys? We can either justify the
entire table, and give specific spots for the outlier keys, thereby
significantly increasing the size of the table, or we can leave the table
unjustified, abandoning it's eye-guiding attributes.
Special cases: (Array-tree, Table-Tree, Linked-List, Predictive Sequences) TODO
# License # License

View File

@ -14,20 +14,20 @@ Setup is simple, use `pretty = require 'pretty'`, and you're good to go.
$ print(pretty( { 1, 2, 3 } )) $ print(pretty( { 1, 2, 3 } ))
{ 1, 2, 3 } { 1, 2, 3 }
> print(pretty( { hello = 'world', num = 42 } )) $ print(pretty( { hello = 'world', num = 42 } ))
{ {
num = 42 num = 42
hello = 'world' hello = 'world'
} }
> print(pretty( { abs = math.abs, max = math.max, some = function() end } )) $ print(pretty( { abs = math.abs, max = math.max, some = function() end } ))
{ {
abs = builtin function (x) ... end abs = builtin function (x) ... end
max = builtin function (x, ...) ... end max = builtin function (x, ...) ... end
some = function () ... end some = function () ... end
} }
> print(pretty( math.abs )) $ print(pretty( math.abs ))
builtin function (x) builtin function (x)
-- math.abs -- math.abs
-- Returns the absolute value of x -- Returns the absolute value of x