• Stars
    star
    1,346
  • Rank 34,772 (Top 0.7 %)
  • Language
    Lua
  • License
    MIT License
  • Created over 13 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Human-readable representation of Lua tables

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, <options>).

value can be any Lua value.

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

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:

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

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

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:

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

Subtables are indented with two spaces per level.

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

Functions, userdata and any other custom types from Luajit are simply as <function x>, <userdata x>, etc.:

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

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

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, <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.

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 {...}:

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).

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:

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:

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:

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:

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, 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 and then launch 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

More Repositories

1

middleclass

Object-orientation for Lua
Lua
1,629
star
2

bump.lua

A collision detection library for Lua
Lua
914
star
3

anim8

An animation library for LÖVE
Lua
707
star
4

tween.lua

Tweening/Easing/Interpolating functions for lua. Inspired on jQuery's animate method.
Lua
568
star
5

lua_missions

Lua Koans, minus the Zen stuff
Lua
375
star
6

md5.lua

MD5 sum in pure Lua, with no C and no external dependencies
Lua
321
star
7

love-tile-tutorial

A tutorial for making tile-based games with LÖVE
Lua
272
star
8

i18n.lua

A very complete i18n lib for Lua
Lua
251
star
9

gamera

A camera system for LÖVE
Lua
248
star
10

stateful.lua

Stateful classes for Lua
Lua
174
star
11

cron.lua

Time-related functions for Lua, inspired in javascript's setTimeout and setInterval
Lua
169
star
12

love-loader

Threaded resource loading for LÖVE
Lua
130
star
13

lua-sandbox

A lua sandbox for executing non-trusted code
Lua
128
star
14

beholder.lua

Minimal observer pattern for Lua, with a couple twists
Lua
105
star
15

semver.lua

Semantic versioning for Lua
Lua
103
star
16

memoize.lua

memoized functions in lua
Lua
88
star
17

sha1.lua

(Deprecated Repo) SHA-1 secure hash computation, and HMAC-SHA1 signature computation in Lua (5.1)
Lua
72
star
18

7-languages-in-7-weeks

My personal repo for 7LI7W exercises
Prolog
63
star
19

luv.js

Minimal HTML5 game development lib
JavaScript
43
star
20

passion

An object-oriented LÖVE game engine
Lua
36
star
21

middleclass-extras

A set of middleclass add-ons that make it easier to use in some cases
Lua
32
star
22

bresenham.lua

Lua
29
star
23

utf8_validator.lua

Easily validating UTF-8 strings in pure Lua
Lua
26
star
24

battle-cry

Lua
13
star
25

middleclass-commons

Interface between middleclass and Class-Commons
Lua
10
star
26

pulsar.lua

A-star algorithm implementation in Lua
Lua
10
star
27

ekrixion

simple game in LÖVE
Lua
9
star
28

fay

A small game for LÖVE, made for Ludum Dare #25
Lua
9
star
29

contact.php

Simple contact form. I really mean it. It's very simple.
PHP
9
star
30

lua-for-javascripters

A presentation about Lua, for people who are familiar with Javascript
CSS
7
star
31

pew-pew-boom

Explosions in 2D space. Ussing PÄSSION and LÖVE
Lua
6
star
32

middleclass-specs

Specs for testing middleclass
Lua
5
star
33

kongame

Lua
5
star
34

nvim

nvim custom config
Vim Script
5
star
35

missing_i18n

Rails mountable engine that finds missing i18n translations and displays them in a variety of formats.
Ruby
5
star
36

busted-stable

A simple rock to install a stable version of busted
4
star
37

middleclass-ai

Ai-related classes implemented in Lua
4
star
38

passion-demos

several demos of the PÄSSION game engine
Lua
4
star
39

rickshaw-vs-nvd3

Comparison of 2 popular js charting libs
CSS
3
star
40

adegan

my personal vim configuration
Vim Script
3
star
41

ci-with-lua

Presentation about continuous integration with Lua
CSS
3
star
42

love_open_chars

open_chars used on a love
Lua
3
star
43

us-4-es.keylayout

Mac keyboard layout for users of U.S. layout who need to write Spanish characters occasionally.
3
star
44

things-to-do-with-postgresql

A presentation about postgresql and rails
CSS
3
star
45

measuring-luas-performance

CSS
2
star
46

a-taste-of-lua

My talk about Lua in APIStrat Chicago 09-2014
CSS
2
star
47

stateful-demo

A simple demo of stateful.lua
Lua
2
star
48

rust-by-example

My activities & impressions while reading Rust by Example
Rust
2
star
49

modis.lua

Lua implementation of MongoDB query language over redis.
Lua
2
star
50

open_chars

My take on Silveira Neto's Open Charas project
2
star
51

jay

javascript object oriented game engine
JavaScript
2
star
52

ld-30

LD 30 - Earth, Hell & Space
Lua
2
star
53

kiki.to

CSS
1
star
54

S021

Interactive Fiction Collaborative Story
HTML
1
star
55

ood-with-ruby

A POODR-based presentation
CSS
1
star
56

stimulus-how-and-why

CSS
1
star
57

lua-for-rubyists

Slides for a talk about Lua for Ruby practicioners
CSS
1
star
58

hacking-madrid

Presentation for t3chfest 2016 about my work in decide.madrid.es
CSS
1
star
59

ci-with-ruby

Talk about continouous integration with ruby
CSS
1
star
60

popular-gemology

A talk about ruby gems: what to look for and to avoid
CSS
1
star
61

old-blog

Kikito's github page
JavaScript
1
star
62

api-addicts-2021-06-24

Companion repo for my API:Addicts talk of June 2021
1
star