Updated README and fixed some test issues with lua 5.1
This commit is contained in:
parent
f4d6e301a1
commit
3d6c7dbfbc
63
README.md
63
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
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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[[
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue
Block a user