diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | Makefile | 20 | ||||
| -rw-r--r-- | README.rst | 164 | ||||
| -rwxr-xr-x | conf.py | 169 | ||||
| -rw-r--r-- | docs/embedding.rst | 161 | ||||
| -rw-r--r-- | docs/language.rst (renamed from LANGUAGE.rst) | 2 | ||||
| -rw-r--r-- | docs/security.rst (renamed from SECURITY.rst) | 2 | ||||
| -rw-r--r-- | index.rst | 7 | ||||
| -rw-r--r-- | requirements-docs.txt | 17 | ||||
| -rw-r--r-- | setup.py | 2 |
10 files changed, 381 insertions, 165 deletions
@@ -4,3 +4,5 @@ __pycache__/ /.cache/ /.hypothesis/* !/.hypothesis/examples/ +/build/ +/_build/ diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..cdf3d26 --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = Actinide +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) @@ -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. @@ -0,0 +1,169 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Actinide documentation build configuration file, created by +# sphinx-quickstart on Sat Nov 18 20:35:56 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.todo'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Actinide' +copyright = '2017, Owen Jacobson' +author = 'Owen Jacobson' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.1' +# The full version, including alpha/beta/rc tags. +release = '0.1.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.eggs', '.venv'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + ] +} + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Actinidedoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'Actinide.tex', 'Actinide Documentation', + 'Owen Jacobson', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'actinide', 'Actinide Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'Actinide', 'Actinide Documentation', + author, 'Actinide', 'One line description of project.', + 'Miscellaneous'), +] + + + diff --git a/docs/embedding.rst b/docs/embedding.rst new file mode 100644 index 0000000..0bb9dcc --- /dev/null +++ b/docs/embedding.rst @@ -0,0 +1,161 @@ +################## +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-block:: 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-block:: 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-block:: 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-block:: 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-block:: 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-block:: 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-block:: 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-block:: 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-block:: 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. diff --git a/LANGUAGE.rst b/docs/language.rst index 36f5793..0296ec1 100644 --- a/LANGUAGE.rst +++ b/docs/language.rst @@ -2,6 +2,8 @@ The Actinide Programming Language ################################# +.. highlight:: scheme + ***** Forms ***** diff --git a/SECURITY.rst b/docs/security.rst index 2d450e8..4a42a2d 100644 --- a/SECURITY.rst +++ b/docs/security.rst @@ -1,5 +1,5 @@ ######## -SECURITY +Security ######## In the README, I made this strong claim: diff --git a/index.rst b/index.rst new file mode 100644 index 0000000..69b40b4 --- /dev/null +++ b/index.rst @@ -0,0 +1,7 @@ +.. include:: README.rst +.. toctree:: + :maxdepth: 2 + + docs/language + docs/embedding + docs/security diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 0000000..f89c262 --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1,17 @@ +alabaster==0.7.10 +Babel==2.5.1 +certifi==2017.11.5 +chardet==3.0.4 +docutils==0.14 +idna==2.6 +imagesize==0.7.1 +Jinja2==2.10 +MarkupSafe==1.0 +Pygments==2.2.0 +pytz==2017.3 +requests==2.18.4 +six==1.11.0 +snowballstemmer==1.2.1 +Sphinx==1.6.5 +sphinxcontrib-websupport==1.0.1 +urllib3==1.22 @@ -2,7 +2,7 @@ from setuptools import setup, find_packages setup( name='actinide', - version='0.1', + version='0.1.0', packages=find_packages(), scripts=['bin/actinide-repl'], |