updated readme with wishes

README.md

@@ -10,90 +10,204 @@ The objective here is human understanding (i.e. for debugging), not serializatio
 Examples of use
 ===============
 
-`inspect` has the following declaration: `str = inspect(value, <options>)`.
+`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. Tables, on the other
-hand, are rendered in a way a human can understand.
+`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:
 
-    inspect({1,2,3,4}) == "{ 1, 2, 3, 4 }"
+```lua
+assert(inspect({1,2,3,4}) == "{ 1, 2, 3, 4 }")
+```
 
-"dictionary-like" tables are rendered with one element per line:
+"Dictionary-like" tables are rendered with one element per line:
 
-    inspect({a=1,b=2}) == [[{
-      a = 1,
-      b = 2
-    }]]
+```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:
 
-    inspect({1,2,3,b=2,a=1}) == [[{ 1, 2, 3,
-      a = 1,
-      b = 2
-    }]]
+```lua
+assert(inspect({1,2,3,b=2,a=1}) == [[{ 1, 2, 3,
+  a = 1,
+  b = 2
+}]])
+```
 
-Tables can be nested, and will be indented with two spaces per level.
+Subtables are indented with two spaces per level.
 
-    inspect({a={b=2}}) == [[{
-      a = {
-        b = 2
-      }
-    }]]
+```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.:
 
-    inspect({ f = print, ud = some_user_data, thread = a_thread} ) == [[{
-      f = <function 1>,
-      u = <userdata 1>,
-      thread = <thread 1>
-    }]])
+```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>`:
 
-    inspect(setmetatable({a=1}, {b=2}) == [[{
-      a = 1
-      <metatable> = {
-        b = 2
-      }
-    }]])
+```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.
 
-    a = {1, 2}
-    b = {3, 4, a}
-    a[3] = b -- a references b, and b references a
-    inspect(a) = "<1>{ 1, 2, { 3, 4, <table 1> } }"
+```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.depth
+### options
 
-`inspect`'s second parameter allows controlling the maximum depth that will be printed out. When the max depth is reached, it'll just return `{...}`:
+`inspect` has a second parameter, called `options`. It is not mandatory, but when it is provided, it must be a table.
 
-    local t5 = {a = {b = {c = {d = {e = 5}}}}}
+#### options.depth
 
-    inspect(t5, {depth = 4}) == [[{
-      a = {
-        b = {
-          c = {
-            d = {...}
-          }
-        }
-      }
-    }]]
+`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}}}}}
 
-    inspect(t5, {depth = 2}) == [[{
-      a = {
-        b = {...}
+assert(inspect(t5, {depth = 4}) == [[{
+  a = {
+    b = {
+      c = {
+        d = {...}
       }
-    }]])
+    }
+  }
+}]])
+
+assert(inspect(t5, {depth = 2}) == [[{
+  a = {
+    b = {...}
+  }
+}]])
+
+```
 
 `options.depth` defaults to infinite (`math.huge`).
 
-### options.filter
+### 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, a special value called `<key>` is inserted. For example, to reach the `c` in `{a = {b = {c = 1}}}`,
+    the path will be `{'a', 'b', 'c', '<key>' }`
+  * For metatables, a special value called `<metatable>` is inserted. For `{a = {b = 1}}}`, the path
+    `{'a', 'b', '<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 `path`:
+
+``` lua
+local t, mt = ... -- (defined as before)
+
+local remove_all_metatables = function(item, path)
+  if path[#path] ~= '<metatable>' then return item end
+end
+
+-- Removes all metatables
+assert(inspect(t, {process = remove_mt}) == "{ 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"
+}]])
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 Sometimes it might be convenient to "filter out" some parts of the output. The `options.filter` option can do that.