inspect.lua/inspect.tl

-- inspect.tl
local record inspect
   _VERSION: string
   _URL: string
   _DESCRIPTION: string
   _LICENSE: string
   KEY: table
   METATABLE: table

   type ProcessFunction = function(any, {any}): any

   record Options
      depth: integer
      newline: string
      indent: string
      process: ProcessFunction
   end
end

inspect._VERSION = 'inspect.lua 3.1.0'
inspect._URL     = 'http://github.com/kikito/inspect.lua'
inspect._DESCRIPTION = 'human-readable representations of tables'
inspect._LICENSE = [[
  MIT LICENSE

  Copyright (c) 2022 Enrique García Cota

  Permission is hereby granted, free of charge, to any person obtaining a
  copy of this software and associated documentation files (the
  "Software"), to deal in the Software without restriction, including
  without limitation the rights to use, copy, modify, merge, publish,
  distribute, sublicense, and/or sell copies of the Software, and to
  permit persons to whom the Software is furnished to do so, subject to
  the following conditions:

  The above copyright notice and this permission notice shall be included
  in all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
]]
inspect.KEY       = setmetatable({}, {__tostring = function(): string return 'inspect.KEY' end})
inspect.METATABLE = setmetatable({}, {__tostring = function(): string return 'inspect.METATABLE' end})

local tostring = tostring

local function rawpairs(t: table): function, table, nil
   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: string): string
   if str:match('"') and not str:match("'") then
      return "'" .. str .. "'"
   end
   return '"' .. str:gsub('"', '\\"') .. '"'
end

-- \a => '\\a', \0 => '\\0', 31 => '\31'
local shortControlCharEscapes: {string:string} = {
   ["\a"] = "\\a",  ["\b"] = "\\b", ["\f"] = "\\f", ["\n"] = "\\n",
   ["\r"] = "\\r",  ["\t"] = "\\t", ["\v"] = "\\v", ["\127"] = "\\127",
}
local longControlCharEscapes: {string:string} = {["\127"]="\127"} -- \a => nil, \0 => \000, 31 => \031
for i=0, 31 do
   local ch: string = string.char(i)
   if not shortControlCharEscapes[ch] then
      shortControlCharEscapes[ch] = "\\"..i
      longControlCharEscapes[ch]  = string.format("\\%03d", i)
   end
end

local function escape(str: string): string
   return (str:gsub("\\", "\\\\")
              :gsub("(%c)%f[0-9]", longControlCharEscapes)
              :gsub("%c", shortControlCharEscapes))
end

local function isIdentifier(str: any): boolean
   return str is string and not not str:match("^[_%a][_%a%d]*$")
end

local flr = math.floor
local function isSequenceKey(k: any, sequenceLength: integer): boolean
   return k is number
      and flr(k) == k
      and 1 <= (k)
      and k <= sequenceLength
end

local defaultTypeOrders: {string:integer} = {
   ['number']   = 1, ['boolean']  = 2, ['string'] = 3, ['table'] = 4,
   ['function'] = 5, ['userdata'] = 6, ['thread'] = 7
}

local function sortKeys(a:any, b:any): boolean
   local ta, tb: string, string = type(a), type(b)

   -- strings and numbers are sorted numerically/alphabetically
   if ta == tb and (ta == 'string' or ta == 'number') then
      return (a as string) < (b as string)
   end

   local dta, dtb: integer, integer = defaultTypeOrders[ta], defaultTypeOrders[tb]
   -- Two default types are compared according to the defaultTypeOrders table
   if dta and dtb then return defaultTypeOrders[ta] < defaultTypeOrders[tb]
   elseif dta     then return true  -- default types before custom ones
   elseif dtb     then return false -- custom types after default ones
   end

   -- custom types are sorted out alphabetically
   return ta < tb
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: table): integer
   local len: integer = 1
   local v: any = rawget(t, len)
   while v ~= nil do
      len = len + 1
      v = rawget(t,len)
   end
   return len - 1
end

local function getNonSequentialKeys(t: table): {any}, integer, integer
   local keys, keysLength: {any}, integer = {}, 0
   local sequenceLength: integer = 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, keysLength, sequenceLength
end

local function countTableAppearances(t: any, tableAppearances: {any:integer}): {any:integer}
   tableAppearances = tableAppearances or {}

   if t is table then
      if not tableAppearances[t] then
         tableAppearances[t] = 1
         for k,v in rawpairs(t) do
            countTableAppearances(k, tableAppearances)
            countTableAppearances(v, tableAppearances)
         end
         countTableAppearances(getmetatable(t), tableAppearances)
      else
         tableAppearances[t] = tableAppearances[t] + 1
      end
   end

   return tableAppearances
end

local function makePath(path: {any}, a: any, b: any): {any}
   local newPath: {any} = {}
   local len: integer = #path
   for i=1, len do newPath[i] = path[i] end

   newPath[len + 1] = a
   newPath[len + 2] = b

   return newPath
end


local function processRecursive(process: inspect.ProcessFunction,
                                item: any,
                                path: {any},
                                visited: {any:any}): any
   if item == nil then return nil end
   if visited[item] then return visited[item] end

   local processed: any = process(item, path)
   if processed is table then
      local processedCopy = {}
      visited[item] = processedCopy
      local processedKey: any

      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), visited)
         end
      end

      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 as metatable<{any:any}>)
      processed = processedCopy
   end
   return processed
end



-------------------------------------------------------------------

local type Inspector = record
   depth: integer
   level: integer
   buffer: {string}
   ids: {any:integer}
   maxIds: {any:integer}
   newline: string
   indent: string
   tableAppearances: {table: integer}
end

local Inspector_mt = {__index = Inspector}

function Inspector:puts(a:string, b:string, c:string, d:string, e:string): nil
   local buffer: {string} = self.buffer
   local len: integer     = #buffer
   buffer[len+1] = a
   buffer[len+2] = b
   buffer[len+3] = c
   buffer[len+4] = d
   buffer[len+5] = e
end

function Inspector:down(f: function()): nil
   self.level = self.level + 1
   f()
   self.level = self.level - 1
end

function Inspector:tabify(): nil
   self:puts(self.newline,
   string.rep(self.indent, self.level))
end

function Inspector:alreadyVisited(v: any): boolean
   return self.ids[v] ~= nil
end

function Inspector:getId(v: any): string
   local id: integer = self.ids[v]
   if not id then
      local tv: string = type(v)
      id              = (self.maxIds[tv] or 0) + 1
      self.maxIds[tv] = id
      self.ids[v]     = id
   end
   return tostring(id)
end

-- dummy function; defined later
function Inspector:putValue(_: any):nil
end

function Inspector:putKey(k: any): nil
   if isIdentifier(k) then
      self:puts(k as string)
      return
   end
   self:puts("[")
   self:putValue(k)
   self:puts("]")
end

function Inspector:putTable(t: table): nil
   if t == inspect.KEY or t == inspect.METATABLE then
      self:puts(tostring(t))
   elseif self:alreadyVisited(t) then
      self:puts('<table ', self:getId(t), '>')
   elseif self.level >= self.depth then
      self:puts('{...}')
   else
      if self.tableAppearances[t] > 1 then self:puts('<', self:getId(t), '>') end

      local nonSequentialKeys, nonSequentialKeysLength, sequenceLength = getNonSequentialKeys(t)
      local mt = getmetatable(t)

      self:puts('{')
      self:down(function()
         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 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 type(mt) == 'table' then
            if count > 0 then self:puts(',') end
            self:tabify()
            self:puts('<metatable> = ')
            self:putValue(mt)
         end
      end)

      if nonSequentialKeysLength > 0 or type(mt) == 'table' then -- result is multi-lined. Justify closing }
         self:tabify()
      elseif sequenceLength > 0 then -- array tables have one extra space before closing }
         self:puts(' ')
      end

      self:puts('}')
   end
end

function Inspector:putValue(v: any)
   local tv: string = type(v)
   if tv == 'string' then
      self:puts(smartQuote(escape(v as string)))
   elseif tv == 'number' or tv == 'boolean' or tv == 'nil' or
          tv == 'cdata' or tv == 'ctype' then
      self:puts(tostring(v as number))
   elseif tv == 'table' then
      self:putTable(v as table)
   else
      self:puts('<', tv, ' ', self:getId(v), '>')
   end
end

-------------------------------------------------------------------


function inspect.inspect(root: any, options: inspect.Options): string
   options       = options or {}

   local depth: integer  = options.depth   or (math.huge as integer)
   local newline: string = options.newline or '\n'
   local indent: string  = options.indent  or '  '
   local process: inspect.ProcessFunction = options.process

   if process then
      root = processRecursive(process, root, {}, {})
   end

   local inspector = setmetatable({
      depth            = depth,
      level            = 0,
      buffer           = {},
      ids              = {},
      maxIds           = {},
      newline          = newline,
      indent           = indent,
      tableAppearances = countTableAppearances(root)
   } as Inspector, Inspector_mt)

   inspector:putValue(root)

   return table.concat(inspector.buffer)
end

setmetatable(inspect, {
   __call = function(_, root: any, options: inspect.Options): string
      return inspect.inspect(root, options)
   end
})

return inspect