mirror of
https://github.com/kikito/inspect.lua.git
synced 2024-12-15 14:34:21 +00:00
Human-readable representation of Lua tables
spec | ||
BSD-LICENSE.txt | ||
inspect.lua | ||
README.textile |
h1. 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. h1. Examples of use "Array-like" tables are rendered horizontally: <pre>inspect({1,2,3,4}) == "<1>{ 1, 2, 3, 4 }"</pre> "dictionary-like" tables are rendered with one element per line: <pre>inspect({a=1,b=2}) == [[<1>{ a = 1, b = 2 }]]</pre> 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: <pre> inspect({1,2,3,a=1,b=2}) == [[<1>{ 1, 2, 3, a = 1, b = 2 }]] </pre> Tables can be nested, and will be indented with two spaces per level. <pre> inspect({a={b=2}}) = [[<1>{ a = <2>{ b = 2 } }]] </pre> By default, @inspect@ will stop rendering at a depth of 4 levels. When that point is reached, it will just return @{...}@ : <pre> local t5 = {a = {b = {c = {d = {e = 5}}}}} inspect(t5) == [[<1>{ a = <2>{ b = <3>{ c = <4>{ d = {...} } } } }]] </pre> You can increase/decrease the max depth with the second parameter: <pre> inspect(t5, 2) == [[<1>{ a = <2>{ b = {...} } }]]) inspect(t5, 7) == [[<1>{ a = <2>{ b = <3>{ c = <4>{ d = <5>{ e = 5 } } } } }]]) </pre> Functions, userdata and threads are simply rendered as @<function x>@, @<userdata x>@ and @<thread x>@ respectively: <pre> inspect({ f = print, ud = some_user_data, thread = a_thread} ) == [[{ f = <function 1>, u = <userdata 1>, thread = <thread 1> }]]) </pre> If the table has a metatable, inspect will include it at the end, in a special field called @<metatable>@: <pre> inspect(setmetatable({a=1}, {b=2}) == [[<1>{ a = 1 <metatable> = <2>{ b = 2 } }]]) </pre> You may have noticed that all tables are preceded by an @<id>@ string. If a table has already been printed out, @inspect@ will just print @<table id>@ the second time it finds it. This will infinite loops. <pre> a = {1,2} b = {3,4,a} a[3] = b inspect(a) = "<1>{ 1, 2, <2>{ 3, 4, <table 1> } }" </pre> Notice how the second appearance of @a@ was replaced by @<table 1>@ in the string above. h1. Gotchas / Warnings This method is *not* appropiate for saving/restoring tables. It is ment to be used by the programmer mainly while debugging a program. h1. 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, altough others might like table.inspect) <pre> local inspect = require 'inspect' -- or -- table.inspect = require 'inspect' </pre> Also, make sure to read the license file; the text of that license file must appear somewhere in your projects' files. h1. Specs This project uses "telescope":https://github.com/norman/telescope for its specs. If you want to run the specs, you will have to install telescope first. Then just enter the spec folder and execute run.lua: <pre> cd path/to/inspect.lua/specs lua run.lua </pre>