allow using inspect inside __tostring metamethods without errors

Ignore __pairs and __ipairs metamethods when rendering tables

.travis.yml

@@ -1,12 +1,36 @@
-language: erlang
+language: python
+sudo: false
 
 env:
-  - LUA=""
-  - LUA="luajit"
+  - LUA="lua=5.1"
+  - LUA="lua=5.2"
+  - LUA="lua=5.3"
+  - LUA="luajit=2.0"
+  - LUA="luajit=2.1"
+
+before_install:
+  - pip install hererocks
+  - hererocks lua_install -r^ --$LUA
+  - export PATH=$PATH:$PWD/lua_install/bin # Add directory with all installed binaries to PATH
 
 install:
-  - sudo apt-get install luajit
-  - sudo apt-get install luarocks
-  - sudo luarocks install busted
+  - luarocks install luacheck
+  - luarocks install busted
+  - luarocks install luacov
+  - luarocks install luacov-coveralls
 
-script: "busted"
+script:
+  - luacheck --std max+busted *.lua spec
+  - busted --verbose --coverage
+
+after_success:
+  - luacov-coveralls --exclude $TRAVIS_BUILD_DIR/lua_install
+
+branches:
+  except:
+    - gh-pages
+
+notifications:
+  email:
+    on_success: change
+    on_failure: always

CHANGELOG.md

@@ -1,4 +1,36 @@
-v2.0.0
+## v3.1.1
+
+* Better handling of LuaJIT's `ctype` and `cdata` values (#34, thanks @akopytov)
+
+## v3.1.0
+
+* Fixes bug: all control codes are escaped correctly (instead of only the named ones such as \n).
+  Example: \1 becomes \\1 (or \\001 when followed by a digit)
+* Fixes bug when using the `process` option in recursive tables
+* Overriding global `tostring` with inspect no longer results in an error.
+* Simplifies id generation, using less tables and metatables.
+
+## v3.0.3
+* Fixes a bug which sometimes displayed struct-like parts of tables as sequence-like due
+  to the way rawlen/the # operator are implemented.
+
+## v3.0.2
+* Fixes a bug when a table was garbage-collected while inspect was trying to render it
+
+## v3.0.1
+* Fixes a bug when dealing with tables which have a __len metamethod in Lua >= 5.2
+
+## v3.0.0
+
+The basic functionality remains as before, but there's one backwards-incompatible change if you used `options.filter`.
+
+* **Removed** `options.filter`
+* **Added** `options.process`, which can be used to do the same as `options.filter`, and more.
+* **Added** two new constants, `inspect.METATABLE` and `inspect.KEY`
+* **Added** `options.indent` & `options.newline`.
+
+
+## v2.0.0
 
 * Ability to deal with LuaJit's custom types
 * License change from BSD to MIT

README.md

@@ -2,8 +2,10 @@ inspect.lua
 ===========
 
 [![Build Status](https://travis-ci.org/kikito/inspect.lua.png?branch=master)](https://travis-ci.org/kikito/inspect.lua)
+[![Coverage Status](https://coveralls.io/repos/github/kikito/inspect.lua/badge.svg?branch=master)](https://coveralls.io/github/kikito/inspect.lua?branch=master)
 
-This function transform any Lua table into a human-readable representation of that table.
+
+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.
 
@@ -124,7 +126,7 @@ assert(inspect(t5, {depth = 2}) == [[{
 
 `options.depth` defaults to infinite (`math.huge`).
 
-### options.newline & options.indent
+#### options.newline & options.indent
 
 These are the strings used by `inspect` to respectively add a newline and indent each level of a table.
 
@@ -142,7 +144,7 @@ assert(inspect(t) == [[{
 assert(inspect(t, {newline='@', indent="++"}), "{@++a = {@++++b = 1@++}@}"
 ```
 
-### options.process
+#### 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.
@@ -182,17 +184,17 @@ end
 assert(inspect(t, {process = remove_mt}) == "{ 1, 2, 3 }")
 ```
 
-The previous exaple only works for a particular metatable. If you want to make *all* metatables, you can use `path`:
+The previous exaple 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] ~= '<metatable>' then return item end
+  if path[#path] ~= inspect.METATABLE then return item end
 end
 
--- Removes all metatables
-assert(inspect(t, {process = remove_mt}) == "{ 1, 2, 3 }")
+assert(inspect(t, {process = remove_all_metatables}) == "{ 1, 2, 3 }")
 ```
 
 Filter a value:
@@ -211,40 +213,6 @@ assert(inspect(info, {process = anonymize_password}) == [[{
 }]])
 ```
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Sometimes it might be convenient to "filter out" some parts of the output. The `options.filter` option can do that.
-
-`options.filter` accepts a table of values. Any value on that table will be rendered as `<filtered>`. This is useful for hiding things like long complex tables that are not interesting for the task at hand, for example an unuseful complex metatable.
-
-    local person = {name = 'peter'}
-    setmetatable(person, complex_mt)
-    inspect(x, {filter = {complex_mt}}) == [[{
-      name = "peter",
-      <metatable> = <filtered>
-    }]]
-
-`options.filter` can also be a function. The function must return true for the values that must be filtered out.
-
-    local isEvenNumber = function(x) return type(x) == 'number' and x % 2 == 0 end
-
-    inspect({1,2,3,4,5}, {filter = isEvenNumber}) == "{ 1, <filtered>, 3, <filtered>, 5 }"
-
-
 Gotchas / Warnings
 ==================
 
@@ -253,15 +221,19 @@ This method is *not* appropriate for saving/restoring tables. It is meant to be
 Installation
 ============
 
-Just copy the inspect.lua file somewhere in your projects (maybe inside a /lib/ folder) and require it accordingly.
+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 --
-    table.inspect = require 'inspect'
+    local inspect = require 'lib.inspect'
 
-Also, make sure to read the license file; the text of that license file must appear somewhere in your projects' files.
+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.
 
 Specs
 =====
@@ -270,4 +242,12 @@ This project uses [busted](http://olivinelabs.com/busted/) for its specs. If you
 
     busted
 
+Change log
+==========
+
+Read it on the CHANGELOG.md file
+
+
+
+
 

inspect.lua

@@ -1,5 +1,5 @@
 local inspect ={
-  _VERSION = 'inspect.lua 2.0.0',
+  _VERSION = 'inspect.lua 3.1.0',
   _URL     = 'http://github.com/kikito/inspect.lua',
   _DESCRIPTION = 'human-readable representations of tables',
   _LICENSE = [[
@@ -28,9 +28,15 @@ local inspect ={
   ]]
 }
 
+local tostring = tostring
+
 inspect.KEY       = setmetatable({}, {__tostring = function() return 'inspect.KEY' end})
 inspect.METATABLE = setmetatable({}, {__tostring = function() return 'inspect.METATABLE' end})
 
+local function rawpairs(t)
+  return next, t, nil
+end
+
 -- Apostrophizes the string if it has quotes, but not aphostrophes
 -- Otherwise, it returns a regular quoted string
 local function smartQuote(str)
@@ -40,28 +46,35 @@ local function smartQuote(str)
   return '"' .. str:gsub('"', '\\"') .. '"'
 end
 
-local controlCharsTranslation = {
-  ["\a"] = "\\a",  ["\b"] = "\\b", ["\f"] = "\\f",  ["\n"] = "\\n",
+-- \a => '\\a', \0 => '\\0', 31 => '\31'
+local shortControlCharEscapes = {
+  ["\a"] = "\\a",  ["\b"] = "\\b", ["\f"] = "\\f", ["\n"] = "\\n",
   ["\r"] = "\\r",  ["\t"] = "\\t", ["\v"] = "\\v"
 }
-
-local function escapeChar(c) return controlCharsTranslation[c] end
+local longControlCharEscapes = {} -- \a => nil, \0 => \000, 31 => \031
+for i=0, 31 do
+  local ch = string.char(i)
+  if not shortControlCharEscapes[ch] then
+    shortControlCharEscapes[ch] = "\\"..i
+    longControlCharEscapes[ch]  = string.format("\\%03d", i)
+  end
+end
 
 local function escape(str)
-  local result = str:gsub("\\", "\\\\"):gsub("(%c)", escapeChar)
-  return result
+  return (str:gsub("\\", "\\\\")
+             :gsub("(%c)%f[0-9]", longControlCharEscapes)
+             :gsub("%c", shortControlCharEscapes))
 end
 
 local function isIdentifier(str)
   return type(str) == 'string' and str:match( "^[_%a][_%a%d]*$" )
 end
 
-local function isArrayKey(k, length)
-  return type(k) == 'number' and 1 <= k and k <= length
-end
-
-local function isDictionaryKey(k, length)
-  return not isArrayKey(k, length)
+local function isSequenceKey(k, sequenceLength)
+  return type(k) == 'number'
+     and 1 <= k
+     and k <= sequenceLength
+     and math.floor(k) == k
 end
 
 local defaultTypeOrders = {
@@ -86,47 +99,38 @@ local function sortKeys(a, b)
   return ta < tb
 end
 
-local function getDictionaryKeys(t)
-  local keys, length = {}, #t
-  for k,_ in pairs(t) do
-    if isDictionaryKey(k, length) then table.insert(keys, k) end
+-- For implementation reasons, the behavior of rawlen & # is "undefined" when
+-- tables aren't pure sequences. So we implement our own # operator.
+local function getSequenceLength(t)
+  local len = 1
+  local v = rawget(t,len)
+  while v ~= nil do
+    len = len + 1
+    v = rawget(t,len)
+  end
+  return len - 1
+end
+
+local function getNonSequentialKeys(t)
+  local keys, keysLength = {}, 0
+  local sequenceLength = getSequenceLength(t)
+  for k,_ in rawpairs(t) do
+    if not isSequenceKey(k, sequenceLength) then
+      keysLength = keysLength + 1
+      keys[keysLength] = k
+    end
   end
   table.sort(keys, sortKeys)
-  return keys
+  return keys, keysLength, sequenceLength
 end
 
-local function getToStringResultSafely(t, mt)
-  local __tostring = type(mt) == 'table' and rawget(mt, '__tostring')
-  local str, ok
-  if type(__tostring) == 'function' then
-    ok, str = pcall(__tostring, t)
-    str = ok and str or 'error: ' .. tostring(str)
-  end
-  if type(str) == 'string' and #str > 0 then return str end
-end
-
-local maxIdsMetaTable = {
-  __index = function(self, typeName)
-    rawset(self, typeName, 0)
-    return 0
-  end
-}
-
-local idsMetaTable = {
-  __index = function (self, typeName)
-    local col = setmetatable({}, {__mode = "kv"})
-    rawset(self, typeName, col)
-    return col
-  end
-}
-
 local function countTableAppearances(t, tableAppearances)
-  tableAppearances = tableAppearances or setmetatable({}, {__mode = "k"})
+  tableAppearances = tableAppearances or {}
 
   if type(t) == 'table' then
     if not tableAppearances[t] then
       tableAppearances[t] = 1
-      for k,v in pairs(t) do
+      for k,v in rawpairs(t) do
         countTableAppearances(k, tableAppearances)
         countTableAppearances(v, tableAppearances)
       end
@@ -154,22 +158,25 @@ local function makePath(path, ...)
   return newPath
 end
 
-local function processRecursive(process, item, path)
+local function processRecursive(process, item, path, visited)
   if item == nil then return nil end
+  if visited[item] then return visited[item] end
 
   local processed = process(item, path)
   if type(processed) == 'table' then
     local processedCopy = {}
+    visited[item] = processedCopy
     local processedKey
 
-    for k,v in pairs(processed) do
-      processedKey = processRecursive(process, k, makePath(path, k, inspect.KEY))
+    for k,v in rawpairs(processed) do
+      processedKey = processRecursive(process, k, makePath(path, k, inspect.KEY), visited)
       if processedKey ~= nil then
-        processedCopy[processedKey] = processRecursive(process, v, makePath(path, processedKey))
+        processedCopy[processedKey] = processRecursive(process, v, makePath(path, processedKey), visited)
       end
     end
 
-    local mt  = processRecursive(process, getmetatable(processed), makePath(path, inspect.METATABLE))
+    local mt  = processRecursive(process, getmetatable(processed), makePath(path, inspect.METATABLE), visited)
+    if type(mt) ~= 'table' then mt = nil end -- ignore not nil/table __metatable field
     setmetatable(processedCopy, mt)
     processed = processedCopy
   end
@@ -177,6 +184,7 @@ local function processRecursive(process, item, path)
 end
 
 
+
 -------------------------------------------------------------------
 
 local Inspector = {}
@@ -188,7 +196,7 @@ function Inspector:puts(...)
   local len    = #buffer
   for i=1, #args do
     len = len + 1
-    buffer[len] = tostring(args[i])
+    buffer[len] = args[i]
   end
 end
 
@@ -202,24 +210,19 @@ function Inspector:tabify()
   self:puts(self.newline, string.rep(self.indent, self.level))
 end
 
-function Inspector:commaControl(needsComma)
-  if needsComma then self:puts(',') end
-  return true
-end
-
 function Inspector:alreadyVisited(v)
-  return self.ids[type(v)][v] ~= nil
+  return self.ids[v] ~= nil
 end
 
 function Inspector:getId(v)
-  local tv = type(v)
-  local id = self.ids[tv][v]
+  local id = self.ids[v]
   if not id then
-    id              = self.maxIds[tv] + 1
+    local tv = type(v)
+    id              = (self.maxIds[tv] or 0) + 1
     self.maxIds[tv] = id
-    self.ids[tv][v] = id
+    self.ids[v]     = id
   end
-  return id
+  return tostring(id)
 end
 
 function Inspector:putKey(k)
@@ -239,44 +242,40 @@ function Inspector:putTable(t)
   else
     if self.tableAppearances[t] > 1 then self:puts('<', self:getId(t), '>') end
 
-    local dictKeys          = getDictionaryKeys(t)
-    local length            = #t
+    local nonSequentialKeys, nonSequentialKeysLength, sequenceLength = getNonSequentialKeys(t)
     local mt                = getmetatable(t)
-    local to_string_result  = getToStringResultSafely(t, mt)
 
     self:puts('{')
     self:down(function()
-      if to_string_result then
-        self:puts(' -- ', escape(to_string_result))
-        if length >= 1 then self:tabify() end
-      end
-
-      local needsComma = false
-      for i=1, length do
-        needsComma = self:commaControl(needsComma)
+      local count = 0
+      for i=1, sequenceLength do
+        if count > 0 then self:puts(',') end
         self:puts(' ')
         self:putValue(t[i])
+        count = count + 1
       end
 
-      for _,k in ipairs(dictKeys) do
-        needsComma = self:commaControl(needsComma)
+      for i=1, nonSequentialKeysLength do
+        local k = nonSequentialKeys[i]
+        if count > 0 then self:puts(',') end
         self:tabify()
         self:putKey(k)
         self:puts(' = ')
         self:putValue(t[k])
+        count = count + 1
       end
 
-      if mt then
-        needsComma = self:commaControl(needsComma)
+      if type(mt) == 'table' then
+        if count > 0 then self:puts(',') end
         self:tabify()
         self:puts('<metatable> = ')
         self:putValue(mt)
       end
     end)
 
-    if #dictKeys > 0 or mt then -- dictionary table. Justify closing }
+    if nonSequentialKeysLength > 0 or type(mt) == 'table' then -- result is multi-lined. Justify closing }
       self:tabify()
-    elseif length > 0 then -- array tables have one extra space before closing }
+    elseif sequenceLength > 0 then -- array tables have one extra space before closing }
       self:puts(' ')
     end
 
@@ -289,12 +288,13 @@ function Inspector:putValue(v)
 
   if tv == 'string' then
     self:puts(smartQuote(escape(v)))
-  elseif tv == 'number' or tv == 'boolean' or tv == 'nil' then
+  elseif tv == 'number' or tv == 'boolean' or tv == 'nil' or
+         tv == 'cdata' or tv == 'ctype' then
     self:puts(tostring(v))
   elseif tv == 'table' then
     self:putTable(v)
   else
-    self:puts('<',tv,' ',self:getId(v),'>')
+    self:puts('<', tv, ' ', self:getId(v), '>')
   end
 end
 
@@ -302,20 +302,22 @@ end
 
 function inspect.inspect(root, options)
   options       = options or {}
-  local depth   = options.depth or math.huge
-  local process = options.process
+
+  local depth   = options.depth   or math.huge
   local newline = options.newline or '\n'
   local indent  = options.indent  or '  '
+  local process = options.process
+
   if process then
-    root = processRecursive(process, root, {})
+    root = processRecursive(process, root, {}, {})
   end
 
   local inspector = setmetatable({
     depth            = depth,
-    buffer           = {},
     level            = 0,
-    ids              = setmetatable({}, idsMetaTable),
-    maxIds           = setmetatable({}, maxIdsMetaTable),
+    buffer           = {},
+    ids              = {},
+    maxIds           = {},
     newline          = newline,
     indent           = indent,
     tableAppearances = countTableAppearances(root)

rockspecs/inspect-3.0-1.rockspec

@@ -0,0 +1,23 @@
+package = "inspect"
+version = "3.0-1"
+source = {
+  url = "https://github.com/kikito/inspect.lua/archive/v3.0.0.tar.gz",
+  dir = "inspect.lua-3.0.0"
+}
+description = {
+  summary = "Lua table visualizer, ideal for debugging",
+  detailed = [[
+    inspect will print out your lua tables nicely so you can debug your programs quickly. It sorts keys by type and name and handles recursive tables properly.
+  ]],
+  homepage = "https://github.com/kikito/inspect.lua",
+  license = "MIT <http://opensource.org/licenses/MIT>"
+}
+dependencies = {
+  "lua >= 5.1"
+}
+build = {
+  type = "builtin",
+  modules = {
+    inspect = "inspect.lua"
+  }
+}

rockspecs/inspect-3.0-2.rockspec

@@ -0,0 +1,23 @@
+package = "inspect"
+version = "3.0-2"
+source = {
+  url = "https://github.com/kikito/inspect.lua/archive/v3.0.1.tar.gz",
+  dir = "inspect.lua-3.0.1"
+}
+description = {
+  summary = "Lua table visualizer, ideal for debugging",
+  detailed = [[
+    inspect will print out your lua tables nicely so you can debug your programs quickly. It sorts keys by type and name and handles recursive tables properly.
+  ]],
+  homepage = "https://github.com/kikito/inspect.lua",
+  license = "MIT <http://opensource.org/licenses/MIT>"
+}
+dependencies = {
+  "lua >= 5.1"
+}
+build = {
+  type = "builtin",
+  modules = {
+    inspect = "inspect.lua"
+  }
+}

rockspecs/inspect-3.0-3.rockspec

@@ -0,0 +1,23 @@
+package = "inspect"
+version = "3.0-3"
+source = {
+  url = "https://github.com/kikito/inspect.lua/archive/v3.0.2.tar.gz",
+  dir = "inspect.lua-3.0.2"
+}
+description = {
+  summary = "Lua table visualizer, ideal for debugging",
+  detailed = [[
+    inspect will print out your lua tables nicely so you can debug your programs quickly. It sorts keys by type and name and handles recursive tables properly.
+  ]],
+  homepage = "https://github.com/kikito/inspect.lua",
+  license = "MIT <http://opensource.org/licenses/MIT>"
+}
+dependencies = {
+  "lua >= 5.1"
+}
+build = {
+  type = "builtin",
+  modules = {
+    inspect = "inspect.lua"
+  }
+}

rockspecs/inspect-3.0-4.rockspec

@@ -0,0 +1,23 @@
+package = "inspect"
+version = "3.0-4"
+source = {
+  url = "https://github.com/kikito/inspect.lua/archive/v3.0.3.tar.gz",
+  dir = "inspect.lua-3.0.3"
+}
+description = {
+  summary = "Lua table visualizer, ideal for debugging",
+  detailed = [[
+    inspect will print out your lua tables nicely so you can debug your programs quickly. It sorts keys by type and name and handles recursive tables properly.
+  ]],
+  homepage = "https://github.com/kikito/inspect.lua",
+  license = "MIT <http://opensource.org/licenses/MIT>"
+}
+dependencies = {
+  "lua >= 5.1"
+}
+build = {
+  type = "builtin",
+  modules = {
+    inspect = "inspect.lua"
+  }
+}

rockspecs/inspect-3.1.1-0.rockspec

@@ -0,0 +1,23 @@
+package = "inspect"
+version = "3.1.1-0"
+source = {
+  url = "https://github.com/kikito/inspect.lua/archive/v3.1.1.tar.gz",
+  dir = "inspect.lua-3.1.1"
+}
+description = {
+  summary = "Lua table visualizer, ideal for debugging",
+  detailed = [[
+    inspect will print out your lua tables nicely so you can debug your programs quickly. It sorts keys by type and name and handles recursive tables properly.
+  ]],
+  homepage = "https://github.com/kikito/inspect.lua",
+  license = "MIT <http://opensource.org/licenses/MIT>"
+}
+dependencies = {
+  "lua >= 5.1"
+}
+build = {
+  type = "builtin",
+  modules = {
+    inspect = "inspect.lua"
+  }
+}

spec/inspect_spec.lua

@@ -1,83 +1,127 @@
 local inspect         = require 'inspect'
 local unindent        = require 'spec.unindent'
 local is_luajit, ffi  = pcall(require, 'ffi')
+local has_rawlen      = type(_G.rawlen) == 'function'
 
 describe( 'inspect', function()
 
   describe('numbers', function()
     it('works', function()
-      assert.equals(inspect(1), "1")
-      assert.equals(inspect(1.5), "1.5")
-      assert.equals(inspect(-3.14), "-3.14")
+      assert.equals("1", inspect(1))
+      assert.equals("1.5", inspect(1.5))
+      assert.equals("-3.14", inspect(-3.14))
     end)
   end)
 
   describe('strings', function()
     it('puts quotes around regular strings', function()
-      assert.equals(inspect("hello"), '"hello"')
+      assert.equals('"hello"', inspect("hello"))
     end)
 
     it('puts apostrophes around strings with quotes', function()
-      assert.equals(inspect('I have "quotes"'), "'I have \"quotes\"'")
+      assert.equals("'I have \"quotes\"'", inspect('I have "quotes"'))
     end)
 
     it('uses regular quotes if the string has both quotes and apostrophes', function()
-      assert.equals(inspect("I have \"quotes\" and 'apostrophes'"), '"I have \\"quotes\\" and \'apostrophes\'"')
+      assert.equals('"I have \\"quotes\\" and \'apostrophes\'"', inspect("I have \"quotes\" and 'apostrophes'"))
     end)
 
     it('escapes newlines properly', function()
-       assert.equals(inspect('I have \n new \n lines'), '"I have \\n new \\n lines"')
+      assert.equals('"I have \\n new \\n lines"', inspect('I have \n new \n lines'))
     end)
 
     it('escapes tabs properly', function()
-       assert.equals(inspect('I have \t a tab character'), '"I have \\t a tab character"')
+      assert.equals('"I have \\t a tab character"', inspect('I have \t a tab character'))
     end)
 
     it('escapes backspaces properly', function()
-       assert.equals(inspect('I have \b a back space'), '"I have \\b a back space"')
+      assert.equals('"I have \\b a back space"', inspect('I have \b a back space'))
+    end)
+
+    it('escapes unnamed control characters with 1 or 2 digits', function()
+      assert.equals('"Here are some control characters: \\0 \\1 \\6 \\17 \\27 \\31"',
+      inspect('Here are some control characters: \0 \1 \6 \17 \27 \31'))
+    end)
+
+    it('escapes unnamed control characters with 3 digits when they are followed by numbers', function()
+      assert.equals('"Control chars followed by digits \\0001 \\0011 \\0061 \\0171 \\0271 \\0311"',
+      inspect('Control chars followed by digits \0001 \0011 \0061 \0171 \0271 \0311'))
     end)
 
     it('backslashes its backslashes', function()
-       assert.equals(inspect('I have \\ a backslash'), '"I have \\\\ a backslash"')
-       assert.equals(inspect('I have \\\\ two backslashes'), '"I have \\\\\\\\ two backslashes"')
-       assert.equals(inspect('I have \\\n a backslash followed by a newline'), '"I have \\\\\\n a backslash followed by a newline"')
+      assert.equals('"I have \\\\ a backslash"', inspect('I have \\ a backslash'))
+      assert.equals('"I have \\\\\\\\ two backslashes"', inspect('I have \\\\ two backslashes'))
+      assert.equals('"I have \\\\\\n a backslash followed by a newline"',
+                    inspect('I have \\\n a backslash followed by a newline'))
     end)
 
   end)
 
   it('works with nil', function()
-    assert.equals(inspect(nil), 'nil')
+    assert.equals('nil', inspect(nil))
   end)
 
   it('works with functions', function()
-    assert.equals(inspect({ print, type, print }), '{ <function 1>, <function 2>, <function 1> }')
+    assert.equals('{ <function 1>, <function 2>, <function 1> }', inspect({ print, type, print }))
   end)
 
   it('works with booleans', function()
-    assert.equals(inspect(true), 'true')
-    assert.equals(inspect(false), 'false')
+    assert.equals('true', inspect(true))
+    assert.equals('false', inspect(false))
   end)
 
   if is_luajit then
-    describe('luajit cdata', function()
-      it('works with luajit cdata', function()
-        assert.equals(inspect({ ffi.new("int", 1), ffi.typeof("int"), ffi.typeof("int")(1) }), '{ <cdata 1>, <cdata 2>, <cdata 3> }')
-      end)
+    it('works with luajit cdata', function()
+      assert.equals('{ cdata<int>: PTR, ctype<int>, cdata<int>: PTR }',
+                    inspect({ ffi.new("int", 1), ffi.typeof("int"), ffi.typeof("int")(1) }):gsub('(0x%x+)','PTR'))
     end)
   end
 
   describe('tables', function()
 
     it('works with simple array-like tables', function()
-      assert.equals(inspect({1,2,3}), "{ 1, 2, 3 }" )
+      assert.equals("{ 1, 2, 3 }", inspect({1,2,3}))
     end)
 
     it('works with nested arrays', function()
-      assert.equals(inspect({'a','b','c', {'d','e'}, 'f'}), '{ "a", "b", "c", { "d", "e" }, "f" }' )
+      assert.equals('{ "a", "b", "c", { "d", "e" }, "f" }', inspect({'a','b','c', {'d','e'}, 'f'}))
     end)
 
+    if has_rawlen then
+      it('handles arrays with a __len metatable correctly (ignoring the __len metatable and using rawlen)', function()
+        local arr = setmetatable({1,2,3}, {__len = function() return nil end})
+        assert.equals("{ 1, 2, 3,\n  <metatable> = {\n    __len = <function 1>\n  }\n}", inspect(arr))
+      end)
+
+      it('handles tables with a __pairs metamethod (ignoring the __pairs metamethod and using next)', function()
+        local t = setmetatable({ {}, name = "yeah" }, { __pairs = function() end })
+        assert.equals(
+          unindent([[{ {},
+            name = "yeah",
+            <metatable> = {
+              __pairs = <function 1>
+            }
+          }]]),
+          inspect(t))
+      end)
+    end
+
     it('works with simple dictionary tables', function()
-      assert.equals(inspect({a = 1, b = 2}), "{\n  a = 1,\n  b = 2\n}")
+      assert.equals("{\n  a = 1,\n  b = 2\n}", inspect({a = 1, b = 2}))
+    end)
+
+    it('identifies tables with no number 1 as struct-like', function()
+      assert.equals(unindent([[{
+          [2] = 1,
+          [25] = 1,
+          id = 1
+        }
+        ]]), inspect({[2]=1,[25]=1,id=1}))
+    end)
+
+    it('identifies numeric non-array keys as dictionary keys', function()
+      assert.equals("{ 1, 2,\n  [-1] = true\n}", inspect({1, 2, [-1] = true}))
+      assert.equals("{ 1, 2,\n  [1.5] = true\n}", inspect({1, 2, [1.5] = true}))
     end)
 
     it('sorts keys in dictionary tables', function()
@@ -86,7 +130,7 @@ describe( 'inspect', function()
         [coroutine.create(function() end)] = 1,
         [14] = 1, [{c=2}] = 1, [true]= 1
       }
-      assert.equals(inspect(t), unindent([[
+      assert.equals(unindent([[
         { 1, 2, 3,
           [14] = 1,
           [true] = 1,
@@ -98,30 +142,30 @@ describe( 'inspect', function()
           [<function 1>] = 1,
           [<thread 1>] = 1
         }
-      ]]))
+      ]]), inspect(t))
     end)
 
     it('works with nested dictionary tables', function()
-      assert.equals(inspect( {d=3, b={c=2}, a=1} ), unindent([[{
+      assert.equals(unindent([[{
         a = 1,
         b = {
           c = 2
         },
         d = 3
-      }]]))
+      }]]), inspect( {d=3, b={c=2}, a=1} ))
     end)
 
     it('works with hybrid tables', function()
-      assert.equals(
-        inspect({ 'a', {b = 1}, 2, c = 3, ['ahoy you'] = 4 }),
-        unindent([[
+      assert.equals(unindent([[
           { "a", {
             b = 1
           }, 2,
           ["ahoy you"] = 4,
           c = 3
         }
-        ]]))
+        ]]), inspect({ 'a', {b = 1}, 2, c = 3, ['ahoy you'] = 4 }))
+
+
     end)
 
     it('displays <table x> instead of repeating an already existing table', function()
@@ -130,7 +174,7 @@ describe( 'inspect', function()
       a[4] = b
       a[5] = a
       a[6] = b
-      assert.equals(inspect(a), '<1>{ 1, 2, 3, <2>{ "a", "b", "c", <table 1> }, <table 1>, <table 2> }')
+      assert.equals('<1>{ 1, 2, 3, <2>{ "a", "b", "c", <table 1> }, <table 1>, <table 2> }', inspect(a))
     end)
 
     describe('The depth parameter', function()
@@ -138,7 +182,7 @@ describe( 'inspect', function()
       local keys = { [level5] = true }
 
       it('has infinite depth by default', function()
-        assert.equals(inspect(level5), unindent([[
+        assert.equals(unindent([[
           { 1, 2, 3,
             a = {
               b = {
@@ -150,24 +194,24 @@ describe( 'inspect', function()
               }
             }
           }
-        ]]))
+        ]]), inspect(level5))
       end)
       it('is modifiable by the user', function()
-        assert.equals(inspect(level5, {depth = 2}), unindent([[
+        assert.equals(unindent([[
           { 1, 2, 3,
             a = {
               b = {...}
             }
           }
-        ]]))
+        ]]), inspect(level5, {depth = 2}))
 
-        assert.equals(inspect(level5, {depth = 1}), unindent([[
+        assert.equals(unindent([[
           { 1, 2, 3,
             a = {...}
           }
-        ]]))
+        ]]), inspect(level5, {depth = 1}))
 
-        assert.equals(inspect(level5, {depth = 4}), unindent([[
+        assert.equals(unindent([[
           { 1, 2, 3,
             a = {
               b = {
@@ -177,13 +221,13 @@ describe( 'inspect', function()
               }
             }
           }
-        ]]))
+        ]]), inspect(level5, {depth = 4}))
 
-        assert.equals(inspect(level5, {depth = 0}), "{...}")
+        assert.equals("{...}", inspect(level5, {depth = 0}))
       end)
 
       it('respects depth on keys', function()
-        assert.equals(inspect(keys, {depth = 4}), unindent([[
+        assert.equals(unindent([[
           {
             [{ 1, 2, 3,
               a = {
@@ -193,7 +237,7 @@ describe( 'inspect', function()
               }
             }] = true
           }
-        ]]))
+        ]]), inspect(keys, {depth = 4}))
       end)
     end)
 
@@ -201,7 +245,7 @@ describe( 'inspect', function()
       it('changes the substring used for newlines', function()
         local t = {a={b=1}}
 
-        assert.equal(inspect(t, {newline='@'}), "{@  a = {@    b = 1@  }@}")
+        assert.equal("{@  a = {@    b = 1@  }@}", inspect(t, {newline='@'}))
       end)
     end)
 
@@ -209,7 +253,7 @@ describe( 'inspect', function()
       it('changes the substring used for indenting', function()
         local t = {a={b=1}}
 
-        assert.equal(inspect(t, {indent='>>>'}), "{\n>>>a = {\n>>>>>>b = 1\n>>>}\n}")
+        assert.equal("{\n>>>a = {\n>>>>>>b = 1\n>>>}\n}", inspect(t, {indent='>>>'}))
       end)
     end)
 
@@ -218,56 +262,56 @@ describe( 'inspect', function()
       it('removes one element', function()
         local names     = {'Andrew', 'Peter', 'Ann' }
         local removeAnn = function(item) if item ~= 'Ann' then return item end end
-        assert.equals(inspect(names, {process = removeAnn}), '{ "Andrew", "Peter" }')
+        assert.equals('{ "Andrew", "Peter" }', inspect(names, {process = removeAnn}))
       end)
 
       it('uses the path', function()
         local names     = {'Andrew', 'Peter', 'Ann' }
         local removeThird = function(item, path) if path[1] ~= 3 then return item end end
-        assert.equals(inspect(names, {process = removeThird}), '{ "Andrew", "Peter" }')
+        assert.equals('{ "Andrew", "Peter" }', inspect(names, {process = removeThird}))
       end)
 
       it('replaces items', function()
         local names     = {'Andrew', 'Peter', 'Ann' }
         local filterAnn = function(item) return item == 'Ann' and '<filtered>' or item end
-        assert.equals(inspect(names, {process = filterAnn}), '{ "Andrew", "Peter", "<filtered>" }')
+        assert.equals('{ "Andrew", "Peter", "<filtered>" }', inspect(names, {process = filterAnn}))
       end)
 
       it('nullifies metatables', function()
         local mt       = {'world'}
         local t        = setmetatable({'hello'}, mt)
         local removeMt = function(item) if item ~= mt then return item end end
-        assert.equals(inspect(t, {process = removeMt}), '{ "hello" }')
+        assert.equals('{ "hello" }', inspect(t, {process = removeMt}))
       end)
 
       it('nullifies metatables using their paths', function()
         local mt       = {'world'}
         local t        = setmetatable({'hello'}, mt)
         local removeMt = function(item, path) if path[#path] ~= inspect.METATABLE then return item end end
-        assert.equals(inspect(t, {process = removeMt}), '{ "hello" }')
+        assert.equals('{ "hello" }', inspect(t, {process = removeMt}))
       end)
 
       it('nullifies the root object', function()
         local names     = {'Andrew', 'Peter', 'Ann' }
         local removeNames = function(item) if item ~= names then return item end end
-        assert.equals(inspect(names, {process = removeNames}), 'nil')
+        assert.equals('nil', inspect(names, {process = removeNames}))
       end)
 
       it('changes keys', function()
         local dict = {a = 1}
-        local changeKey = function(item, path) return item == 'a' and 'x' or item end
-        assert.equals(inspect(dict, {process = changeKey}), '{\n  x = 1\n}')
+        local changeKey = function(item) return item == 'a' and 'x' or item end
+        assert.equals('{\n  x = 1\n}', inspect(dict, {process = changeKey}))
       end)
 
       it('nullifies keys', function()
         local dict = {a = 1, b = 2}
-        local removeA = function(item, path) return item ~= 'a' and item or nil end
-        assert.equals(inspect(dict, {process = removeA}), '{\n  b = 2\n}')
+        local removeA = function(item) return item ~= 'a' and item or nil end
+        assert.equals('{\n  b = 2\n}', inspect(dict, {process = removeA}))
       end)
 
       it('prints inspect.KEY & inspect.METATABLE', function()
         local t = {inspect.KEY, inspect.METATABLE}
-        assert.equals(inspect(t), "{ inspect.KEY, inspect.METATABLE }")
+        assert.equals("{ inspect.KEY, inspect.METATABLE }", inspect(t))
       end)
 
       it('marks key paths with inspect.KEY and metatables with inspect.METATABLE', function()
@@ -281,7 +325,7 @@ describe( 'inspect', function()
 
         inspect(t, {process = addItem})
 
-        assert.same(items, {
+        assert.same({
           {item = t,                           path = {}},
           {item = {a=1},                       path = {{a=1}, inspect.KEY}},
           {item = 'a',                         path = {{a=1}, inspect.KEY, 'a', inspect.KEY}},
@@ -292,9 +336,15 @@ describe( 'inspect', function()
           {item = {c=3},                       path = {{a=1}, inspect.METATABLE}},
           {item = 'c',                         path = {{a=1}, inspect.METATABLE, 'c', inspect.KEY}},
           {item = 3,                           path = {{a=1}, inspect.METATABLE, 'c'}}
-        })
+        }, items)
 
       end)
+
+      it('handles recursive tables correctly', function()
+          local tbl = { 1,2,3}
+          tbl.loop = tbl
+          inspect(tbl, { process=function(x) return x end})
+      end)
     end)
 
     describe('metatables', function()
@@ -302,7 +352,7 @@ describe( 'inspect', function()
       it('includes the metatable as an extra hash attribute', function()
         local foo = { foo = 1, __mode = 'v' }
         local bar = setmetatable({a = 1}, foo)
-        assert.equals(inspect(bar), unindent([[
+        assert.equals(unindent([[
           {
             a = 1,
             <metatable> = {
@@ -310,60 +360,101 @@ describe( 'inspect', function()
               foo = 1
             }
           }
-        ]]))
+        ]]), inspect(bar))
       end)
 
-      it('includes the __tostring metamethod if it exists', function()
-        local foo = { foo = 1, __tostring = function() return 'hello\nworld' end }
-        local bar = setmetatable({a = 1}, foo)
-        assert.equals(inspect(bar), unindent([[
-          { -- hello\nworld
-            a = 1,
+      it('can be used on the __tostring metamethod of a table without errors', function()
+        local f = function(x) return inspect(x) end
+        local tbl = setmetatable({ x = 1 }, { __tostring = f })
+        assert.equals(unindent([[
+          {
+            x = 1,
             <metatable> = {
-              __tostring = <function 1>,
-              foo = 1
+              __tostring = <function 1>
             }
           }
-        ]]))
+        ]]), tostring(tbl))
       end)
 
-      it('includes an error string if __tostring metamethod throws an error', function()
-        local foo = { foo = 1, __tostring = function() error('hello', 0) end }
-        local bar = setmetatable({a = 1}, foo)
-        assert.equals(inspect(bar), unindent([[
-          { -- error: hello
-            a = 1,
-            <metatable> = {
-              __tostring = <function 1>,
-              foo = 1
-            }
+      it('does not allow collecting weak tables while they are being inspected', function()
+        collectgarbage('stop')
+        finally(function() collectgarbage('restart') end)
+        local shimMetatable = {
+          __mode = 'v',
+          __index = function() return {} end,
+        }
+        local function shim() return setmetatable({}, shimMetatable) end
+        local t = shim()
+        t.key = shim()
+        assert.equals(unindent([[
+          {
+            key = {
+              <metatable> = <1>{
+                __index = <function 1>,
+                __mode = "v"
+              }
+            },
+            <metatable> = <table 1>
           }
-        ]]))
+        ]]), inspect(t))
+      end)
+
+      it('ignores metatables with __metatable field set to non-nil and non-table type', function()
+        local function process(item) return item end
+        local function inspector(data) return inspect(data, {process=process}) end
+
+        local foo = setmetatable({}, {__metatable=false})
+        local bar = setmetatable({}, {__metatable=true})
+        local baz = setmetatable({}, {__metatable=10})
+        local spam = setmetatable({}, {__metatable=nil})
+        local eggs = setmetatable({}, {__metatable={}})
+        assert.equals(unindent('{}'), inspector(foo))
+        assert.equals(unindent('{}'), inspector(bar))
+        assert.equals(unindent('{}'), inspector(baz))
+        assert.equals(unindent([[
+          {
+            <metatable> = {}
+          }
+        ]]), inspector(spam))
+        assert.equals(unindent([[
+          {
+            <metatable> = {}
+          }
+        ]]), inspector(eggs))
       end)
 
       describe('When a table is its own metatable', function()
         it('accepts a table that is its own metatable without stack overflowing', function()
           local x = {}
           setmetatable(x,x)
-          assert.equals(inspect(x), unindent([[
+          assert.equals(unindent([[
             <1>{
               <metatable> = <table 1>
             }
-          ]]))
+          ]]), inspect(x))
         end)
 
         it('can invoke the __tostring method without stack overflowing', function()
           local t = {}
           t.__index = t
           setmetatable(t,t)
-          assert.equals(inspect(t), unindent([[
+          assert.equals(unindent([[
             <1>{
               __index = <table 1>,
               <metatable> = <table 1>
             }
-          ]]))
+          ]]), inspect(t))
         end)
       end)
     end)
   end)
+
+  it('allows changing the global tostring', function()
+    local save = _G.tostring
+    _G.tostring = inspect
+    local s = tostring({1, 2, 3})
+    _G.tostring = save
+    assert.equals("{ 1, 2, 3 }", s)
+  end)
+
 end)