diff --git a/README.md b/README.md index 26e043c..88099f1 100644 --- a/README.md +++ b/README.md @@ -4,24 +4,10 @@ ## Introduction `pretty` is an advanced pretty printer for [Lua](lua.org) aiming primarily for -human readability. This is done by looking for patterns in the input data, and +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. -Sometimes just aligning elements are enough to easy the burden on the eyes. -Contrast the two following pieces of code: - -```lua - bad = { - a = 'hello world', - hello = 'hi' - } - good = { - a = 'hello world', - hello = 'hi' - } -``` - 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 default Xenoterm pretty @@ -33,7 +19,7 @@ other pretty printers. 1. Human readability. 2. Lua-compatible output. -3. Customization support. +3. Customization. I'd rather have good defaults than provide a ton of customization options. And if some structure cannot be represented in Lua, I will rather extend the @@ -48,8 +34,8 @@ available. ## Features -- Written in good-old pureblood Lua, with support for PUC Lua 5.0 - 5.3 and - LuaJIT 2.0 and up. +- Written in good-old pureblood 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 readablitiy. * Indention and alignment of keys-value pairs. @@ -61,6 +47,24 @@ available. * Uses the standard `debug` library to gain information about functions and other advanced structures. +## Readability Methods + +Here we outline the methods we use when formatting. + +The simplest method is to align keys, equals-sign and values, of a table. Thus +we separate them, and make it easier to distinguish them from each. Compare: + +```lua + bad = { + a = 'hello world', + hello = 'hi' + } + good = { + a = 'hello world', + hello = 'hi' + } +``` + ## Performance As specified in the introduction, `pretty` is not a performance oriented @@ -74,24 +78,23 @@ printers specified below. I'm looking into implementing following features: -- Improve display of medium-long lists with short elements better. One option - would be to implement something analog to the default results of `ls` on - Linux. +- Improve display of medium-long lists with short elements. One option is + something analog to the default results of `ls` on Linux. - Add support for `setmetatable`, and exploring the values accessible through it. -- Nice formatting for `cdata` datatype in LuaJIT. -- Add possibility of comments in output, for stuff like `__tostring` methods, - and global namespaces like `io` or `math`. +- 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. +- Find a better name than `pretty`. +- Add options for colored output, and allow custom formatting. +- Look more into `string.dump` in the core library. - Better support upvalues for in functions. Complete support is impossible without traversing the original code or inspecting the intermediate representation, due to lexical scoping. (Pluto does it, but it's written in C.) -- Look more into `string.dump` in the core library. -- Look into using concat operation to improve appearance of overly long - non-breaking strings. Maybe even attempt to break near whitespace. -- Attempt to fit output within a predefined width limit. Default to 80(?) -- Find a better name than `pretty`. -- Add options for colored output, and allow custom formatting. ## Other pretty printers diff --git a/test/test_function.lua b/test/test_function.lua index 92c3fa3..4da72c4 100644 --- a/test/test_function.lua +++ b/test/test_function.lua @@ -6,8 +6,12 @@ SUITE:setEnviroment{ -------------------------------------------------------------------------------- -local HAS_ADV_GETLOCAL = not not debug.getinfo(1, 'u').nparams -- Lua 5.1 compat -if not loadstring then loadstring = load end -- Lua 5.3 compat +-- Compat +if not loadstring then loadstring = load end -- Lua 5.3 compat +local HAS_ADV_GETLOCAL = not not debug.getinfo(1, 'u').nparams -- Lua 5.1 compat +local HAS_UNICODE_IDEN = not not loadstring 'local ϕ = 1; return ϕ' -- Lua 5.1 compat +local HAS_JIT_LIBRARY = type(rawget(_G, 'jit')) == 'table' -- Non-LuaJIT compat +-- local function format_test (t) if t.adv_getlocal and not HAS_ADV_GETLOCAL then return end @@ -331,14 +335,14 @@ format_test { expect = '{\n abs = function (x) ... end,\n max = function (a, b) ... end\n}', } -format_test { - name = 'Functions with unicode-named parameters should align nicely', - adv_getlocal = true, - input = { a = function (ψ) return ψ end, - b = function (a) return a end - }, - expect = '{\n a = function (ψ) ... end\n b = function (a) ... end\n}', -} +if HAS_UNICODE_IDEN then + format_test { + name = 'Functions with unicode-named parameters should align nicely', + adv_getlocal = true, + input = loadstring 'return { a = function (ψ) return ψ end, b = function (a) return a end }' (), + expect = '{\n a = function (ψ) ... end\n b = function (a) ... end\n}', + } +end -------------------------------------------------------------------------------- -- Closure creation diff --git a/test/test_pretty.lua b/test/test_pretty.lua index 306223c..4428a20 100644 --- a/test/test_pretty.lua +++ b/test/test_pretty.lua @@ -12,8 +12,12 @@ Approximate strings not similar enough: -------------------------------------------------------------------------------- -local HAS_ADV_GETLOCAL = not not debug.getinfo(1, 'u').nparams -- Lua 5.1 compat -if not loadstring then loadstring = load end -- Lua 5.3 compat +-- Compat +if not loadstring then loadstring = load end -- Lua 5.3 compat +local HAS_ADV_GETLOCAL = not not debug.getinfo(1, 'u').nparams -- Lua 5.1 compat +local HAS_UNICODE_IDEN = not not loadstring 'local ϕ = 1; return ϕ' -- Lua 5.1 compat +local HAS_JIT_LIBRARY = type(rawget(_G, 'jit')) == 'table' -- Non-LuaJIT compat +-- local function format_test (t) if t.longterm then return end @@ -220,11 +224,13 @@ format_test { expect = '{ a = { 1, 2, 3 }, b = { 4, 5, 6 } }', } -format_test { - name = 'Unicode characters can be used as string keys in tables', - input = { a = 1, ψ = 2 }, - expect = '{ a = 1, ψ = 2 }', -} +if HAS_UNICODE_IDEN then + format_test { + name = 'Unicode characters can be used as string keys in tables', + input = loadstring 'return { a = 1, ψ = 2 }' (), + expect = '{ a = 1, ψ = 2 }', + } +end format_test { input = { [100] = 'Hi', [300] = 'Hello' }, @@ -302,15 +308,17 @@ format_test { expect = '{\n { a = \'hello\', b = \'hi\' },\n { a = \'hi\', b = \'hello\' }\n}', } -format_test { - name = 'Proper alignment when using unicode characters as keys', - input = { - djævle = 'dyr?', - europa = 'måne', - øå = 'en å på en ø?', - }, - expect = '{\n djævle = \'dyr?\',\n europa = \'måne\',\n øå = \'en å på en ø?\'\n}', -} +if HAS_UNICODE_IDEN then + format_test { + name = 'Proper alignment when using unicode characters as keys', + input = loadstring [[return { + djævle = 'dyr?', + europa = 'måne', + øå = 'en å på en ø?', + }]] (), + expect = '{\n djævle = \'dyr?\',\n europa = \'måne\',\n øå = \'en å på en ø?\'\n}', + } +end -------------------------------------------------------------------------------- -- Table recursion @@ -353,7 +361,7 @@ end -- TODO: Add more advanced understanding of cdata. -if type(jit) == 'table' then +if HAS_JIT_LIBRARY then local ffi = require('ffi') ffi.cdef[[ diff --git a/test/test_sorting.lua b/test/test_sorting.lua index 8fcf1b4..583fd71 100644 --- a/test/test_sorting.lua +++ b/test/test_sorting.lua @@ -6,6 +6,13 @@ SUITE:setEnviroment{ -------------------------------------------------------------------------------- +-- Compat +if not loadstring then loadstring = load end -- Lua 5.3 compat +local HAS_ADV_GETLOCAL = not not debug.getinfo(1, 'u').nparams -- Lua 5.1 compat +local HAS_UNICODE_IDEN = not not loadstring 'local ϕ = 1; return ϕ' -- Lua 5.1 compat +local HAS_JIT_LIBRARY = type(rawget(_G, 'jit')) == 'table' -- Non-LuaJIT compat +-- + local function format_test (t) SUITE:addTest(t.name or t.expect:gsub('[ \n\t]+', ' '), function () assert_equal(t.expect, pretty(t.input, t.options)) @@ -66,11 +73,13 @@ format_test { expect = '{ 1, nil, 3 }', } -format_test { - name = 'øl kommer tydeligt før ål', - input = { øl = 1, ål = 2 }, - expect = '{ øl = 1, ål = 2 }', -} +if HAS_UNICODE_IDEN then + format_test { + name = 'øl kommer tydeligt før ål', + input = loadstring 'return { øl = 1, ål = 2 }' (), + expect = '{ øl = 1, ål = 2 }', + } +end -------------------------------------------------------------------------------- -- Alphanum Algorithm Example 1