kodewulf/inspect.lua

Human-readable representation of Lua tables

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>{ 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 <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}) == [[<1>{
  a = 1
  <metatable> = <2>{
    b = 2
  }
}]])

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.

a = {1,2}
b = {3,4,a}
a[3] = b
inspect(a) = "<1>{ 1, 2, <2>{ 3, 4, <table 1> } }"

Notice how the second appearance of a was replaced by <table 1> in the string above.

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.

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.

Specs

This project uses 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/*