From ca9e012357944ef2213a14d3668aa73b14a91bb4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Enrique=20Garc=C3=ADa=20Cota?= <kikito@gmail.com>
Date: Tue, 10 May 2011 00:48:23 +0200
Subject: [PATCH] edited README

---
 README.textile | 55 ++++++++++++++++++++++++++++++--------------------
 1 file changed, 33 insertions(+), 22 deletions(-)

diff --git a/README.textile b/README.textile
index e8c4453..a8f45f1 100644
--- a/README.textile
+++ b/README.textile
@@ -8,11 +8,11 @@ h1. Examples of use
 
 "Array-like" tables are rendered horizontally:
 
-<pre>inspect({1,2,3,4}) == "{ 1, 2, 3, 4 }"</pre>
+<pre>inspect({1,2,3,4}) == "<1>{ 1, 2, 3, 4 }"</pre>
 
 "dictionary-like" tables are rendered with one element per line:
 
-<pre>inspect({a=1,b=2}) == [[{
+<pre>inspect({a=1,b=2}) == [[<1>{
   a = 1,
   b = 2
 }]]</pre>
@@ -22,7 +22,7 @@ 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:
 
 <pre>
-inspect({1,2,3,a=1,b=2}) == [[{ 1, 2, 3,
+inspect({1,2,3,a=1,b=2}) == [[<1>{ 1, 2, 3,
   a = 1,
   b = 2
 }]]
@@ -31,8 +31,8 @@ inspect({1,2,3,a=1,b=2}) == [[{ 1, 2, 3,
 Tables can be nested, and will be indented with two spaces per level.
 
 <pre>
-inspect({a={b=2}}) = [
-  a = {
+inspect({a={b=2}}) = [[<1>{
+  a = <2>{
     b = 2
   }
 }]]
@@ -42,10 +42,10 @@ By default, @inspect@ will stop rendering at a depth of 4 levels. When that poin
 
 <pre>
 local t5 = {a = {b = {c = {d = {e = 5}}}}}
-inspect(t5) == [[
-  a = {
-    b = {
-      c = {
+inspect(t5) == [[<1>{
+  a = <2>{
+    b = <3>{
+      c = <4>{
         d = {...}
       }
     }
@@ -56,17 +56,17 @@ inspect(t5) == [[
 You can increase/decrease the max depth with the second parameter:
 
 <pre>
-inspect(t5, 2) == [[{
-  a = {
+inspect(t5, 2) == [[<1>{
+  a = <2>{
     b = {...}
   }
 }]])
 
-inspect(t5, 7) == [[{
-  a = {
-    b = {
-      c = {
-        d = {
+inspect(t5, 7) == [[<1>{
+  a = <2>{
+    b = <3>{
+      c = <4>{
+        d = <5>{
           e = 5
         }
       }
@@ -75,13 +75,13 @@ inspect(t5, 7) == [[{
 }]])
 </pre>
 
-Functions, userdata and threads are simply rendered as @<function>@, @<userdata>@ and @<thread>@ respectively:
+Functions, userdata and threads are simply rendered as @<function x>@, @<userdata x>@ and @<thread x>@ respectively:
 
 <pre>
 inspect({ f = print, ud = some_user_data, thread = a_thread} ) == [[{
-  f = <function>,
-  u = <userdata>,
-  thread = <thread>
+  f = <function 1>,
+  u = <userdata 1>,
+  thread = <thread 1>
 }]])
 </pre>
 
@@ -89,14 +89,25 @@ inspect({ f = print, ud = some_user_data, thread = a_thread} ) == [[{
 If the table has a metatable, inspect will include it at the end, in a special field called @<metatable>@:
 
 <pre>
-inspect(setmetatable({a=1}, {b=2}) == [[{
+inspect(setmetatable({a=1}, {b=2}) == [[<1>{
   a = 1
-  <metatable> = {
+  <metatable> = <2>{
     b = 2
   }
 }]])
 </pre>
 
+You may have noticed that all tables are preceded by an @<id>@ string. If a table has already been printed out, @inspect@ will just print @<table id>@ the second time it finds it. This will infinite loops.
+
+<pre>
+a = {1,2}
+b = {3,4,a}
+a[3] = b
+inspect(a) = "<1>{ 1, 2, <2>{ 3, 4, <table 1> } }"
+</pre>
+
+Notice how the second appearance of @a@ was replaced by @<table 1>@ in the string above.
+
 h1. Gotchas / Warnings
 
 This method is *not* appropiate for saving/restoring tables. It is ment to be used by the programmer mainly while debugging a program.