From 762b8f3d200381c581c6769b328eb18884ef5919 Mon Sep 17 00:00:00 2001 From: Jon Michael Aanes Date: Sat, 22 Jul 2017 14:44:24 +0200 Subject: [PATCH] Updated readme, and a bit of commentary. --- README.md | 49 ++++++++++++++++++++++++------------------------- function.lua | 10 ++++++++-- pretty.lua | 6 ++---- pstring.lua | 4 +++- 4 files changed, 37 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 3938999..8628f59 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,13 @@ # Pretty # -`pretty` is an advanced pretty printer for [Lua](lua.org) aiming primarily for -human readability. It does this by looking for patterns in the input data, and -creating an output string utilizing and highlighting those patterns. Thus it's -a primarily a debugging tool, not a speedy serialization tool. +`pretty` is an advanced pretty printer for [Lua](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, just `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 } )) @@ -79,24 +78,27 @@ available. ## Installation -TODO +`pretty` is loadable directly with `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. +2. **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 + `/usr/local/share/lua/5.1/`. Now you can `require` it from anywhere. ## API Documentation -TODO +`pretty` exposes a single function, the `pretty` function itself. It's function +signature is `pretty(value, options)`. `value` can be any Lua value. `options` +must be a table. -## Tests +### List of options -TODO +`pretty` is sure to complain if you give it an unknown option, or if you give an +option a bad value. -## Performance - -As specified in the introduction, `pretty` is not a performance oriented -library. Expected usage is in error conditions and debugging, not in tight -inner loops. - -Don't use `pretty.lua` if you want fast serialization. Use one of the pretty -printers specified below. +- `indent: string`: The string to indent with. Four spaces (` `) by default. ## TODO @@ -108,23 +110,20 @@ I'm looking into implementing following features: - Provide nice formatting for `cdata` datatype in LuaJIT. - Expand on the comment output in output, for `__tostring` methods, and global namespaces like `io` or `math`. -- Look into using concat operation to improve appearance of overly long - non-breaking strings. Attempt to break near whitespace. - Attempt to fit output within a predefined width limit. Default to 80. - Add option for colored output. Primarily syntax highlighting, but also [BlueJ-style](www.bluej.org/about.html) scope highlighting, with some faint background colors. -- Look more into `string.dump` in the core library. - Find a better name than `pretty`. -## Other pretty printers +## 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 other -options. Lua has a large library of pretty printers and serialization libraries: +If you want a sleek, fast, customizable or embeddable library, there are +thankfully other options. - [inspect.lua](github.com/kikito/inspect.lua): One of the classic debugging pretty printers. @@ -136,12 +135,12 @@ options. Lua has a large library of pretty printers and serialization libraries: - [binser](github.com/bakpakin/binser): Library for special purpose serialization. -Find others at [the lua-users wiki](lua-users.org/wiki/TableSerialization). +Even more are available at [the lua-users wiki](lua-users.org/wiki/TableSerialization). ## Contact The author is available at `jonjmaa (at) gmail.com`. Be sure to send an email if -you have ideas for improvements, find an issue, or even an unintuitive result. +you have ideas for improvements, or find an issue. ## License diff --git a/function.lua b/function.lua index b111ad2..a052c83 100644 --- a/function.lua +++ b/function.lua @@ -111,7 +111,7 @@ local function get_function_info (f) if info.source:sub(1,1) == '=' then info.defined_how = 'C' elseif info.source:sub(1,1) == '@' then info.defined_how = 'file' - elseif info.source:find'^%w+.lua$' then info.defined_how = 'file' -- XXX: Hotfix for Love2d boot.lua issue. + elseif info.source:find'^%w+.lua$' then info.defined_how = 'file' -- Hotfix for Love2d boot.lua issue. else info.defined_how = 'string' end @@ -233,6 +233,8 @@ local function width_of_strings_in_l (l, start_i, end_i) end local function add_indent_to_string (str, indent) + -- Indents `str` by `indent`. + assert(type(str) == 'string') assert(type(indent) == 'string') @@ -240,12 +242,16 @@ local function add_indent_to_string (str, indent) end local function wrap_text (text, max_width) + -- Creates a wrapped version of given `text`, with no lines longer than + -- `max_width`. Splits only at whitespace. + + -- TODO: Fix this. + local l, i, last_i = {}, max_width, 1 repeat if text:sub(i, i) == ' ' then l[#l+1], last_i, i = text:sub(last_i, i - 1), i + 1, i + max_width elseif i <= last_i then - -- TODO: Make sure this part works. i = text:find(' ', last_i) or #text else i = i - 1 diff --git a/pretty.lua b/pretty.lua index a91ad27..b8bc2b1 100644 --- a/pretty.lua +++ b/pretty.lua @@ -393,8 +393,6 @@ local TABLE_TYPE_TO_PAIR_FORMAT = { -- Formatting tables local function format_table (t, depth, l) - -- TODO: Add more nuanced formatting. - -- Error Checking assert(type(t) == 'table') assert(type(depth) == 'number' and type(l) == 'table') @@ -518,12 +516,12 @@ setmetatable(StringBuilder, { local DEBUG_OPTION_USED = { } local KNOWN_OPTIONS = { - _table_addr_comment = { type = 'boolean', default = false, debug = 'debug' }, + _table_addr_comment = { type = 'boolean', default = false, debug = 'debug' }, -- TODO: Maybe automatically display table address when depth = 0? indent = { type = 'string', default = ' ' }, max_depth = { type = 'number', default = math.huge }, short_builtins = { type = 'boolean', default = false }, -- TODO: Outphase this. Rather automatically use the short versions in places where it would be strange to find the function, like keys, etc. - recursion = { type = 'string', default = 'ignore', accepted = {['ignore'] = true, ['marked'] = true, ['revisit'] = true} }, + recursion = { type = 'string', default = 'ignore', accepted = {['ignore'] = true, ['marked'] = true, ['revisit'] = true} }, -- TODO: Completely depricate this option. I do not like it. } local function ensure_that_all_options_are_known (input_options) diff --git a/pstring.lua b/pstring.lua index da7f12f..df7921f 100644 --- a/pstring.lua +++ b/pstring.lua @@ -4,7 +4,7 @@ --[=[ Thoughts on displaying strings in the useful ways. -TODO +Thoughts are TODO --]=] @@ -135,6 +135,8 @@ local function format_concatted_string (str, depth, l) -- Cuts the string up into smaller individual substrings, each Concatted -- together. Is uglier compared to longform, but is at least idempotent. + -- TODO: Attempt to cut near whitespace? + -- Error checking assert( type(str) == 'string' ) assert(type(depth) == 'number' and type(l) == 'table')