diff options
Diffstat (limited to 'README.rst')
| -rw-r--r-- | README.rst | 164 |
1 files changed, 1 insertions, 163 deletions
@@ -54,7 +54,7 @@ Actinide requires Python 3.6 or later. Installation ************ -:: +.. code-block:: bash $ pip install actinide $ pip freeze > requirements.txt @@ -73,165 +73,3 @@ 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). - -****************** -Embedding Actinide -****************** - -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: - -.. code:: python - - 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: - -.. code:: python - - 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``: - -.. code:: python - - 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: - -.. code:: python - - 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: - -.. code:: python - - 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: - -.. code:: python - - 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. An equivalent set of methods, ``macro_bind``, -``macro_bind_void``, ``macro_bind_fn``, and ``macro_bind_builtin`` bind values -to entries in the top-level macro table, instead of the top-level environment, -and allow extension of the language's syntax. - -Finally, Actinide can bind specially-crafted Python modules. If a module -contains a top-level symbol named ``An`` (for the informal chemical symbol for -the actinide series), it can be passed to the session's ``bind_module`` method. -The symbol must be bound to an instance of the ``Registry`` class from the -``actinide.builtin`` module: - -.. code:: python - - from actinide.builtin import Registry - An = Registry() - - five = An.bind('five', 5) - - @An.void - def python_print(*args): - print(*args) - - @An.fn - def bitwise_and(a, b): - return a & b - - @An.builtin - def two_values(): - return 1, "Two" - - # @An.macro_bind, @An.macro_void, @An.macro_fn, and @An.macro_builtin follow - # the same pattern. - -Going the other direction, values can be extracted from bindings in the session -using the ``get`` method: - -.. code:: python - - 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: - -.. code:: python - - session.run(''' - (begin - ; 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. |