Re-add the repl, and a bunch of stdlib glue.

1 files changed, 163 insertions, 5 deletions

diff --git a/README.rst b/README.rst
index 595c43e..9dfef88 100644
--- a/README.rst
+++ b/README.rst
@@ -66,13 +66,11 @@ Or, if you prefer, add ``actinide`` to your application's ``Pipfile`` or
 Freestanding REPL
 *****************
 
-**Note: this section is presently incorrect - the ``actinide-repl`` command
-doesn't exist.**
-
 The Actinide interpreter can be started interactively using the
 ``actinide-repl`` command. In this mode, Actinide forms can be entered
 interactively. The REPL will immediately evaluate each top-level form, then
-print the result of that evaluation.
+print the result of that evaluation. The environment is persisted from form to
+form, to allow interactive definitions.
 
 To exit the REPL, type an end-of-file (Ctrl-D on most OSes, Ctrl-Z on Windows).
 
@@ -80,7 +78,167 @@ To exit the REPL, type an end-of-file (Ctrl-D on most OSes, Ctrl-Z on Windows).
 Embedding Actinide
 ******************
 
-WIP
+Actinide is designed to be embedded into larger Python programs. It's possible
+to call into Actinide, either by providing code to be evaluated, or by
+obtaining builtin functions and procedures from Actinide and invoking them.
+
+The ``Session`` class is the basic building block of an Actinide integration.
+Creating a session creates a number of resources associated with Actinide
+evaluation: a symbol table for interning symbols, and an initial top-level
+environment to evaluate code in, pre-populated with the Actinide standard
+library.
+
+Executing Actinide programs in a session consists of two steps: reading the
+program in from a string or an input port, and evaluating the resulting forms.
+The following example illustrates a simple infinite loop:
+
+::
+
+    import actinide
+
+    session = actinide.Session()
+    program = session.read('''
+        (begin
+            ; define the factorial function
+            (define (factorial n)
+                (fact n 1))
+
+            ; define a tail-recursive factorial function
+            (define (fact n a)
+                (if (= n 1)
+                    a
+                    (fact (- n 1) (* n a))))
+
+            ; call them both
+            (factorial 100))
+    ''')
+
+    # Compute the factorial of 100
+    result = session.eval(program)
+
+As a shorthand for this common sequence of operations, the Session exposes a
+``run`` method:
+
+::
+
+    print(*session.run('(factorial 5)')) # prints "120"
+
+Callers can inject variables, including new builtin functions, into the initial
+environment using the ``bind``, ``bind_void``, ``bind_fn``, and
+``bind_builtin`` methods of the session.
+
+To bind a simple value, or to manually bind a wrapped builtin, call
+``session.bind``:
+
+::
+
+    session.bind('var', 5)
+    print(*session.run('var')) # prints "5"
+
+To bind a function whose return value should be ignored, call ``bind_void``.
+This will automatically determine the name to bind the function to:
+
+::
+
+    session.bind_void(print)
+    session.run('(print "Hello, world!")') # prints "Hello, world!" using Python's print fn
+
+To bind a function returning one value (most functions), call ``bind_fn``. This
+will automatically determine the name to bind to:
+
+::
+
+    def example():
+        return 5
+
+    session.bind_fn(example)
+    print(*session.run('(example)')) # prints "5"
+
+Finally, to bind a function returning a tuple of results, call
+``bind_builtin``. This will automatically determine the name to bind to:
+
+::
+
+    def pair():
+        return 1, 2
+
+    session.bind_builtin(pair)
+    print(*session.run('(pair)')) # prints "1 2"
+
+Actinide functions can return zero, one, or multiple values. As a result, the
+``result`` returned by ``session.eval`` is a tuple, with one value per result.
+
+Actinide can bind Python functions, as well as bound and unbound methods, and
+nearly any other kind of callable. Under the hood, Actinide uses a thin adapter
+layer to map Python return values to Actinide value lists. The ``bind_void``
+helper ultimately calls that module's ``wrap_void`` to wrap the function, and
+``bind_fn`` calls ``wrap_fn``. (Tuple-returning functions do not need to be
+wrapped.) If you prefer to manually bind functions using ``bind``, they must be
+wrapped appropriately.
+
+Finally Actinide can bind specially-crafted Python modules. If a module
+contains top-level symbols named ``ACTINIDE_BINDINGS``, ``ACTINIDE_VOIDS``,
+``ACTINIDE_FNS``, and/or ``ACTINIDE_BUILTINS``, it can be passed to the
+session's ``bind_module`` method. The semantics of each symbol are as follows:
+
+* ``ACTINIDE_BINDINGS`` is a list of name, value pairs. Each binding binding
+  will be installed verbatim, without any function mangling, as if by
+  ``session.bind``.
+
+* ``ACTINIDE_VOIDS``, ``ACTINIDE_FNS``, and ``ACTINIDE_BUILTINS`` are lists of
+  function objects. Each will be bound as if by the corresponding
+  ``session.bind_void``, ``session.bind_fn``, or ``session.bind_builtin``
+  method.
+
+The ``actinide.builtin`` module contains a helper function, ``make_registry``,
+which can simplify construction of these fields:
+
+::
+
+    from actinide.builtin import make_registry
+    ACTINIDE_BINDINGS, ACTINIDE_VOIDS, ACTINIDE_FNS, ACTINIDE_BUILTINS, bind, void, fn, builtin = make_registry()
+
+    five = bind('five', 5)
+
+    @void
+    def python_print(*args):
+        print(*args)
+
+    @fn
+    def bitwise_and(a, b):
+        return a & b
+
+    @builtin
+    def two_values():
+        return 1, "Two"
+
+Going the other direction, values can be extracted from bindings in the session
+using the ``get`` method:
+
+::
+
+    session.run('(define x 8)')
+    print(session.get('x')) # prints "8"
+
+If the extracted value is a built-in function or an Actinide procedure, it can
+be invoked like a Python function. However, much like ``eval`` and ``run``,
+Actinide functions returne a tuple of results rather than a single value:
+
+::
+
+    session.run('''
+        ; Set a variable
+        (define x 5)
+
+        ; Define a function that reads the variable
+        (define (get-x) x)
+    ''')
+
+    get_x = session.get('get-x')
+    print(*get_x()) # prints "5"
+
+This two-way binding mechanism makes it straightforward to define interfaces
+between Actinide and the target domain.
 
 *********************************
 The Actinide Programming Language