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
|
## Introduction
|
||||||
|
|
||||||
`pretty` is an advanced pretty printer for [Lua](lua.org) aiming primarily for
|
`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
|
creating an output string utilizing and highlighting those patterns. Thus it's
|
||||||
a primarily a debugging tool, not a speedy serialization tool.
|
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
|
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 default Xenoterm pretty
|
[Xenoterm](https://gitfub.space/takunomi/Xenoterm). The default Xenoterm pretty
|
||||||
|
@ -33,7 +19,7 @@ other pretty printers.
|
||||||
|
|
||||||
1. Human readability.
|
1. Human readability.
|
||||||
2. Lua-compatible output.
|
2. Lua-compatible output.
|
||||||
3. Customization support.
|
3. Customization.
|
||||||
|
|
||||||
I'd rather have good defaults than provide a ton of customization options. And
|
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
|
if some structure cannot be represented in Lua, I will rather extend the
|
||||||
|
@ -48,8 +34,8 @@ available.
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- Written in good-old pureblood Lua, with support for PUC Lua 5.0 - 5.3 and
|
- Written in good-old pureblood Lua, with support for PUC Lua 5.0+ and
|
||||||
LuaJIT 2.0 and up.
|
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 readablitiy.
|
* Is multi-line centric, to aid readablitiy.
|
||||||
* Indention and alignment of keys-value pairs.
|
* Indention and alignment of keys-value pairs.
|
||||||
|
@ -61,6 +47,24 @@ available.
|
||||||
* Uses the standard `debug` library to gain information about functions
|
* Uses the standard `debug` library to gain information about functions
|
||||||
and other advanced structures.
|
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
|
## Performance
|
||||||
|
|
||||||
As specified in the introduction, `pretty` is not a performance oriented
|
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:
|
I'm looking into implementing following features:
|
||||||
|
|
||||||
- Improve display of medium-long lists with short elements better. One option
|
- Improve display of medium-long lists with short elements. One option is
|
||||||
would be to implement something analog to the default results of `ls` on
|
something analog to the default results of `ls` on Linux.
|
||||||
Linux.
|
|
||||||
- Add support for `setmetatable`, and exploring the values accessible through
|
- Add support for `setmetatable`, and exploring the values accessible through
|
||||||
it.
|
it.
|
||||||
- Nice formatting for `cdata` datatype in LuaJIT.
|
- Provide nice formatting for `cdata` datatype in LuaJIT.
|
||||||
- Add possibility of comments in output, for stuff like `__tostring` methods,
|
- Expand on the comment output in output, for `__tostring` methods, and global
|
||||||
and global namespaces like `io` or `math`.
|
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
|
- Better support upvalues for in functions. Complete support is impossible
|
||||||
without traversing the original code or inspecting the intermediate
|
without traversing the original code or inspecting the intermediate
|
||||||
representation, due to lexical scoping. (Pluto does it, but it's written in
|
representation, due to lexical scoping. (Pluto does it, but it's written in
|
||||||
C.)
|
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
|
## Other pretty printers
|
||||||
|
|
||||||
|
|
|
@ -6,8 +6,12 @@ SUITE:setEnviroment{
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
local HAS_ADV_GETLOCAL = not not debug.getinfo(1, 'u').nparams -- Lua 5.1 compat
|
-- Compat
|
||||||
if not loadstring then loadstring = load end -- Lua 5.3 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)
|
local function format_test (t)
|
||||||
if t.adv_getlocal and not HAS_ADV_GETLOCAL then return end
|
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}',
|
expect = '{\n abs = function (x) ... end,\n max = function (a, b) ... end\n}',
|
||||||
}
|
}
|
||||||
|
|
||||||
|
if HAS_UNICODE_IDEN then
|
||||||
format_test {
|
format_test {
|
||||||
name = 'Functions with unicode-named parameters should align nicely',
|
name = 'Functions with unicode-named parameters should align nicely',
|
||||||
adv_getlocal = true,
|
adv_getlocal = true,
|
||||||
input = { a = function (ψ) return ψ end,
|
input = loadstring 'return { a = function (ψ) return ψ end, b = function (a) return a end }' (),
|
||||||
b = function (a) return a end
|
|
||||||
},
|
|
||||||
expect = '{\n a = function (ψ) ... end\n b = function (a) ... end\n}',
|
expect = '{\n a = function (ψ) ... end\n b = function (a) ... end\n}',
|
||||||
}
|
}
|
||||||
|
end
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
-- Closure creation
|
-- 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
|
-- Compat
|
||||||
if not loadstring then loadstring = load end -- Lua 5.3 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)
|
local function format_test (t)
|
||||||
if t.longterm then return end
|
if t.longterm then return end
|
||||||
|
@ -220,11 +224,13 @@ format_test {
|
||||||
expect = '{ a = { 1, 2, 3 }, b = { 4, 5, 6 } }',
|
expect = '{ a = { 1, 2, 3 }, b = { 4, 5, 6 } }',
|
||||||
}
|
}
|
||||||
|
|
||||||
|
if HAS_UNICODE_IDEN then
|
||||||
format_test {
|
format_test {
|
||||||
name = 'Unicode characters can be used as string keys in tables',
|
name = 'Unicode characters can be used as string keys in tables',
|
||||||
input = { a = 1, ψ = 2 },
|
input = loadstring 'return { a = 1, ψ = 2 }' (),
|
||||||
expect = '{ a = 1, ψ = 2 }',
|
expect = '{ a = 1, ψ = 2 }',
|
||||||
}
|
}
|
||||||
|
end
|
||||||
|
|
||||||
format_test {
|
format_test {
|
||||||
input = { [100] = 'Hi', [300] = 'Hello' },
|
input = { [100] = 'Hi', [300] = 'Hello' },
|
||||||
|
@ -302,15 +308,17 @@ format_test {
|
||||||
expect = '{\n { a = \'hello\', b = \'hi\' },\n { a = \'hi\', b = \'hello\' }\n}',
|
expect = '{\n { a = \'hello\', b = \'hi\' },\n { a = \'hi\', b = \'hello\' }\n}',
|
||||||
}
|
}
|
||||||
|
|
||||||
|
if HAS_UNICODE_IDEN then
|
||||||
format_test {
|
format_test {
|
||||||
name = 'Proper alignment when using unicode characters as keys',
|
name = 'Proper alignment when using unicode characters as keys',
|
||||||
input = {
|
input = loadstring [[return {
|
||||||
djævle = 'dyr?',
|
djævle = 'dyr?',
|
||||||
europa = 'måne',
|
europa = 'måne',
|
||||||
øå = 'en å på en ø?',
|
øå = 'en å på en ø?',
|
||||||
},
|
}]] (),
|
||||||
expect = '{\n djævle = \'dyr?\',\n europa = \'måne\',\n øå = \'en å på en ø?\'\n}',
|
expect = '{\n djævle = \'dyr?\',\n europa = \'måne\',\n øå = \'en å på en ø?\'\n}',
|
||||||
}
|
}
|
||||||
|
end
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
-- Table recursion
|
-- Table recursion
|
||||||
|
@ -353,7 +361,7 @@ end
|
||||||
|
|
||||||
-- TODO: Add more advanced understanding of cdata.
|
-- TODO: Add more advanced understanding of cdata.
|
||||||
|
|
||||||
if type(jit) == 'table' then
|
if HAS_JIT_LIBRARY then
|
||||||
|
|
||||||
local ffi = require('ffi')
|
local ffi = require('ffi')
|
||||||
ffi.cdef[[
|
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)
|
local function format_test (t)
|
||||||
SUITE:addTest(t.name or t.expect:gsub('[ \n\t]+', ' '), function ()
|
SUITE:addTest(t.name or t.expect:gsub('[ \n\t]+', ' '), function ()
|
||||||
assert_equal(t.expect, pretty(t.input, t.options))
|
assert_equal(t.expect, pretty(t.input, t.options))
|
||||||
|
@ -66,11 +73,13 @@ format_test {
|
||||||
expect = '{ 1, nil, 3 }',
|
expect = '{ 1, nil, 3 }',
|
||||||
}
|
}
|
||||||
|
|
||||||
|
if HAS_UNICODE_IDEN then
|
||||||
format_test {
|
format_test {
|
||||||
name = 'øl kommer tydeligt før ål',
|
name = 'øl kommer tydeligt før ål',
|
||||||
input = { øl = 1, ål = 2 },
|
input = loadstring 'return { øl = 1, ål = 2 }' (),
|
||||||
expect = '{ øl = 1, ål = 2 }',
|
expect = '{ øl = 1, ål = 2 }',
|
||||||
}
|
}
|
||||||
|
end
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
-- Alphanum Algorithm Example 1
|
-- Alphanum Algorithm Example 1
|
||||||
|
|
Loading…
Reference in New Issue
Block a user