kikito
12 years ago
parent
f4eceb558a
commit
4cffae8b5b
@ -0,0 +1,111 @@ |
||||
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 |
||||
=============== |
||||
|
||||
"Array-like" tables are rendered horizontally: |
||||
|
||||
inspect({1,2,3,4}) == "{ 1, 2, 3, 4 }" |
||||
|
||||
"dictionary-like" tables are rendered with one element per line: |
||||
|
||||
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 |
||||
}]] |
||||
|
||||
Tables can be nested, and will be indented with two spaces per level. |
||||
|
||||
inspect({a={b=2}}) == [[{ |
||||
a = { |
||||
b = 2 |
||||
} |
||||
}]] |
||||
|
||||
`inspect`'s second parameter allows controlling the maximum depth that will be printed out. When the max depth is reached, it'll just return `{...}`: |
||||
|
||||
local t5 = {a = {b = {c = {d = {e = 5}}}}} |
||||
|
||||
inspect(t5, 4) == [[{ |
||||
a = { |
||||
b = { |
||||
c = { |
||||
d = {...} |
||||
} |
||||
} |
||||
} |
||||
}]] |
||||
|
||||
inspect(t5, 2) == [[{ |
||||
a = { |
||||
b = {...} |
||||
} |
||||
}]]) |
||||
|
||||
Functions, userdata and threads are simply rendered as `<function x>`, `<userdata x>` and `<thread x>` respectively: |
||||
|
||||
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}) == [[{ |
||||
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} |
||||
a[3] = b -- a references b, and b references a |
||||
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. |
||||
|
||||
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 execute the following from the root inspect folder: |
||||
|
||||
<pre> |
||||
tsc -f spec/* |
||||
</pre> |
||||
|
||||
|
||||
@ -1,137 +0,0 @@ |
||||
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 prevent 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 execute the following from the root inspect folder: |
||||
|
||||
<pre> |
||||
tsc -f spec/* |
||||
</pre> |
||||
|
||||
|
||||
Loading…
Reference in new issue