diff options
Diffstat (limited to 'Resources/DefaultContent/Libraries/inspect/README.md')
| -rw-r--r-- | Resources/DefaultContent/Libraries/inspect/README.md | 253 |
1 files changed, 0 insertions, 253 deletions
diff --git a/Resources/DefaultContent/Libraries/inspect/README.md b/Resources/DefaultContent/Libraries/inspect/README.md deleted file mode 100644 index e9c6f86..0000000 --- a/Resources/DefaultContent/Libraries/inspect/README.md +++ /dev/null @@ -1,253 +0,0 @@ -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 - - - - - |