Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kikito/inspect.lua

Human-readable representation of Lua tables
https://github.com/kikito/inspect.lua

human-readable lua tables

Last synced: 26 days ago
JSON representation

Human-readable representation of Lua tables

Awesome Lists containing this project

README 

        
inspect.lua

===========



This library transforms any Lua value into a human-readable representation. It is especially useful for debugging errors in tables.



The objective here is human understanding (i.e. for debugging), not serialization or compactness.



Examples of use

===============



`inspect` has the following declaration: `local str = inspect(value, )`.



`value` can be any Lua value.



`inspect` transforms simple types (like strings or numbers) into strings.



```lua

assert(inspect(1) == "1")

assert(inspect("Hello") == '"Hello"')

```



Tables, on the other hand, are rendered in a way a human can read easily.



"Array-like" tables are rendered horizontally:



```lua

assert(inspect({1,2,3,4}) == "{ 1, 2, 3, 4 }")

```



"Dictionary-like" tables are rendered with one element per line:



```lua

assert(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:



```lua

assert(inspect({1,2,3,b=2,a=1}) == [[{ 1, 2, 3,

  a = 1,

  b = 2

}]])

```



Subtables are indented with two spaces per level.



```lua

assert(inspect({a={b=2}}) == [[{

  a = {

    b = 2

  }

}]])

```



Functions, userdata and any other custom types from Luajit are simply as ``, ``, etc.:



```lua

assert(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 ``:



```lua

assert(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.



```lua

local a = {1, 2}

local b = {3, 4, a}

a[3] = b -- a references b, and b references a

assert(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.



### options



`inspect` has a second parameter, called `options`. It is not mandatory, but when it is provided, it must be a table.



#### options.depth



`options.depth` sets the maximum depth that will be printed out.

When the max depth is reached, `inspect` will stop parsing tables and just return `{...}`:



```lua



local t5 = {a = {b = {c = {d = {e = 5}}}}}



assert(inspect(t5, {depth = 4}) == [[{

  a = {

    b = {

      c = {

        d = {...}

      }

    }

  }

}]])



assert(inspect(t5, {depth = 2}) == [[{

  a = {

    b = {...}

  }

}]])



```



`options.depth` defaults to infinite (`math.huge`).



#### options.newline & options.indent



These are the strings used by `inspect` to respectively add a newline and indent each level of a table.



By default, `options.newline` is `"\n"` and `options.indent` is `"  "` (two spaces).



``` lua

local t = {a={b=1}}



assert(inspect(t) == [[{

  a = {

    b = 1

  }

}]])



assert(inspect(t, {newline='@', indent="++"}), "{@++a = {@++++b = 1@++}@}"

```



#### options.process



`options.process` is a function which allow altering the passed object before transforming it into a string.

A typical way to use it would be to remove certain values so that they don't appear at all.



`options.process` has the following signature:



``` lua

local processed_item = function(item, path)

```



* `item` is either a key or a value on the table, or any of its subtables

* `path` is an array-like table built with all the keys that have been used to reach `item`, from the root.

  * For values, it is just a regular list of keys. For example, to reach the 1 in `{a = {b = 1}}`, the `path`

    will be `{'a', 'b'}`

  * For keys, the special value `inspect.KEY` is inserted. For example, to reach the `c` in `{a = {b = {c = 1}}}`,

    the path will be `{'a', 'b', 'c', inspect.KEY }`

  * For metatables, the special value `inspect.METATABLE` is inserted. For `{a = {b = 1}}}`, the path

    `{'a', {b = 1}, inspect.METATABLE}` means "the metatable of the table `{b = 1}`".

* `processed_item` is the value returned by `options.process`. If it is equal to `item`, then the inspected

  table will look unchanged. If it is different, then the table will look different; most notably, if it's `nil`,

  the item will dissapear on the inspected table.



#### Examples



Remove a particular metatable from the result:



``` lua

local t = {1,2,3}

local mt = {b = 2}

setmetatable(t, mt)



local remove_mt = function(item)

  if item ~= mt then return item end

end



-- mt does not appear

assert(inspect(t, {process = remove_mt}) == "{ 1, 2, 3 }")

```



The previous example only works for a particular metatable. If you want to make *all* metatables, you can use the `path` parameter to check

wether the last element is `inspect.METATABLE`, and return `nil` instead of the item:



``` lua

local t, mt = ... -- (defined as before)



local remove_all_metatables = function(item, path)

  if path[#path] ~= inspect.METATABLE then return item end

end



assert(inspect(t, {process = remove_all_metatables}) == "{ 1, 2, 3 }")

```



Filter a value:



```lua

local anonymize_password = function(item, path)

  if path[#path] == 'password' then return "XXXX" end

  return item

end



local info = {user = 'peter', password = 'secret'}



assert(inspect(info, {process = anonymize_password}) == [[{

  password = "XXXX",

  user     = "peter"

}]])

```



Gotchas / Warnings

==================



This method is *not* appropriate for saving/restoring tables. It is meant to be used by the programmer mainly while debugging a program.



Installation

============



If you are using luarocks, just run



    luarocks install inspect



Otherwise, you can 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, although others might like table.inspect)



    local inspect = require 'inspect'

          -- or --

    local inspect = require 'lib.inspect'



Also, make sure to read the license; the text of that license file must appear somewhere in your projects' files. For your convenience, it's included at the begining of inspect.lua.



Contributing

============



This project uses [Teal](https://github.com/teal-language/tl), a typed dialect of Lua (which generates plain lua files too)



If you want to send a pull request to this project, first of all, thank you! You will need to install the. You can install all of them by running:



```

make dev

```



When writing your PR, please make your modifications on the `inspect.tl` file and then generate the `inspect.lua` file from it. You will probably want to make sure that the tests are still 

working (github should run them from you, but they should run very fast). You can do both things in one go by just invoking



```

make

```



This will generate `inspect.lua`, check it with [luacheck](https://github.com/lunarmodules/luacheck) and then launch [busted](http://olivinelabs.com/busted/) to run the specs.



If you are sending a pull request, you might want to add some specs in the `specs` folder.



Change log

==========



Read it on the CHANGELOG.md file