mirror of
https://github.com/kikito/inspect.lua.git
synced 2024-12-15 14:34:21 +00:00
updated readme with wishes
This commit is contained in:
parent
d07147ed54
commit
9ce951f6af
162
README.md
162
README.md
@ -10,72 +10,101 @@ The objective here is human understanding (i.e. for debugging), not serializatio
|
||||
Examples of use
|
||||
===============
|
||||
|
||||
`inspect` has the following declaration: `str = inspect(value, <options>)`.
|
||||
`inspect` has the following declaration: `local str = inspect(value, <options>)`.
|
||||
|
||||
`value` can be any Lua value. `inspect` transforms simple types (like strings or numbers) into strings. Tables, on the other
|
||||
hand, are rendered in a way a human can understand.
|
||||
`value` can be any Lua value.
|
||||
|
||||
`inspect` transforms simple types (like strings or numbers) into strings.
|
||||
|
||||
```lua
|
||||
assert(inspect(1) == "1")
|
||||
assert(inspect("Hello") == '"Hello"')
|
||||
```
|
||||
|
||||
Tables, on the other hand, are rendered in a way a human can read easily.
|
||||
|
||||
"Array-like" tables are rendered horizontally:
|
||||
|
||||
inspect({1,2,3,4}) == "{ 1, 2, 3, 4 }"
|
||||
```lua
|
||||
assert(inspect({1,2,3,4}) == "{ 1, 2, 3, 4 }")
|
||||
```
|
||||
|
||||
"dictionary-like" tables are rendered with one element per line:
|
||||
"Dictionary-like" tables are rendered with one element per line:
|
||||
|
||||
inspect({a=1,b=2}) == [[{
|
||||
```lua
|
||||
assert(inspect({a=1,b=2}) == [[{
|
||||
a = 1,
|
||||
b = 2
|
||||
}]]
|
||||
}]])
|
||||
```
|
||||
|
||||
The keys will be sorted alphanumerically when possible.
|
||||
|
||||
"Hybrid" tables will have the array part on the first line, and the dictionary part just below them:
|
||||
|
||||
inspect({1,2,3,b=2,a=1}) == [[{ 1, 2, 3,
|
||||
```lua
|
||||
assert(inspect({1,2,3,b=2,a=1}) == [[{ 1, 2, 3,
|
||||
a = 1,
|
||||
b = 2
|
||||
}]]
|
||||
}]])
|
||||
```
|
||||
|
||||
Tables can be nested, and will be indented with two spaces per level.
|
||||
Subtables are indented with two spaces per level.
|
||||
|
||||
inspect({a={b=2}}) == [[{
|
||||
```lua
|
||||
assert(inspect({a={b=2}}) == [[{
|
||||
a = {
|
||||
b = 2
|
||||
}
|
||||
}]]
|
||||
}]])
|
||||
```
|
||||
|
||||
Functions, userdata and any other custom types from Luajit are simply as `<function x>`, `<userdata x>`, etc.:
|
||||
|
||||
inspect({ f = print, ud = some_user_data, thread = a_thread} ) == [[{
|
||||
```lua
|
||||
assert(inspect({ f = print, ud = some_user_data, thread = a_thread} ) == [[{
|
||||
f = <function 1>,
|
||||
u = <userdata 1>,
|
||||
thread = <thread 1>
|
||||
}]])
|
||||
```
|
||||
|
||||
If the table has a metatable, inspect will include it at the end, in a special field called `<metatable>`:
|
||||
|
||||
inspect(setmetatable({a=1}, {b=2}) == [[{
|
||||
```lua
|
||||
assert(inspect(setmetatable({a=1}, {b=2}) == [[{
|
||||
a = 1
|
||||
<metatable> = {
|
||||
b = 2
|
||||
}
|
||||
}]])
|
||||
}]]))
|
||||
```
|
||||
|
||||
`inspect` can handle tables with loops inside them. It will print `<id>` right before the table is printed out the first time, and replace the whole table with `<table id>` from then on, preventing infinite loops.
|
||||
|
||||
a = {1, 2}
|
||||
b = {3, 4, a}
|
||||
```lua
|
||||
local a = {1, 2}
|
||||
local b = {3, 4, a}
|
||||
a[3] = b -- a references b, and b references a
|
||||
inspect(a) = "<1>{ 1, 2, { 3, 4, <table 1> } }"
|
||||
assert(inspect(a) == "<1>{ 1, 2, { 3, 4, <table 1> } }")
|
||||
```
|
||||
|
||||
Notice that since both `a` appears more than once in the expression, it is prefixed by `<1>` and replaced by `<table 1>` every time it appears later on.
|
||||
|
||||
### options.depth
|
||||
### options
|
||||
|
||||
`inspect`'s second parameter allows controlling the maximum depth that will be printed out. When the max depth is reached, it'll just return `{...}`:
|
||||
`inspect` has a second parameter, called `options`. It is not mandatory, but when it is provided, it must be a table.
|
||||
|
||||
#### options.depth
|
||||
|
||||
`options.depth` sets the maximum depth that will be printed out.
|
||||
When the max depth is reached, `inspect` will stop parsing tables and just return `{...}`:
|
||||
|
||||
```lua
|
||||
|
||||
local t5 = {a = {b = {c = {d = {e = 5}}}}}
|
||||
|
||||
inspect(t5, {depth = 4}) == [[{
|
||||
assert(inspect(t5, {depth = 4}) == [[{
|
||||
a = {
|
||||
b = {
|
||||
c = {
|
||||
@ -83,17 +112,102 @@ Notice that since both `a` appears more than once in the expression, it is prefi
|
||||
}
|
||||
}
|
||||
}
|
||||
}]]
|
||||
}]])
|
||||
|
||||
inspect(t5, {depth = 2}) == [[{
|
||||
assert(inspect(t5, {depth = 2}) == [[{
|
||||
a = {
|
||||
b = {...}
|
||||
}
|
||||
}]])
|
||||
|
||||
```
|
||||
|
||||
`options.depth` defaults to infinite (`math.huge`).
|
||||
|
||||
### options.filter
|
||||
### options.process
|
||||
|
||||
`options.process` is a function which allow altering the passed object before transforming it into a string.
|
||||
A typical way to use it would be to remove certain values so that they don't appear at all.
|
||||
|
||||
`options.process` has the following signature:
|
||||
|
||||
``` lua
|
||||
local processed_item = function(item, path)
|
||||
```
|
||||
|
||||
* `item` is either a key or a value on the table, or any of its subtables
|
||||
* `path` is an array-like table built with all the keys that have been used to reach `item`, from the root.
|
||||
* For values, it is just a regular list of keys. For example, to reach the 1 in `{a = {b = 1}}`, the `path`
|
||||
will be `{'a', 'b'}`
|
||||
* For keys, a special value called `<key>` is inserted. For example, to reach the `c` in `{a = {b = {c = 1}}}`,
|
||||
the path will be `{'a', 'b', 'c', '<key>' }`
|
||||
* For metatables, a special value called `<metatable>` is inserted. For `{a = {b = 1}}}`, the path
|
||||
`{'a', 'b', '<metatable>'}` means "the metatable of the table `{b = 1}`".
|
||||
* `processed_item` is the value returned by `options.process`. If it is equal to `item`, then the inspected
|
||||
table will look unchanged. If it is different, then the table will look different; most notably, if it's `nil`,
|
||||
the item will dissapear on the inspected table.
|
||||
|
||||
#### Examples
|
||||
|
||||
Remove a particular metatable from the result:
|
||||
|
||||
``` lua
|
||||
local t = {1,2,3}
|
||||
local mt = {b = 2}
|
||||
setmetatable(t, mt)
|
||||
|
||||
local remove_mt = function(item)
|
||||
if item ~= mt then return item end
|
||||
end
|
||||
|
||||
-- mt does not appear
|
||||
assert(inspect(t, {process = remove_mt}) == "{ 1, 2, 3 }")
|
||||
```
|
||||
|
||||
The previous exaple only works for a particular metatable. If you want to make *all* metatables, you can use `path`:
|
||||
|
||||
``` lua
|
||||
local t, mt = ... -- (defined as before)
|
||||
|
||||
local remove_all_metatables = function(item, path)
|
||||
if path[#path] ~= '<metatable>' then return item end
|
||||
end
|
||||
|
||||
-- Removes all metatables
|
||||
assert(inspect(t, {process = remove_mt}) == "{ 1, 2, 3 }")
|
||||
```
|
||||
|
||||
Filter a value:
|
||||
|
||||
```lua
|
||||
local anonymize_password = function(item, path)
|
||||
if path[#path] == 'password' then return "XXXX" end
|
||||
return item
|
||||
end
|
||||
|
||||
local info = {user = 'peter', password = 'secret'}
|
||||
|
||||
assert(inspect(info, {process = anonymize_password}) == [[{
|
||||
password = "XXXX",
|
||||
user = "peter"
|
||||
}]])
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Sometimes it might be convenient to "filter out" some parts of the output. The `options.filter` option can do that.
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user