From e47dbfc55c8dfd34e0cc028090eb7a5fa6a800d9 Mon Sep 17 00:00:00 2001
From: kikito <kikito@gmail.com>
Date: Sun, 15 Sep 2013 13:32:04 +0200
Subject: [PATCH] updated README to the latest options

---
 README.md | 71 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 50 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 638b17b..2d126c3 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,11 @@ The objective here is human understanding (i.e. for debugging), not serializatio
 Examples of use
 ===============
 
+`inspect` has the following declaration: `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 undersand.
+
 "Array-like" tables are rendered horizontally:
 
     inspect({1,2,3,4}) == "{ 1, 2, 3, 4 }"
@@ -38,27 +43,7 @@ Tables can be nested, and will be indented with two spaces per level.
       }
     }]]
 
-`inspect`'s second parameter allows controlling the maximum depth that will be printed out. When the max depth is reached, it'll just return `{...}`:
-
-    local t5 = {a = {b = {c = {d = {e = 5}}}}}
-
-    inspect(t5, 4) == [[{
-      a = {
-        b = {
-          c = {
-            d = {...}
-          }
-        }
-      }
-    }]]
-
-    inspect(t5, 2) == [[{
-      a = {
-        b = {...}
-      }
-    }]])
-
-Functions, userdata and threads are simply rendered as `<function x>`, `<userdata x>` and `<thread x>` respectively:
+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>,
@@ -84,6 +69,50 @@ If the table has a metatable, inspect will include it at the end, in a special f
 
 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
+
+`inspect`'s second parameter allows controlling the maximum depth that will be printed out. When the max depth is reached, it'll just return `{...}`:
+
+    local t5 = {a = {b = {c = {d = {e = 5}}}}}
+
+    inspect(t5, {depth = 4}) == [[{
+      a = {
+        b = {
+          c = {
+            d = {...}
+          }
+        }
+      }
+    }]]
+
+    inspect(t5, {depth = 2}) == [[{
+      a = {
+        b = {...}
+      }
+    }]])
+
+`options.depth` defaults to infinite (`math.huge`).
+
+### options.filter
+
+Sometimes it might be convenient to "filter out" some parts of the output. The `options.filter` option can do that.
+
+`options.filter` accepts a table of values. Any value on that table will be rendered as `<filtered>`. This is useful for hiding things like long complex tables that are not interesting for the task at hand, for example an unuseful complex metatable.
+
+    local person = {name = 'peter'}
+    setmetatable(person, complex_mt)
+    inspect(x, {filter = {complex_mt}}) == [[{
+      name = "peter",
+      <metatable> = <filtered>
+    }]]
+
+`options.filter` can also be a function. The function must return true for the values that must be filtered out.
+
+    local isEvenNumber = function(x) return type(x) == 'number' and x % 2 == 0 end
+
+    inspect({1,2,3,4,5}, {filter = isEvenNumber}) == "{ 1, <filtered>, 3, <filtered>, 5 }"
+
+
 Gotchas / Warnings
 ==================