diff --git a/README.md b/README.md new file mode 100644 index 0000000..a3cb71a --- /dev/null +++ b/README.md @@ -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 ``, `` and `` respectively: + + 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 + } + }]]) + +`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,
} }" + +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. + +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) + +
+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. + +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: + +
+tsc -f spec/*
+
+ + diff --git a/README.textile b/README.textile deleted file mode 100644 index 508f1e5..0000000 --- a/README.textile +++ /dev/null @@ -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: - -
inspect({1,2,3,4}) == "<1>{ 1, 2, 3, 4 }"
- -"dictionary-like" tables are rendered with one element per line: - -
inspect({a=1,b=2}) == [[<1>{
-  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,a=1,b=2}) == [[<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}}) = [[<1>{
-  a = <2>{
-    b = 2
-  }
-}]]
-
- -By default, @inspect@ will stop rendering at a depth of 4 levels. When that point is reached, it will just return @{...}@ : - -
-local t5 = {a = {b = {c = {d = {e = 5}}}}}
-inspect(t5) == [[<1>{
-  a = <2>{
-    b = <3>{
-      c = <4>{
-        d = {...}
-      }
-    }
-  }
-}]]
-
- -You can increase/decrease the max depth with the second parameter: - -
-inspect(t5, 2) == [[<1>{
-  a = <2>{
-    b = {...}
-  }
-}]])
-
-inspect(t5, 7) == [[<1>{
-  a = <2>{
-    b = <3>{
-      c = <4>{
-        d = <5>{
-          e = 5
-        }
-      }
-    }
-  }
-}]])
-
- -Functions, userdata and threads are simply rendered as @@, @@ and @@ respectively: - -
-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}) == [[<1>{
-  a = 1
-   = <2>{
-    b = 2
-  }
-}]])
-
- -You may have noticed that all tables are preceded by an @@ string. If a table has already been printed out, @inspect@ will just print @
@ the second time it finds it. This will prevent infinite loops. - -
-a = {1,2}
-b = {3,4,a}
-a[3] = b
-inspect(a) = "<1>{ 1, 2, <2>{ 3, 4,
} }" - - -Notice how the second appearance of @a@ was replaced by @
@ 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) - -
-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. - -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: - -
-tsc -f spec/*
-
- -