test/lua/inspect.lua

   1 -------------------------------------------------------------------
   2 -- This was changed for Wireshark's use by Hadriel Kaplan.
   3 --
   4 -- Changes made:
   5 -- * provided 'serialize' option to output serialized info (ie, can be marshaled),
   6 --   though note that serializing functions/metatables/userdata/threads will not
   7 --   magically make them be their original type when marshaled.
   8 -- * provided 'notostring' option, which if true will disabled calling __tostring
   9 --   metamethod of tables.
  10 -- * made it always print the index number of numbered-array entries, and on separate
  11 --   lines like the normal key'd entries (much easier to read this way I think)
  12 -- New public functions:
  13 -- inspect.compare(first,second[,options])
  14 -- inspect.marshal(inString[,options])
  15 -- inspect.makeFilter(arrayTable)
  16 --
  17 -- For the *changes*:
  18 -- Copyright (c) 2014, Hadriel Kaplan
  19 -- My change to the code is in the Public Domain, or the BSD (3 clause) license if
  20 -- Public Domain does not apply in your country, or you would prefer a BSD license.
  21 -- But the original code is still under Enrique García Cota's MIT license (below).
  22 -------------------------------------------------------------------
  23
  24 local inspect ={
  25   _VERSION = 'inspect.lua 2.0.0 - with changes',
  26   _URL     = 'http://github.com/kikito/inspect.lua',
  27   _DESCRIPTION = 'human-readable representations of tables',
  28   _LICENSE = [[
  29     MIT LICENSE
  30
  31     Copyright (c) 2013 Enrique García Cota
  32
  33     Permission is hereby granted, free of charge, to any person obtaining a
  34     copy of this software and associated documentation files (the
  35     "Software"), to deal in the Software without restriction, including
  36     without limitation the rights to use, copy, modify, merge, publish,
  37     distribute, sublicense, and/or sell copies of the Software, and to
  38     permit persons to whom the Software is furnished to do so, subject to
  39     the following conditions:
  40
  41     The above copyright notice and this permission notice shall be included
  42     in all copies or substantial portions of the Software.
  43
  44     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  45     OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  46     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  47     IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  48     CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  49     TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  50     SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  51   ]],
  52   _TINDEX_KEY    = '<index>', -- the key name to use for index number entries for tables
  53   _DEPTH_MARKER  = " ['<depth>'] = true " -- instead of printing '...' we print this
  54 }
  55
  56 -- Apostrophizes the string if it has quotes, but not apostrophes
  57 -- Otherwise, it returns a regular quoted string
  58 local function smartQuote(str)
  59   if str:match('"') and not str:match("'") then
  60     return "'" .. str .. "'"
  61   end
  62   return '"' .. str:gsub('"', '\\"') .. '"'
  63 end
  64
  65 local controlCharsTranslation = {
  66   ["\a"] = "\\a",  ["\b"] = "\\b", ["\f"] = "\\f",  ["\n"] = "\\n",
  67   ["\r"] = "\\r",  ["\t"] = "\\t", ["\v"] = "\\v"
  68 }
  69
  70 local function escapeChar(c) return controlCharsTranslation[c] end
  71
  72 local function escape(str)
  73   local result = str:gsub("\\", "\\\\"):gsub("(%c)", escapeChar)
  74   return result
  75 end
  76
  77 local function isIdentifier(str)
  78   return type(str) == 'string' and str:match( "^[_%a][_%a%d]*$" )
  79 end
  80
  81 local function isArrayKey(k, length)
  82   return type(k) == 'number' and 1 <= k and k <= length
  83 end
  84
  85 local function isDictionaryKey(k, length)
  86   return not isArrayKey(k, length)
  87 end
  88
  89 local defaultTypeOrders = {
  90   ['number']   = 1, ['boolean']  = 2, ['string'] = 3, ['table'] = 4,
  91   ['function'] = 5, ['userdata'] = 6, ['thread'] = 7
  92 }
  93
  94 local function sortKeys(a, b)
  95   local ta, tb = type(a), type(b)
  96
  97   -- strings and numbers are sorted numerically/alphabetically
  98   if ta == tb and (ta == 'string' or ta == 'number') then return a < b end
  99
 100   local dta, dtb = defaultTypeOrders[ta], defaultTypeOrders[tb]
 101   -- Two default types are compared according to the defaultTypeOrders table
 102   if dta and dtb then return defaultTypeOrders[ta] < defaultTypeOrders[tb]
 103   elseif dta     then return true  -- default types before custom ones
 104   elseif dtb     then return false -- custom types after default ones
 105   end
 106
 107   -- custom types are sorted out alphabetically
 108   return ta < tb
 109 end
 110
 111 local function getDictionaryKeys(t)
 112   local keys, length = {}, #t
 113   for k,_ in pairs(t) do
 114     if isDictionaryKey(k, length) then table.insert(keys, k) end
 115   end
 116   table.sort(keys, sortKeys)
 117   return keys
 118 end
 119
 120 local function getToStringResultSafely(t, mt)
 121   local __tostring = type(mt) == 'table' and rawget(mt, '__tostring')
 122   local str, ok
 123   if type(__tostring) == 'function' then
 124     ok, str = pcall(__tostring, t)
 125     str = ok and str or 'error: ' .. tostring(str)
 126   end
 127   if type(str) == 'string' and #str > 0 then return str end
 128 end
 129
 130 local maxIdsMetaTable = {
 131   __index = function(self, typeName)
 132     rawset(self, typeName, 0)
 133     return 0
 134   end
 135 }
 136
 137 local idsMetaTable = {
 138   __index = function (self, typeName)
 139     local col = setmetatable({}, {__mode = "kv"})
 140     rawset(self, typeName, col)
 141     return col
 142   end
 143 }
 144
 145 local function countTableAppearances(t, tableAppearances)
 146   tableAppearances = tableAppearances or setmetatable({}, {__mode = "k"})
 147
 148   if type(t) == 'table' then
 149     if not tableAppearances[t] then
 150       tableAppearances[t] = 1
 151       for k,v in pairs(t) do
 152         countTableAppearances(k, tableAppearances)
 153         countTableAppearances(v, tableAppearances)
 154       end
 155       countTableAppearances(getmetatable(t), tableAppearances)
 156     else
 157       tableAppearances[t] = tableAppearances[t] + 1
 158     end
 159   end
 160
 161   return tableAppearances
 162 end
 163
 164 local function parse_filter(filter)
 165   if type(filter) == 'function' then return filter end
 166   -- not a function, so it must be a table or table-like
 167   filter = type(filter) == 'table' and filter or {filter}
 168   local dictionary = {}
 169   for _,v in pairs(filter) do dictionary[v] = true end
 170   return function(x) return dictionary[x] end
 171 end
 172
 173 local function makePath(path, key)
 174   local newPath, len = {}, #path
 175   for i=1, len do newPath[i] = path[i] end
 176   newPath[len+1] = key
 177   return newPath
 178 end
 179
 180 -------------------------------------------------------------------
 181 function inspect.inspect(rootObject, options)
 182   options       = options or {}
 183   local depth   = options.depth or math.huge
 184   local filter  = parse_filter(options.filter or {})
 185   local serialize  = options.serialize
 186
 187   local depth_marker = inspect._DEPTH_MARKER
 188
 189   local tableAppearances = countTableAppearances(rootObject)
 190
 191   local buffer = {}
 192   local maxIds = setmetatable({}, maxIdsMetaTable)
 193   local ids    = setmetatable({}, idsMetaTable)
 194   local level  = 0
 195   local blen   = 0 -- buffer length
 196
 197   local function puts(...)
 198     local args = {...}
 199     for i=1, #args do
 200       blen = blen + 1
 201       buffer[blen] = tostring(args[i])
 202     end
 203   end
 204
 205   -- like puts above, but for things we want as quoted strings
 206   -- so they become values, as we do if serializing
 207   local function putv(...)
 208     blen = blen + 1
 209     buffer[blen] = "'"
 210     puts(...)
 211     blen = blen + 1
 212     buffer[blen] = "'"
 213   end
 214
 215   -- if serializing, using raw strings is unsafe, so we use the full "['key']" style
 216   local function putk(...)
 217     blen = blen + 1
 218     buffer[blen] = "['"
 219     puts(...)
 220     blen = blen + 1
 221     buffer[blen] = "']"
 222   end
 223
 224   -- if not serializing, it's all puts
 225   if not serialize then
 226     putv = puts
 227     putk = puts
 228     depth_marker = '...'
 229   end
 230
 231   -- disable using __tostring metamethod
 232   local getToStringResultSafely = getToStringResultSafely
 233   if options.notostring or serialize then
 234     getToStringResultSafely = function() return end
 235   end
 236
 237   local function down(f)
 238     level = level + 1
 239     f()
 240     level = level - 1
 241   end
 242
 243   local function tabify()
 244     puts("\n", string.rep("    ", level))
 245   end
 246
 247   local function commaControl(needsComma)
 248     if needsComma then puts(',') end
 249     return true
 250   end
 251
 252   local function alreadyVisited(v)
 253     return ids[type(v)][v] ~= nil
 254   end
 255
 256   local function getId(v)
 257     local tv = type(v)
 258     local id = ids[tv][v]
 259     if not id then
 260       id         = maxIds[tv] + 1
 261       maxIds[tv] = id
 262       ids[tv][v] = id
 263     end
 264     return id
 265   end
 266
 267   local putValue -- forward declaration that needs to go before putTable & putKey
 268
 269   local function putKey(k)
 270     if not serialize and isIdentifier(k) then return puts(k) end
 271     puts("[")
 272     putValue(k, {})
 273     puts("]")
 274   end
 275
 276   local function putTable(t, path)
 277     if alreadyVisited(t) then
 278       putv('<table ', getId(t), '>')
 279     elseif level >= depth then
 280       puts('{', depth_marker, '}')
 281     else
 282       if not serialize and tableAppearances[t] > 1 then puts('<', getId(t), '>') end
 283
 284       local dictKeys          = getDictionaryKeys(t)
 285       local length            = #t
 286       local mt                = getmetatable(t)
 287       local to_string_result  = getToStringResultSafely(t, mt)
 288
 289       puts('{')
 290       down(function()
 291         if to_string_result then
 292           puts(' -- ', escape(to_string_result))
 293           if length >= 1 then tabify() end -- tabify the array values
 294         end
 295
 296         local needsComma = false
 297
 298         if serialize and tableAppearances[t] > 1 then
 299           getId(t)
 300         end
 301
 302         for i=1, length do
 303           needsComma = commaControl(needsComma)
 304           -- just doing puts(' ') made for ugly arrays
 305           tabify()
 306           putKey(i)
 307           puts(' = ')
 308           putValue(t[i], makePath(path, i))
 309         end
 310
 311         for _,k in ipairs(dictKeys) do
 312           needsComma = commaControl(needsComma)
 313           tabify()
 314           putKey(k)
 315           puts(' = ')
 316           putValue(t[k], makePath(path, k))
 317         end
 318
 319         if mt then
 320           needsComma = commaControl(needsComma)
 321           tabify()
 322           putk('<metatable>')
 323           puts(' = ')
 324           putValue(mt, makePath(path, '<metatable>'))
 325         end
 326       end)
 327
 328       if #dictKeys > 0 or mt then -- dictionary table. Justify closing }
 329         tabify()
 330       elseif length > 0 then -- array tables have one extra space before closing }
 331         puts(' ')
 332       end
 333
 334       puts('}')
 335     end
 336
 337   end
 338
 339   -- putvalue is forward-declared before putTable & putKey
 340   putValue = function(v, path)
 341     if filter(v, path) then
 342       putv('<filtered>')
 343     else
 344       local tv = type(v)
 345
 346       if tv == 'string' then
 347         puts(smartQuote(escape(v)))
 348       elseif tv == 'number' and v == math.huge then
 349         putv('<number inf>')
 350       elseif tv == 'number' or tv == 'boolean' or tv == 'nil' then
 351         puts(tostring(v))
 352       elseif tv == 'table' then
 353         putTable(v, path)
 354       else
 355         putv('<',tv,' ',getId(v),'>')
 356       end
 357     end
 358   end
 359
 360   putValue(rootObject, {})
 361
 362   return table.concat(buffer)
 363 end
 364
 365 setmetatable(inspect, { __call = function(_, ...) return inspect.inspect(...) end })
 366
 367 -------------------------------------------------------------------
 368
 369 -- The above is very close to Enrique's original inspect library.
 370 -- Below are my main changes.
 371
 372 -------------------------------------------------------------------
 373 -- Given a string generated by inspect() with the serialize option,
 374 -- this function marshals it back into a Lua table/whatever.
 375 -- If the string's table(s) had metatable(s), i.e. "<metatable>" tables,
 376 -- then this keeps them as "<metatable>" subtables unless the option
 377 -- 'nometa' is set to true.
 378 --
 379 -- This function also removes all "<index>" entries.
 380 --
 381 function inspect.marshal(inString, options)
 382   options     = options or {}
 383   local index = inspect._TINDEX_KEY
 384
 385   local function removeIndex(t)
 386     if type(t) == 'table' then
 387       t[index] = nil
 388       for _, v in pairs(t) do
 389         removeIndex(v)
 390       end
 391     end
 392   end
 393
 394   local function removeMeta(t)
 395     if type(t) == 'table' then
 396       t['<metatable>'] = nil
 397       for _, v in pairs(t) do
 398         removeMeta(v)
 399       end
 400     end
 401   end
 402
 403   -- first skip past comments/empty-lines
 404   -- warning: super-hack-ish weak
 405   local pos, ok, dk = 1, true, true
 406   local fin
 407   local stop = string.len(inString)
 408   while ok or dk do
 409     ok, fin = inString:find("^[%s\r\n]+",pos)
 410     if ok then pos = fin + 1 end
 411     dk, fin = inString:find("^%-%-.-\n",pos)
 412     if dk then pos = fin + 1 end
 413   end
 414
 415   if not inString:find("^%s*return[%s%{]",pos) then
 416     inString = "return " .. inString
 417   end
 418
 419   local t = assert(load(inString))()
 420
 421   removeIndex(t)
 422
 423   if options.nometa then removeMeta(t) end
 424
 425   return t
 426 end
 427
 428 -------------------------------------------------------------------
 429
 430 -------------------------------------------------------------------
 431 -- more private functions
 432
 433 -- things like '<function>' are equal to '<function 32>'
 434 local mungetypes = {
 435   {"^<function ?%d*>",  '<function>'},
 436   {"^<table ?%d*>",     '<table>'},
 437   {"^<userdata ?%d*>",  '<userdata>'},
 438   {"^<thread ?%d*>",    '<thread>'}
 439 }
 440 local function normalizeString(s)
 441   for _,t in ipairs(mungetypes) do
 442     if s:find(t[1]) then
 443       return t[2]
 444     end
 445   end
 446   return s
 447 end
 448
 449 local typetable = {
 450   ['<function>']  = 'function',
 451   ['<table>']     = 'table',
 452   ['<userdata>']  = 'userdata',
 453   ['<thread>']    = 'thread'
 454 }
 455 local function getType(v)
 456   local tv = type(v)
 457   if tv == 'string' then
 458     tv = typetable[normalizeString(v)] or 'string'
 459   end
 460   return tv
 461 end
 462
 463 local function tablelength(t)
 464   local count = 0
 465   for _ in pairs(t) do count = count + 1 end
 466   return count
 467 end
 468
 469 -- for pretty-printing paths, for debug output
 470 -- this is non-optimal, but only gets used in verbose mode anyway
 471 local function serializePath(path)
 472   local t = {}
 473   for i,k in ipairs(path) do
 474     local tk = type(k)
 475     if isIdentifier(k) then
 476       t[i] = ((i == 1) and k) or ('.'..k)
 477     elseif tk == 'string' then
 478       t[i] = '[' .. smartQuote(escape(k)) .. ']'
 479     elseif tk == 'number' or tk == 'boolean' then
 480       t[i] = '[' .. tostring(k) .. ']'
 481     else
 482       t[i] = "['<" .. tk .. ">']"
 483     end
 484   end
 485   if #t == 0 then t[1] = '{}' end
 486   return table.concat(t)
 487 end
 488
 489 -------------------------------------------------------------------
 490
 491 -------------------------------------------------------------------
 492 -- Given one table and another, this function detects if the first is
 493 -- completely contained in the second object. The second can have more
 494 -- entries, but cannot be missing an entry in the first one. Entry values
 495 -- must match as well - i.e., string values are the same, numbers the
 496 -- same, booleans the same.
 497 --
 498 -- The function returns true if the first is in the second, false otherwise.
 499 -- It also returns a table of the diff, which will be empty if they matched.
 500 -- This returned table is structured like the first one passed in,
 501 -- so calling print(inspect(returnedTabled)) will make it pretty print.
 502 --
 503 -- The returned table's members have their values replaced with mismatch
 504 -- information, explaining what the mismatch was. Setting the option "keep"
 505 -- makes it not replace the values, but keep them as they were in the first
 506 -- table.
 507 --
 508 -- By default, the key's values must match in both tables.  If the option
 509 -- 'nonumber' is set, then number values are not compared.  This is useful
 510 -- if they're things that can change (like exported C-code numbers).
 511 --
 512 -- By default, the metatables/"<metatables>" are also compared.  If the option
 513 -- 'nometa' is set, then metatables are not compared, nor does it matter if
 514 -- they exist in either table.
 515 --
 516 -- Like inspect(), there's a 'filter' option, which works the same way:
 517 -- it ignores its value completely in terms of matching, so their string values
 518 -- can be different, but the keys still have to exist.  Sub-tables of
 519 -- such keys (i.e., if the key's value is a table) are not checked/compared.
 520 -- In other words, it's identical to the filter option for inspect().
 521 --
 522 -- The option 'ignore' is similar to 'filter', except matching ones
 523 -- are not checked for existence in the tables at all.
 524 --
 525 -- Setting the 'depth' option applies as in inspect(), to both tables.
 526 --
 527 -- Setting the option 'verbose' makes it print out as it compares, for
 528 -- debugging or test purposes.
 529 --
 530 function inspect.compare(firstTable, secondTable, options)
 531   options       = options or {}
 532   local depth   = options.depth or math.huge
 533   local filter  = parse_filter(options.filter or {})
 534   local ignore  = parse_filter(options.ignore or {})
 535
 536   local function puts(...)
 537     local args = {...}
 538     for i=1, #args do
 539       blen = blen + 1
 540       buffer[blen] = tostring(args[i])
 541     end
 542   end
 543
 544   -- for debug printing
 545   local function dprint(...)
 546     local args = {...}
 547     print(table.concat(args))
 548   end
 549
 550   local serializePath = serializePath
 551
 552   if not options.verbose then
 553     dprint = function() return end
 554     serializePath = function() return end
 555   end
 556
 557   -- for error message replacing key value
 558   local function emsg(...)
 559     local args = {...}
 560     return(table.concat(args))
 561   end
 562
 563   if options.keep then
 564     emsg = function() return end
 565   end
 566
 567   -- declare checkValue here
 568   local checkValue
 569
 570   local function checkTable(f, s, path)
 571     dprint("checking ",serializePath(path)," table contents")
 572
 573     for k, v in pairs(f) do
 574       local child = makePath(path, k)
 575
 576       if not ignore(v,child) then
 577         local ret, msg = checkValue(v, s[k], child)
 578         if ret then
 579           f[k] = nil
 580         elseif msg then
 581           f[k] = msg
 582           dprint(serializePath(child)," ",msg)
 583         end
 584       else
 585         dprint("ignoring ",serializePath(child))
 586         f[k] = nil
 587       end
 588     end
 589     return tablelength(f) == 0
 590   end
 591
 592   -- a wrapper for failure cases in checkValue() that can be handled the same way
 593   local function compCheck(f,s,func)
 594     if not func() then
 595       return false, emsg("mismatched ",getType(f)," values: ",tostring(f)," --> ",tostring(s))
 596     end
 597     return true
 598   end
 599
 600   -- kinda ugly, but I wanted pretty information output
 601   checkValue = function(f, s, path)
 602     local tf = getType(f)
 603
 604     dprint("checking ",serializePath(path)," (",tf,")")
 605
 606     if s == nil then
 607       return false, emsg("missing ",tf,"!")
 608     elseif tf ~= getType(s) then
 609       return false, emsg("type mismatch (",tf,") --> (",getType(s),")")
 610     elseif type(f) == 'table' then
 611       return checkTable(f, s, path)
 612     end
 613
 614     return compCheck(f,s,function()
 615       if tf == 'string' or tf == 'boolean' then
 616         return f == s
 617       elseif tf == 'number' then
 618         return f == s or options.nonumber
 619       else
 620         -- assume they're the same functions/userdata/looped-table
 621         -- type matching before would already cover it otherwise
 622         return true
 623       end
 624     end)
 625   end
 626
 627   -- inspect+serialize both tables, to normalize them, separate their
 628   -- metatables, limit depth, etc.  Also, since we pass the filter option on,
 629   -- the filtered items become "<filtered>" and will by definition match
 630   local function normalizeTable(t)
 631     return assert( inspect.marshal( inspect.inspect(t,{serialize=true,depth=depth,filter=filter}), {nometa=options.nometa} ))
 632   end
 633
 634   local first = normalizeTable(firstTable)
 635   local second = normalizeTable(secondTable)
 636
 637   return checkTable(first, second, {}), first
 638
 639 end
 640
 641 -------------------------------------------------------------------
 642
 643
 644
 645 -------------------------------------------------------------------
 646 -- Given a table of key strings, return a function that can be used for
 647 -- the 'filter' option of inspect() and inspect.compare() functions.
 648 function inspect.makeFilter(arrayTable)
 649   local filter = {} -- our filter lookup tree (tables of tables)
 650   local matchNode = {} -- a table instance we use as a key for nodes which match
 651   local wildcard = {} -- a key table of wildcard match names
 652
 653   local function buildFilter(pathname)
 654     local t = filter
 655     local key
 656     -- if the filtered name starts with a '.', it's a wildcard
 657     if pathname:find("^%.") then
 658       wildcard[pathname:sub(2)] = true
 659       return
 660     end
 661     for sep, name in pathname:gmatch("([%.%[\"\']*)([^%.%[\"\'%]]+)[\"\'%]]?") do
 662       if sep == '[' then
 663         if name == 'true' then
 664           key = true
 665         elseif name == 'false' then
 666           key = false
 667         else
 668           key = tonumber(name)
 669         end
 670       else
 671         -- to be safe, we'll check the key name doesn't mean a table/function/userdata
 672         local tn = getType(name)
 673         if tn == 'string' then
 674           key = name
 675         else
 676           error("filter key '"..pathname.."' has key '"..name.."' which is an unsupported type ("..tn..")")
 677         end
 678       end
 679
 680       if not t[key] then
 681         t[key] = {}
 682       end
 683       t = t[key]
 684     end
 685
 686     t[matchNode] = true
 687   end
 688
 689   -- we could call serializePath() and do a simple lookup, but it's expensive and
 690   -- we'd be calling it a LOT.  So instead we break up the filter
 691   -- table into true "path" elements, into a filter tree, and compare
 692   -- against it... thereby avoiding string concat/manip during compare.
 693
 694   for _, pathname in ipairs(arrayTable) do
 695     buildFilter(pathname)
 696   end
 697
 698   return function(value,path)
 699       local t = filter
 700       if wildcard[ path[#path] ] then
 701         return true
 702       end
 703       for _,v in ipairs(path) do
 704           if not t[v] then
 705             return false
 706           end
 707           t = t[v]
 708       end
 709       return t[matchNode] == true
 710     end
 711
 712 end
 713
 714 return inspect
 715