From 721878115a9fa7efab0c63a056f1d5e769cb71f0 Mon Sep 17 00:00:00 2001
From: kikito <kikito@gmail.com>
Date: Fri, 13 Sep 2013 13:20:24 +0200
Subject: [PATCH] updated README

---
 README.md | 58 ++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 38 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index c227a49..8ea77a7 100644
--- a/README.md
+++ b/README.md
@@ -10,29 +10,31 @@ Usage
 
     local sandbox = require 'sandbox'
 
-`sandbox(f, options)` and `sandbox.protect(f, options)` are synonyms. They return a sandboxed version of `f`.
-`options` is not required. So far the only possible options are `env` and `quota` (see below)
+`sf = sandbox(f, options)` and `sf = sandbox.protect(f, options)`
+-----------------------------------------------------------------
+
+Those two are synonyms. They return a sandboxed version of `f`.
+
+`options` is not required. So far the only possible options are `env` and `quota`
 
     local sandboxed_f = sandbox(function() return 'hey' end)
     local msg = sandboxed_f() -- msg is now 'hey'
 
-`sandbox.run(f)` sanboxes a function and executes it. f can be either a string or a function
+Only safe modules and operations can be accessed from a sandboxed function. See the source code for a list of safe/unsafe operations.
 
-    local msg  = sandbox.run(function() return 'this is untrusted code' end)
-    local msg2 = sandbox.run("return 'this is also untrusted code'")
-
-Only safe modules and operations can be accessed from the sandboxed mode. See the source code for a list of safe/unsafe operations.
-
-    sandbox.run(function()
+    local f1 = sandbox.protect(function()
       return string.upper('string.upper is a safe operation.')
     end)
 
-Attempting to invoke unsafe operations (such as `os.execute`) is not permitted
-
-    sandbox.run(function()
-      os.execute('rm -rf /') -- this will throw an error, no damage don
+    local f2 = sandbox.protect(function()
+      os.execute('rm -rf /') -- this will throw an error, no damage done
     end)
 
+    f1() -- ok
+    f2() -- error: os.execute not found
+
+### `options.quota (default 500000)`
+
 It is not possible to exhaust the machine with infinite loops; the following will throw an error after invoking 500000 instructions:
 
     sandbox.run('while true do end')
@@ -41,21 +43,37 @@ The amount of instructions executed can be tweaked via the `quota` option (defau
 
     sandbox.run('while true do end', {quota=10000}) -- throw error after 10000 instructions
 
-It is also possible to use the env option to add additional variables to the environment
+### `options.env (default {})`
 
-    sandbox.run('return foo', {env = {foo = 'This was on the environment'}})
+Use the `env` option to add additional variables to the environment
 
-If provided, the env variable will be heavily modified by the sanbox (adding base modules like string)
-The sandboxed code can also modify the env
+    local msg = sandbox.run('return foo', {env = {foo = 'This is on the environment'}})
+
+If provided, the `env` variable will be modified by the sanbox (adding base modules like `string`)
+The sandboxed code can also modify the sandboxed function. Make sure to securize it if needed.
 
     local env = {amount = 1}
     sandbox.run('amount = amount + 1', {env = env})
     assert(env.amount = 2)
 
-Finally, you may pass parameters to the sandboxed function directly in `sandbox.run`. Just add them after the `options` param.
 
-    local secret = sandbox.run(function(a,b) return a + b, {}, 1, 2)
-    assert(secret == 3)
+`result = sandbox.run(f, options, ...)`
+---------------------------------------
+
+`sandbox.run` sanboxes a function and executes it. `f` can be either a string or a function
+
+    local msg  = sandbox.run(function() return 'this is untrusted code' end)
+    local msg2 = sandbox.run("return 'this is also untrusted code'")
+
+`sandbox.run(f, o, ...)` is equivalent to `sandbox.protect(f,o)(...)`.
+
+`options` works exactly like in `sandbox.protect`.
+
+`sandbox.run` also returns the result of executing `f` with the given params after `options`, if any (notice that strings can't accept parameters).
+
+Notice that if `f` throws an error, it is *NOT* captured by `sandbox.run`. Use `pcall` if you want your app to be immune to errors, like this:
+
+    local ok, result = pcall(sandbox.run, 'error("this just throws an error")')
 
 
 Installation