--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs.txt	Thu Sep 10 16:59:18 2009 -0700
@@ -0,0 +1,81 @@
+=========
+Pydertron
+=========
+
+Pydertron is a high-level wrapper for `Pydermonkey`__ that
+provides convenient, secure object wrapping between JS and Python
+space.
+
+The ``JsSandbox`` class encapsulates a JavaScript runtime, context, global
+object, and a simple `SecurableModule`__ implementation that complies
+with the `CommonJS`__ standard. It also provides a high-level bridge between
+Python and JavaScript so that you don't need to deal with any of the
+low-level details of the Pydermonkey API.
+
+__ http://code.google.com/p/pydermonkey
+__ http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules
+__ http://wiki.commonjs.org/wiki/CommonJS
+
+For instance, here we'll create a ``JsSandbox`` whose module root
+points to the ``monkeys`` SecurableModule compliance test over HTTP:
+
+  >>> url = ("http://interoperablejs.googlecode.com/svn/trunk/"
+  ...        "compliance/monkeys/")
+  >>> sandbox = JsSandbox(HttpFileSystem(url))
+
+This compliance test requires a global ``sys`` object that contains one
+method, ``print()``, that takes two arguments. First, we'll create the
+``print()`` function and prepare it for exposure to JS code:
+
+  >>> @jsexposed
+  ... def jsprint(message, label):
+  ...   print message, label
+
+Note the use of the ``@jsexposed`` decorator: all this does is set
+the function's ``__jsexposed__`` attribute to ``True``. This is
+done for security purposes: only Python callables satisfying this
+criteria will be exposed to JavaScript code, to ensure that
+untrusted JS can't accidentally gain access to privileged Python
+functionality.
+
+Creating a JS object can be done like this:
+
+  >>> system = sandbox.new_object()
+
+We can now access and set properties on this object via either
+item or attribute lookup, just like in JavaScript. Because
+``print`` is a reserved word in Python, though, we'll use item
+lookup to set the property here:
+
+  >>> system['print'] = jsprint
+
+Now we tell the sandbox that we want the ``sys`` object to be a
+global:
+
+  >>> sandbox.set_globals(sys = system)
+
+And finally, we execute the compliance test by running a one-line
+script that imports the 'program' module, like so:
+
+  >>> sandbox.run_script("require('program');")
+  PASS monkeys permitted pass
+  DONE info
+  0
+
+Note the ``0`` in the last line: this is the return value of
+``sandbox.run_script()``, which returns ``0`` on success, and
+``-1`` if an exception was raised. For instance, the output of bad
+code looks like this:
+
+  >>> sandbox.run_script("(function foo() { bar(); })();",
+  ...                    stderr=sys.stdout)
+  Traceback (most recent call last):
+    File "<string>", line 1, in <module>
+    File "<string>", line 1, in foo
+  ReferenceError: bar is not defined
+  -1
+
+Note that the traceback displayed is actually referring to
+JavaScript code: one of Pydertron's helpful conveniences is that
+it makes debugging JS code as much like debugging Python code as
+possible.