You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
251 lines
6.7 KiB
251 lines
6.7 KiB
inspect.lua
|
|
===========
|
|
|
|
[](https://travis-ci.org/kikito/inspect.lua)
|
|
|
|
This library transforms any Lua value into a human-readable representation. It is especially useful for debugging errors in tables.
|
|
|
|
The objective here is human understanding (i.e. for debugging), not serialization or compactness.
|
|
|
|
Examples of use
|
|
===============
|
|
|
|
`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.
|
|
|
|
```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:
|
|
|
|
```lua
|
|
assert(inspect({1,2,3,4}) == "{ 1, 2, 3, 4 }")
|
|
```
|
|
|
|
"Dictionary-like" tables are rendered with one element per line:
|
|
|
|
```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:
|
|
|
|
```lua
|
|
assert(inspect({1,2,3,b=2,a=1}) == [[{ 1, 2, 3,
|
|
a = 1,
|
|
b = 2
|
|
}]])
|
|
```
|
|
|
|
Subtables are indented with two spaces per level.
|
|
|
|
```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.:
|
|
|
|
```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>`:
|
|
|
|
```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.
|
|
|
|
```lua
|
|
local a = {1, 2}
|
|
local b = {3, 4, a}
|
|
a[3] = b -- a references b, and b references a
|
|
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
|
|
|
|
`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}}}}}
|
|
|
|
assert(inspect(t5, {depth = 4}) == [[{
|
|
a = {
|
|
b = {
|
|
c = {
|
|
d = {...}
|
|
}
|
|
}
|
|
}
|
|
}]])
|
|
|
|
assert(inspect(t5, {depth = 2}) == [[{
|
|
a = {
|
|
b = {...}
|
|
}
|
|
}]])
|
|
|
|
```
|
|
|
|
`options.depth` defaults to infinite (`math.huge`).
|
|
|
|
#### options.newline & options.indent
|
|
|
|
These are the strings used by `inspect` to respectively add a newline and indent each level of a table.
|
|
|
|
By default, `options.newline` is `"\n"` and `options.indent` is `" "` (two spaces).
|
|
|
|
``` lua
|
|
local t = {a={b=1}}
|
|
|
|
assert(inspect(t) == [[{
|
|
a = {
|
|
b = 1
|
|
}
|
|
}]])
|
|
|
|
assert(inspect(t, {newline='@', indent="++"}), "{@++a = {@++++b = 1@++}@}"
|
|
```
|
|
|
|
#### 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, the special value `inspect.KEY` is inserted. For example, to reach the `c` in `{a = {b = {c = 1}}}`,
|
|
the path will be `{'a', 'b', 'c', inspect.KEY }`
|
|
* For metatables, the special value `inspect.METATABLE` is inserted. For `{a = {b = 1}}}`, the path
|
|
`{'a', {b = 1}, inspect.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 the `path` parameter to check
|
|
wether the last element is `inspect.METATABLE`, and return `nil` instead of the item:
|
|
|
|
``` lua
|
|
local t, mt = ... -- (defined as before)
|
|
|
|
local remove_all_metatables = function(item, path)
|
|
if path[#path] ~= inspect.METATABLE then return item end
|
|
end
|
|
|
|
assert(inspect(t, {process = remove_all_metatables}) == "{ 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"
|
|
}]])
|
|
```
|
|
|
|
Gotchas / Warnings
|
|
==================
|
|
|
|
This method is *not* appropriate for saving/restoring tables. It is meant to be used by the programmer mainly while debugging a program.
|
|
|
|
Installation
|
|
============
|
|
|
|
If you are using luarocks, just run
|
|
|
|
luarocks install inspect
|
|
|
|
Otherwise, you can just copy the inspect.lua file somewhere in your projects (maybe inside a /lib/ folder) and require it accordingly.
|
|
|
|
Remember to store the value returned by require somewhere! (I suggest a local variable named inspect, although others might like table.inspect)
|
|
|
|
local inspect = require 'inspect'
|
|
-- or --
|
|
local inspect = require 'lib.inspect'
|
|
|
|
Also, make sure to read the license; the text of that license file must appear somewhere in your projects' files. For your convenience, it's included at the begining of inspect.lua.
|
|
|
|
Specs
|
|
=====
|
|
|
|
This project uses [busted](http://olivinelabs.com/busted/) for its specs. If you want to run the specs, you will have to install busted first. Then just execute the following from the root inspect folder:
|
|
|
|
busted
|
|
|
|
Change log
|
|
==========
|
|
|
|
Read it on the CHANGELOG.md file
|
|
|
|
|
|
|
|
|
|
|
|
|