inspect.lua
===========
[](https://travis-ci.org/kikito/inspect.lua)
This function transform any Lua table into a human-readable representation of that table.
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.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.
`options.filter` accepts a table of values. Any value on that table will be rendered as `<filtered>` . This is useful for hiding things like long complex tables that are not interesting for the task at hand, for example an unuseful complex metatable.
local person = {name = 'peter'}
setmetatable(person, complex_mt)
inspect(x, {filter = {complex_mt}}) == [[{
name = "peter",
< metatable > = < filtered >
}]]
`options.filter` can also be a function. The function must return true for the values that must be filtered out.
local isEvenNumber = function(x) return type(x) == 'number' and x % 2 == 0 end
inspect({1,2,3,4,5}, {filter = isEvenNumber}) == "{ 1, < filtered > , 3, < filtered > , 5 }"
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
============
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 --
table.inspect = require 'inspect'
Also, make sure to read the license file; the text of that license file must appear somewhere in your projects' files.
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
