From cb4f719cc09ab723acd72df4b727b1740650d87c Mon Sep 17 00:00:00 2001 From: Owen Jacobson Date: Wed, 8 Nov 2017 00:28:59 -0500 Subject: draft --- README.rst | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 README.rst 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 -- cgit v1.2.3