Jmaa/pretty
1
0
Fork 0
Code Actions

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

Browse Source
This commit is contained in:
Jon Michael Aanes 2024-07-10 21:06:50 +02:00
parent cee8894983
commit 3c32b09979
Signed by: Jmaa
SSH Key Fingerprint: SHA256:Ab0GfHGCblESJx7JRE4fj4bFy/KRpeLhi41y4pF3sNA
2 changed files with 26 additions and 161 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

183
README.md
View File

@ -2,42 +2,18 @@
<!--- 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
[pretty](index.html#) is an advanced pretty printer for [Lua](https://lua.org). [pretty](index.html#) is an advanced pretty printer for [Lua](https://lua.org).
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
data, and creating an output string utilizing and highlighting those patterns. data, and creating an output string utilizing and highlighting those patterns.
## Code Example ## Code Example
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.
``` ```
$ print(pretty( { 1, 2, 3 } )) $ print(pretty( { 1, 2, 3 } ))
{ 1, 2, 3 } { 1, 2, 3 }
@ -64,14 +40,8 @@ builtin function (x)
end end
``` ```
## Motivation ## Motivation
This project is the outcome of my frustration with existing pretty printers, and This project is the outcome of my frustration with existing pretty printers, and
a desire to expand upon the pretty printer I developed for a desire to expand upon the pretty printer I developed for
[Xenoterm](https://gitfub.space/takunomi/Xenoterm). The original Xenoterm pretty [Xenoterm](https://gitfub.space/takunomi/Xenoterm). The original Xenoterm pretty
@ -79,29 +49,16 @@ printer was much simpler than [pretty](index.html#) - and the current is even si
the enhancements I make, when compared to other pretty printers, inspired me to the enhancements I make, when compared to other pretty printers, inspired me to
create [pretty](index.html#). create [pretty](index.html#).
[pretty](index.html#) sorts it's priorities like so: [pretty](index.html#) sorts it's priorities like so:
1. Human readability. 1. Human readability.
1. Lua-compatible output. 1. Lua-compatible output.
1. Customization. 1. Customization.
I'd rather have good defaults than provide a ton of customization options. If an I'd rather have good defaults than provide a ton of customization options. If an
structure avoids easy representation in Lua, I'd rather extend the syntax, than structure avoids easy representation in Lua, I'd rather extend the syntax, than
lose the info. lose the info.
Another aspect where [pretty](index.html#) shines is in exploratory programming, when Another aspect where [pretty](index.html#) shines is in exploratory programming, when
attempting to avoid reliance on outside documentation. The amount of information attempting to avoid reliance on outside documentation. The amount of information
[pretty](index.html#) exposes varies by the data you are inspecting. If you're inspecting [pretty](index.html#) exposes varies by the data you are inspecting. If you're inspecting
@ -109,172 +66,97 @@ a list of functions, their function signatures are visible, but if you're
inspecting a single function, documentation and source location may appear if inspecting a single function, documentation and source location may appear if
available. available.
## Features ## Features
- Written in good-old pure-blood Lua, with support for PUC Lua 5.0+ and LuaJIT 2.0+. - 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": - Redefining what it means to be "human readable":
- Is multi-line centric, to aid readability. - Is multi-line centric, to aid readability.
- Indention and alignment of keys-value pairs. - Indention and alignment of keys-value pairs.
- Keys-value pairs are - Keys-value pairs are
alpha-numerically sorted by key [alpha-numerically](http://www.davekoelle.com/alphanum.html) sorted by key
type and thereafter alphabetically. type and thereafter alphabetically.
- The format and structure of output changes depending upon the input. Maps - The format and structure of output changes depending upon the input. Maps
appear differently to deeply nested tables to long sequences with short appear differently to deeply nested tables to long sequences with short
strings to short lists. strings to short lists.
- Uses the standard debug library to gain information about functions and - Uses the standard [debug](https://www.lua.org/manual/5.1/manual.html#5.9) library to gain information about functions and
other advanced structures. other advanced structures.
## Installation ## Installation
[pretty](index.html#) is loadable directly with [require](https://www.lua.org/manual/5.1/manual.html#pdf-require). Either clone or download this [pretty](index.html#) is loadable directly with [require](https://www.lua.org/manual/5.1/manual.html#pdf-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:
1. **You want [pretty](index.html#) in a specific project**: Place the [pretty](index.html#) folder
somewhere in your project, and [require](https://www.lua.org/manual/5.1/manual.html#pdf-require) it from one of your project files.
1. **You want [pretty](index.html#) on your system**: Place the [pretty](index.html#) folder such that
1. **You want pretty in a specific project**: Place the pretty folder
somewhere in your project, and require it from one of your project files.
1. **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](https://www.lua.org/manual/5.1/manual.html#pdf-require) it from anywhere.
## API Documentation ## API Documentation
[pretty](index.html#) exposes a single function, the [pretty](index.html#) function itself. It's function [pretty](index.html#) exposes a single function, the [pretty](index.html#) 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.
[pretty](index.html#) is sure to complain if you give it an unknown option, or if you give an [pretty](index.html#) is sure to complain if you give it an unknown option, or if you give an
option a bad value. option a bad value.
- `indent: string`: The string to indent with. Four spaces by default.
- indent: string: The string to indent with. Four spaces by default.
## TODO ## TODO
Tasks to be done before [pretty](index.html#) can be called version 1.0.0, in order of Tasks to be done before [pretty](index.html#) can be called version 1.0.0, in order of
priority: priority:
- [ ] Add dedicated unicode submodule, to handle some minor alignment and - [ ] Add dedicated unicode submodule, to handle some minor alignment and
character escaping issues. pretty should escape all malformed unicode character escaping issues. [pretty](index.html#) should escape all malformed unicode
sequences. sequences.
- [ ] Align numbers towards right for tabular views. - [ ] Align numbers towards right for tabular views.
- [ ] Add support for setmetatable, and exploring values in metatables. - [ ] Add support for [setmetatable](https://www.lua.org/manual/5.1/manual.html#pdf-setmetatable), and exploring values in metatables.
- [ ] Provide nice formatting for cdata datatype in LuaJIT. - [ ] Provide nice formatting for `cdata` datatype in LuaJIT.
- [ ] Find a better name than pretty. - [ ] Find a better name than [pretty](index.html#).
- [ ] Enhance internal structure some amount. See TODO markers in files. - [ ] Enhance internal structure some amount. See `TODO` markers in files.
It would be nice to have the following, but these are secondary: It would be nice to have the following, but these are secondary:
- [ ] Add option for colored output. Primarily syntax highlighting, but also - [ ] Add option for colored output. Primarily syntax highlighting, but also
BlueJ-style scope highlighting, with some faint [BlueJ-style](www.bluej.org/about.html) scope highlighting, with some faint
background colors. background colors.
- [ ] Expand on the comment output in output, for __tostring methods, and - [ ] Expand on the comment output in output, for `__tostring` methods, and
global namespaces like io or math. global namespaces like [io](https://www.lua.org/manual/5.1/manual.html#5.7) or [math](https://www.lua.org/manual/5.1/manual.html#5.6).
- [ ] Fit output within a predefined width limit. Default to 80. - [ ] Fit output within a predefined width limit. Default to 80.
- [ ] Look into tool for understanding complex structures with recursive - [ ] Look into tool for understanding complex structures with recursive
definitions. Whatever modes are thought up, they should be automatic modes, not definitions. Whatever modes are thought up, they should be automatic modes, not
an options. Should at least include modes for self-referential tables and an options. Should at least include modes for self-referential tables and
Directed-Acyclic-Graphs. Directed-Acyclic-Graphs.
## Alternative pretty printers ## Alternative pretty printers
[pretty](index.html#) is large, slow, and requires the debug library to work. It's not [pretty](index.html#) 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 designed for serialization purposes, nor is it concerned with offering the same
level of customization as other libraries do. level of customization as other libraries do.
If you want a sleek, fast, customizable or embeddable library, there are If you want a sleek, fast, customizable or embeddable library, there are
thankfully other options. thankfully other options.
- [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.
- inspect.lua: One of the classic debugging pretty printers. - [pluto](lua-users.org/wiki/PlutoLibrary): Can serialize arbitrary parts of
- 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 Lua, including functions, upvalues, and proper lexical scoping. Not written in
native Lua. native Lua.
- binser: Library for special purpose serialization. - [binser](github.com/bakpakin/binser): Library for special purpose serialization.
Even more are available at [the lua-users wiki](lua-users.org/wiki/TableSerialization). Even more are available at [the lua-users wiki](lua-users.org/wiki/TableSerialization).
## Thoughts on displaying tables in an intuitive way. ## Thoughts on displaying tables in an intuitive way.
Lua's table data-structure is likely to be the most concise data structure ever 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, invented. (If not, please send me a link!) Lists, maps, objects, classes,
proxies, etc. This obviously brings about it some difficulty when attempting to 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 represent these tables. What do we want to highlight, and what do we choose to
avoid? avoid?
One notable issue is whether to show every key that a table answers (to lift 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 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 think about `__index` in the table's metatable and what it returns, or do we
@ -283,24 +165,21 @@ 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 have a better idea, but it would be cluttered to display both types of keys side
by side. by side.
1. Native representation: Lua's native representation includes the type and 1. Native representation: Lua's native representation includes the type and
address of the table. It allows for distinguishing between unique tables, address of the table. It allows for distinguishing between unique tables,
but won't tell us anything about the contents. but won't tell us anything about the contents.
1. Omission: By representing tables as the pseudo-parsable {...}, it's 1. Omission: By representing tables as the pseudo-parsable `{...}`, it's
clear we are talking about a table. We disregard the ability to clear we are talking about a table. We disregard the ability to
distinguish between tables. distinguish between tables.
1. If the table is empty, we could represent it as {}. But what if the table 1. 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 has a metatable with `__index` defined? We could continue to represent it as
{}, but {...} would be more "honest". `{}`, but `{...}` would be more "honest".
1. Single-line: TODO 1. Single-line: TODO
1. Multi-line: TODO 1. Multi-line: TODO
1. Columns: For some highly-regular structures, like lists of short strings, 1. 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 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 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 classic `ls` unix tool, and place the output into columns, to help guide
the eyes. the eyes.
1. Tabular: Other structures are formatted like actual tables of data, e.g. a 1. 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 sequence of tuples, like one would see in an SQL database. For these
@ -316,18 +195,6 @@ by side.
unjustified, abandoning it's eye-guiding attributes. unjustified, abandoning it's eye-guiding attributes.
1. Special cases: (Array-tree, Table-Tree, Linked-List, Predictive Sequences) TODO 1. Special cases: (Array-tree, Table-Tree, Linked-List, Predictive Sequences) TODO
# License # License
``` ```

4
pretty.lua
View File

@ -1,6 +1,4 @@
--[[-- --[[-- # Pretty
# Pretty
`pretty` is an advanced pretty printer for [Lua](https://lua.org). It's primarily a `pretty` is an advanced pretty printer for [Lua](https://lua.org). 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