{"id":"evaera/inspect","name":"inspect","scope":"evaera","platform":"roblox","description":"Lua Inspect but for Roblox","version":"0.0.1","latest":"0.0.1","versions":["0.0.1"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"99ea6cf2d13bdcc3e3f92c313dab79eb48c82e33ebec365dbe444f4eb19bbe8f","likes":0,"downloads":0,"install":"forest install evaera/inspect","url":"https://forest.dev/p/roblox/evaera/inspect","files":"https://api.forest.dev/ai/package/roblox/evaera/inspect/files","readme":"inspect.lua but for Roblox\r\n\r\n---------------------------------------------------\r\n\r\ninspect.lua\r\n===========\r\n\r\n[![Build Status](https://travis-ci.org/kikito/inspect.lua.png?branch=master)](https://travis-ci.org/kikito/inspect.lua)\r\n[![Coverage Status](https://coveralls.io/repos/github/kikito/inspect.lua/badge.svg?branch=master)](https://coveralls.io/github/kikito/inspect.lua?branch=master)\r\n\r\n\r\nThis library transforms any Lua value into a human-readable representation. It is especially useful for debugging errors in tables.\r\n\r\nThe objective here is human understanding (i.e. for debugging), not serialization or compactness.\r\n\r\nExamples of use\r\n===============\r\n\r\n`inspect` has the following declaration: `local str = inspect(value, <options>)`.\r\n\r\n`value` can be any Lua value.\r\n\r\n`inspect` transforms simple types (like strings or numbers) into strings.\r\n\r\n```lua\r\nassert(inspect(1) == \"1\")\r\nassert(inspect(\"Hello\") == '\"Hello\"')\r\n```\r\n\r\nTables, on the other hand, are rendered in a way a human can read easily.\r\n\r\n\"Array-like\" tables are rendered horizontally:\r\n\r\n```lua\r\nassert(inspect({1,2,3,4}) == \"{ 1, 2, 3, 4 }\")\r\n```\r\n\r\n\"Dictionary-like\" tables are rendered with one element per line:\r\n\r\n```lua\r\nassert(inspect({a=1,b=2}) == [[{\r\n  a = 1,\r\n  b = 2\r\n}]])\r\n```\r\n\r\nThe keys will be sorted alphanumerically when possible.\r\n\r\n\"Hybrid\" tables will have the array part on the first line, and the dictionary part just below them:\r\n\r\n```lua\r\nassert(inspect({1,2,3,b=2,a=1}) == [[{ 1, 2, 3,\r\n  a = 1,\r\n  b = 2\r\n}]])\r\n```\r\n\r\nSubtables are indented with two spaces per level.\r\n\r\n```lua\r\nassert(inspect({a={b=2}}) == [[{\r\n  a = {\r\n    b = 2\r\n  }\r\n}]])\r\n```\r\n\r\nFunctions, userdata and any other custom types from Luajit are simply as `<function x>`, `<userdata x>`, etc.:\r\n\r\n```lua\r\nassert(inspect({ f = print, ud = some_user_data, thread = a_thread} ) == [[{\r\n  f = <function 1>,\r\n  u = <userdata 1>,\r\n  thread = <thread 1>\r\n}]])\r\n```\r\n\r\nIf the table has a metatable, inspect will include it at the end, in a special field called `<metatable>`:\r\n\r\n```lua\r\nassert(inspect(setmetatable({a=1}, {b=2}) == [[{\r\n  a = 1\r\n  <metatable> = {\r\n    b = 2\r\n  }\r\n}]]))\r\n```\r\n\r\n`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.\r\n\r\n```lua\r\nlocal a = {1, 2}\r\nlocal b = {3, 4, a}\r\na[3] = b -- a references b, and b references a\r\nassert(inspect(a) == \"<1>{ 1, 2, { 3, 4, <table 1> } }\")\r\n```\r\n\r\nNotice 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.\r\n\r\n### options\r\n\r\n`inspect` has a second parameter, called `options`. It is not mandatory, but when it is provided, it must be a table.\r\n\r\n#### options.depth\r\n\r\n`options.depth` sets the maximum depth that will be printed out.\r\nWhen the max depth is reached, `inspect` will stop parsing tables and just return `{...}`:\r\n\r\n```lua\r\n\r\nlocal t5 = {a = {b = {c = {d = {e = 5}}}}}\r\n\r\nassert(inspect(t5, {depth = 4}) == [[{\r\n  a = {\r\n    b = {\r\n      c = {\r\n        d = {...}\r\n      }\r\n    }\r\n  }\r\n}]])\r\n\r\nassert(inspect(t5, {depth = 2}) == [[{\r\n  a = {\r\n    b = {...}\r\n  }\r\n}]])\r\n\r\n```\r\n\r\n`options.depth` defaults to infinite (`math.huge`).\r\n\r\n#### options.newline & options.indent\r\n\r\nThese are the strings used by `inspect` to respectively add a newline and indent each level of a table.\r\n\r\nBy default, `options.newline` is `\"\\n\"` and `options.indent` is `\"  \"` (two spaces).\r\n\r\n``` lua\r\nlocal t = {a={b=1}}\r\n\r\nassert(inspect(t) == [[{\r\n  a = {\r\n    b = 1\r\n  }\r\n}]])\r\n\r\nassert(inspect(t, {newline='@', indent=\"++\"}), \"{@++a = {@++++b = 1@++}@}\"\r\n```\r\n\r\n#### options.process\r\n\r\n`options.process` is a function which allow altering the passed object before transforming it into a string.\r\nA typical way to use it would be to remove certain values so that they don't appear at all.\r\n\r\n`options.process` has the following signature:\r\n\r\n``` lua\r\nlocal processed_item = function(item, path)\r\n```\r\n\r\n* `item` is either a key or a value on the table, or any of its subtables\r\n* `path` is an array-like table built with all the keys that have been used to reach `item`, from the root.\r\n  * For values, it is just a regular list of keys. For example, to reach the 1 in `{a = {b = 1}}`, the `path`\r\n    will be `{'a', 'b'}`\r\n  * For keys, the special value `inspect.KEY` is inserted. For example, to reach the `c` in `{a = {b = {c = 1}}}`,\r\n    the path will be `{'a', 'b', 'c', inspect.KEY }`\r\n  * For metatables, the special value `inspect.METATABLE` is inserted. For `{a = {b = 1}}}`, the path\r\n    `{'a', {b = 1}, inspect.METATABLE}` means \"the metatable of the table `{b = 1}`\".\r\n* `processed_item` is the value returned by `options.process`. If it is equal to `item`, then the inspected\r\n  table will look unchanged. If it is different, then the table will look different; most notably, if it's `nil`,\r\n  the item will dissapear on the inspected table.\r\n\r\n#### Examples\r\n\r\nRemove a particular metatable from the result:\r\n\r\n``` lua\r\nlocal t = {1,2,3}\r\nlocal mt = {b = 2}\r\nsetmetatable(t, mt)\r\n\r\nlocal remove_mt = function(item)\r\n  if item ~= mt then return item end\r\nend\r\n\r\n-- mt does not appear\r\nassert(inspect(t, {process = remove_mt}) == \"{ 1, 2, 3 }\")\r\n```\r\n\r\nThe previous exaple only works for a particular metatable. If you want to make *all* metatables, you can use the `path` parameter to check\r\nwether the last element is `inspect.METATABLE`, and return `nil` instead of the item:\r\n\r\n``` lua\r\nlocal t, mt = ... -- (defined as before)\r\n\r\nlocal remove_all_metatables = function(item, path)\r\n  if path[#path] ~= inspect.METATABLE then return item end\r\nend\r\n\r\nassert(inspect(t, {process = remove_all_metatables}) == \"{ 1, 2, 3 }\")\r\n```\r\n\r\nFilter a value:\r\n\r\n```lua\r\nlocal anonymize_password = function(item, path)\r\n  if path[#path] == 'password' then return \"XXXX\" end\r\n  return item\r\nend\r\n\r\nlocal info = {user = 'peter', password = 'secret'}\r\n\r\nassert(inspect(info, {process = anonymize_password}) == [[{\r\n  password = \"XXXX\",\r\n  user     = \"peter\"\r\n}]])\r\n```\r\n\r\nGotchas / Warnings\r\n==================\r\n\r\nThis method is *not* appropriate for saving/restoring tables. It is meant to be used by the programmer mainly while debugging a program.\r\n\r\nInstallation\r\n============\r\n\r\nIf you are using luarocks, just run\r\n\r\n    luarocks install inspect\r\n\r\nOtherwise, you can just copy the inspect.lua file somewhere in your projects (maybe inside a /lib/ folder) and require it accordingly.\r\n\r\nRemember to store the value returned by require somewhere! (I suggest a local variable named inspect, although others might like table.inspect)\r\n\r\n    local inspect = require 'inspect'\r\n          -- or --\r\n    local inspect = require 'lib.inspect'\r\n\r\nAlso, 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.\r\n\r\nSpecs\r\n=====\r\n\r\nThis project uses [busted](http://olivinelabs.com/busted/) for its specs. If you want to run the specs, you will have to install busted first. Then just execute the following from the root inspect folder:\r\n\r\n    busted\r\n\r\nChange log\r\n==========\r\n\r\nRead it on the CHANGELOG.md file\r\n\r\n\r\n\r\n\r\n\r\n","readmeTruncated":false}