From 545e0b5b83ee093a3de6800f6fb4aaf87141e3f7 Mon Sep 17 00:00:00 2001
From: Denis Knauf <Denis.Knauf@gmail.com>
Date: Wed, 31 Mar 2010 22:59:31 +0200
Subject: [PATCH] Little more docu

---
 README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 62 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 18df0bb..ade6328 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,12 @@
+Requires
+========
+
+Ruby MRI or Ruby 1.9.
+
+Will not work with Rubinius! It does not support $SAFE.
+
+I do not know JRuby.
+
 Install
 =======
 
@@ -12,26 +21,46 @@ First load the safebox:
 
 The most things in your Safebox are possible:
 
-	value = Safebox.eval "1+2**9"
-	value = Safebox.eval {|| 1+2**8 }
+	value = Safebox.eval "1+2**9"  # => 513
+	value = Safebox.eval {|| 1+2**8 }  # => 257
+
+You can use a String or a Proc,  also as argument:
+
+	value = Safebox.eval lambda {|| 1+2**7 }
+
+More complex code with classes and everything else...
+
+	value = Safebox.eval do
+		class Mail
+			attr_accessor :subject, :body, :to, :from
+			def generate
+				[ "To: #{@to}", "From: #{@from}",
+					"Subject: #{@subject}", '', @body ].join "\n"
+			end
+		end
+		mail = Mail.new
+		mail.from, mail.to, mail.subject = "me", "root", "Plz install Ruby :)"
+		mail.subject = "..."
+		mail.generate
+	end
 
 Only some good things are not possible:
 
-	Safebox.eval "$stdout.puts 'I am OK!'"
+	Safebox.eval "$stdout.puts 'I am OK!'"  # not possible :(
 
 But, very bad code will not damage your system.
 
-	Safebox.eval "class Unsecure;def self.code() system 'rm *' ; end end; Unsecure.code"
+	Safebox.eval "class Unsecure;def self.code() system 'rm *' ; end end; Unsecure.code"  # will fail :)
 
 This will raise a SecurityError.
 
-What is with raised exceptions?
+What is with raised exceptions,  like SecurityError or others?
 
 	Safebox.eval "raise Exception"
 
-This will print the Exception.
+This will print the Exception to Console.
 
-Or if you want to get the Exception:
+You want to get the Exception?
 
 	ret = Safebox.run "raise Exception"
 	ret # => [:exception, #<Exception>]
@@ -41,7 +70,30 @@ What is *Safebox.run*?
 	ret = Safebox.run "1+2**9"
 	ret # => [:value, 513]
 
-You get something back, which can be unsafe!
+It returns the value or the raised exception.  --  Nothing else.
 
-	Safebox.eval( "class A;def to_s() 'Owned!'; end end; A.new").to_s
-	puts Safebox.eval( "class A;def to_s() 'Owned!'; end end; A.new")
+You should know,  Ruby is not stupid.  I am very surprised,
+because this is not possible:
+
+	aA = Safebox.eval do
+		class A
+			def to_s
+				'Owned!'
+			end
+		end
+		A.new
+	end
+	aA.to_s  # => SecurityError: calling insecure method: to_s
+
+*A#to_s* is defined in our *Safebox*,  so every call outside can be a security hole.
+
+But you can use #to_s in an other Safebox, withour any risk:
+
+	Safebox.eval aA.method( :to_s)  # => "Owned!"  # Not really :)
+
+Behind Safebox
+==============
+
+It uses only a Thread,  $SAFE=4 and  some code for automatism.
+
+The real magic is Ruby itself.