diff options
Diffstat (limited to 'Data/BuiltIn/Libraries/inspect/README.md')
| -rw-r--r-- | Data/BuiltIn/Libraries/inspect/README.md | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/Data/BuiltIn/Libraries/inspect/README.md b/Data/BuiltIn/Libraries/inspect/README.md new file mode 100644 index 0000000..e9c6f86 --- /dev/null +++ b/Data/BuiltIn/Libraries/inspect/README.md @@ -0,0 +1,253 @@ +inspect.lua +=========== + +[](https://travis-ci.org/kikito/inspect.lua) +[](https://coveralls.io/github/kikito/inspect.lua?branch=master) + + +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. + +```lua +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: + +```lua +assert(inspect({1,2,3,4}) == "{ 1, 2, 3, 4 }") +``` + +"Dictionary-like" tables are rendered with one element per line: + +```lua +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: + +```lua +assert(inspect({1,2,3,b=2,a=1}) == [[{ 1, 2, 3, + a = 1, + b = 2 +}]]) +``` + +Subtables are indented with two spaces per level. + +```lua +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.: + +```lua +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>`: + +```lua +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. + +```lua +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 `{...}`: + +```lua + +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). + +``` lua +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: + +``` lua +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: + +``` lua +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 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] ~= inspect.METATABLE then return item end +end + +assert(inspect(t, {process = remove_all_metatables}) == "{ 1, 2, 3 }") +``` + +Filter a value: + +```lua +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. + +Specs +===== + +This 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: + + busted + +Change log +========== + +Read it on the CHANGELOG.md file + + + + + |