diff --git a/README.md b/README.md index 7cfe563..f4cf344 100644 --- a/README.md +++ b/README.md @@ -2,42 +2,18 @@ -# - - - - - # Pretty - - - [pretty](index.html#) 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 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. - - - ``` $ print(pretty( { 1, 2, 3 } )) { 1, 2, 3 } @@ -64,14 +40,8 @@ builtin function (x) end ``` - - - ## Motivation - - - 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](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 create [pretty](index.html#). - - - [pretty](index.html#) sorts it's priorities like so: - - - 1. Human readability. 1. Lua-compatible output. 1. Customization. - - - - 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 lose the info. - - - Another aspect where [pretty](index.html#) shines is in exploratory programming, when 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 @@ -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 available. - - - ## Features - - - - 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": - Is multi-line centric, to aid readability. - Indention and alignment of keys-value pairs. - Keys-value pairs are - alpha-numerically sorted by key + [alpha-numerically](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 +- 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. - - - - ## 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 repository. Where you place it, depends upon what you want to do: - - - -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 +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 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 - - - [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` must be a table. - - - - - - [pretty](index.html#) 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. - - - - +- `indent: string`: The string to indent with. Four spaces by default. ## TODO - - - Tasks to be done before [pretty](index.html#) can be called version 1.0.0, in order of priority: - - - - [ ] 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. - [ ] 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. - - - - +- [ ] 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. +- [ ] Find a better name than [pretty](index.html#). +- [ ] 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 scope highlighting, with some faint + [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. +- [ ] Expand on the comment output in output, for `__tostring` methods, and + 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. - [ ] 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](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 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 +- [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. +- [pluto](lua-users.org/wiki/PlutoLibrary): Can serialize arbitrary parts of Lua, including functions, upvalues, and proper lexical scoping. Not written in 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). - - - ## 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 @@ -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 by side. - - - 1. 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. -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 distinguish between tables. -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 - {}, but {...} would be more "honest". +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 + `{}`, but `{...}` would be more "honest". 1. Single-line: TODO 1. Multi-line: TODO 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 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. 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 @@ -316,18 +195,6 @@ by side. unjustified, abandoning it's eye-guiding attributes. 1. Special cases: (Array-tree, Table-Tree, Linked-List, Predictive Sequences) TODO - - - - - - - - - - - - # License ``` diff --git a/pretty.lua b/pretty.lua index c01a940..ccb6706 100644 --- a/pretty.lua +++ b/pretty.lua @@ -1,6 +1,4 @@ ---[[-- - -# Pretty +--[[-- # Pretty `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