diff --git a/README.md b/README.md index c0795a3..e7e933f 100644 --- a/README.md +++ b/README.md @@ -10,90 +10,204 @@ The objective here is human understanding (i.e. for debugging), not serializatio Examples of use =============== -`inspect` has the following declaration: `str = inspect(value, )`. +`inspect` has the following declaration: `local str = inspect(value, )`. -`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}) == [[{ - 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, - a = 1, - b = 2 - }]] +```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}}) == [[{ - a = { - b = 2 - } - }]] +```lua +assert(inspect({a={b=2}}) == [[{ + a = { + b = 2 + } +}]]) +``` Functions, userdata and any other custom types from Luajit are simply as ``, ``, etc.: - inspect({ f = print, ud = some_user_data, thread = a_thread} ) == [[{ - f = , - u = , - thread = - }]]) +```lua +assert(inspect({ f = print, ud = some_user_data, thread = a_thread} ) == [[{ + f = , + u = , + thread = +}]]) +``` If the table has a metatable, inspect will include it at the end, in a special field called ``: - inspect(setmetatable({a=1}, {b=2}) == [[{ - a = 1 - = { - b = 2 - } - }]]) +```lua +assert(inspect(setmetatable({a=1}, {b=2}) == [[{ + a = 1 + = { + b = 2 + } +}]])) +``` `inspect` can handle tables with loops inside them. It will print `` right before the table is printed out the first time, and replace the whole table with `` from then on, preventing infinite loops. - a = {1, 2} - b = {3, 4, a} - a[3] = b -- a references b, and b references a - inspect(a) = "<1>{ 1, 2, { 3, 4,
} }" +```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,
} }") +``` Notice that since both `a` appears more than once in the expression, it is prefixed by `<1>` and replaced by `
` 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. - local t5 = {a = {b = {c = {d = {e = 5}}}}} +#### options.depth - inspect(t5, {depth = 4}) == [[{ - a = { - b = { - c = { - d = {...} - } - } +`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 = {...} } - }]] + } + } +}]]) - inspect(t5, {depth = 2}) == [[{ - a = { - b = {...} - } - }]]) +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 `` is inserted. For example, to reach the `c` in `{a = {b = {c = 1}}}`, + the path will be `{'a', 'b', 'c', '' }` + * For metatables, a special value called `` is inserted. For `{a = {b = 1}}}`, the path + `{'a', 'b', ''}` 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] ~= '' 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.