draft

1 files changed, 77 insertions, 0 deletions

diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..fc6d805
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,77 @@
+########
+Actinide
+########
+
+An embeddable lisp for Python applications.
+
+I had `an application`_ in which the ability to extend the application from
+within, safely, was valuable. None of the languages I reviewed met my criteria:
+
+.. _an application: https://github.com/ojacobson/cadastre/
+
+* `Lua`_ provides `primitives`_ which can be used to interact with the host
+  environment, but no facility that guarantees that these tools are
+  unavailable. I needed to be able to accept programs from hostile users
+  without worrying that they'd overwrite files on the OS.
+
+* `Python itself`_ has the same problem, but more so. Techniques for importing
+  arbitrary code even in constrained Python execution environments are well
+  known and, as far as I know, unfixable.
+
+* `V8`_ is an attractive option, as it was originally built to evaluate
+  Javascript functions in the browser. OS interaction is provided by the
+  execution environment, rather than as part of the language's standard
+  library. Leaving that out is easy.
+
+  However, the problem space I was working in strongly pushed against using a
+  language with no integers and with complex semicolon rules.
+
+.. _Lua: https://www.lua.org
+.. _primitives: https://www.lua.org/manual/5.3/manual.html#pdf-os.exit
+.. _Python itself: https://python.org/
+.. _V8: https://developers.google.com/v8/
+
+So I wrote my own. This is that language.
+
+This is a tiny lisp, along the lines of Peter Norvig's `lispy`_, designed to be
+embedded within Python programs. It provides minimal safety features, but the
+restricted set of builtins ensures that Actinide programs cannot gain access to
+the outside context of the program. The worst they can do is waste CPU time,
+fill up RAM, and drain your battery.
+
+.. _lispy: http://norvig.com/lispy.html
+
+************
+Installation
+************
+
+::
+
+    pip install actinide
+    pip freeze > requirements.txt
+
+Or, if you prefer, add ``actinide`` to your application's ``Pipfile`` or
+``setup.py``.
+
+*****************
+Freestanding REPL
+*****************
+
+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.
+
+To exit the REPL, type an end-of-file (Ctrl-D on most OSes, Ctrl-Z on Windows).
+
+******************
+Embedding Actinide
+******************
+
+WIP
+
+*********************************
+The Actinide Programming Language
+*********************************
+
+WIP