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 execute the following from the root inspect folder:

<pre>
tsc -f spec/*
</pre>