Documentation

Author: jlumpe

docs/elisp.rst

@@ -0,0 +1,175 @@
+Representing Emacs lisp code in Python
+======================================
+
+The :mod:`emacs.elisp` module contains utilities for representing Emacs lisp
+Abstract Syntax Trees (AST's) as Python objects, see the :class:`ElispAstNode`
+abstract class and its subclasses.
+
+
+Creating Elisp forms
+--------------------
+
+The fundamental data type in Elisp is the list. Other data types include symbols
+and self-evaluating types such as strings or numbers.
+
+Use the :func:`to_elisp` function to convert simple Python values to their Elisp
+equivalents. This will wrap numbers and strings as Elisp literals, as well as
+convert bools and None to the correct symbols:
+
+.. doctest::
+
+   >>> import emacs.elisp as el
+
+   >>> el.to_elisp(123)
+   <el 123>
+
+   >>> el.to_elisp(1.23)
+   <el 1.23>
+
+   >>> el.to_elisp('foo')
+   <el "foo">
+
+   >>> el.to_elisp(True)
+   <el t>
+
+   >>> el.to_elisp(False)
+   <el nil>
+
+   >>> el.to_elisp(None)
+   <el nil>
+
+
+Python lists are converted to quoted Elisp lists, while tuples are left unquoted:
+
+.. doctest::
+
+   >>> el.to_elisp([1, 2, 3])
+   <el '(1 2 3)>
+
+   >>> el.to_elisp(('a', 'b', 'c'))
+   <el ("a" "b" "c")>
+
+
+Elements of lists/tuples are recursively converted using :meth:`to_elisp` if
+they are not already instances of :class:`ElispAstNode`.
+
+You can use :func:`quote` to quote a value. It will also convert strings to
+quoted symbols:
+
+.. doctest::
+
+   >>> s = el.Symbol('foo')
+   >>> s
+   <el foo>
+
+   >>> el.quote(s)
+   <el 'foo>
+
+   >>> el.quote('foo')
+   <el 'foo>
+
+
+Other shortcuts are :func:`cons` to create a cons cell, or :func:`symbols` to
+create a list of symbols:
+
+.. doctest::
+
+   >>> el.cons(el.Symbol('a'), 1)
+   <el (cons a 1)>
+
+   >>> el.symbols('a', 'b', 'c')
+   <el (a b c)>
+
+   >>> el.symbols('a', 'b', 'c', quote=True)
+   <el '(a b c)>
+
+
+You can use :func:`make_alist` or :func:`make_plist` to convert common mapping
+types to their Elisp equivalents. These functions will always treat string
+keys as symbols:
+
+.. doctest::
+
+   >>> el.make_alist({'a': 1, 'b': 2}, quote=True)
+   <el '((a . 1) (b . 2))>
+
+   >>> el.make_plist({':x': 1, ':y': 2}, quote=True)
+   <el '(:x 1 :y 2)>
+
+
+Finally, use :class:`Raw` to wrap a raw Elisp code string so that it will just
+be inserted verbatim in the given location:
+
+.. doctest::
+
+   >>> el.Raw('(print "hi")')
+   <el (print "hi")>
+
+
+Using Elisp forms
+-----------------
+
+Elisp forms can be passed to :meth:`Elisp.eval` and :meth:`Elisp.getresult` for
+execution. You can also convert them to strings to produce (hopefully)
+syntactically-correct Elisp code.
+
+
+Elisp DSL
+---------
+
+This package also includes an unholy abomination of a DSL that lets you write
+Elisp code in Python. The DSL is implemented through a singleton object which
+is importable as :data:`emacs.elisp.E`::
+
+   >>> from emacs.elisp import E
+
+
+Calling the singleton as a function converts a Python object into an Elisp object
+using :meth:`to_elisp`:
+
+.. doctest::
+
+   >>> E(3)
+   <el 3>
+
+   >>> E('foo')
+   <el "foo">
+
+   >>> E(['a', 'b', 'c'])
+   <el '("a" "b" "c")>
+
+
+Attribute access produces Elisp symbols, converting underscores to dashes. The
+same can be done by indexing with a string:
+
+.. doctest::
+
+   >>> E.abc
+   <el abc>
+
+   >>> E.foo_bar
+   <el foo-bar>
+
+   >>> E[':baz']
+   <el :baz>
+
+
+Symbols can be called as functions, generating Elisp function calls:
+
+.. doctest::
+
+   >>> E.message("Hello from %s", E('python-emacs'))
+   <el (message "Hello from %s" "python-emacs")>
+
+
+Additionally, the ``Q``, ``C``, ``S``, and ``R`` methods are aliases for the
+:func:`quote`, :func:`cons`, :func:`symbols`, and :class:`Raw`, respectively.
+
+Using just the ``E`` object, it is possible to write complex Elisp forms:
+
+.. doctest::
+
+   >>> E.defun(E.my_elisp_function, E.S('a', 'b'),
+   ...   E.message("I shouldn't exist"),
+   ...   E['+'](E.a, E.b))
+   <el (defun my-elisp-function (a b) (message "I shouldn't exist") (+ a b))>

docs/index.rst

@@ -10,6 +10,8 @@ Welcome to python-emacs's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   usage
+   elisp
 
 
 Indices and tables

docs/usage.rst

@@ -0,0 +1,58 @@
+Basic usage
+===========
+
+Most of the functionality in this package is implemented in the :class:`Emacs`
+class, which represents an interface into the Emacs program.
+
+
+Instantiating the Emacs interface
+---------------------------------
+
+You should generally create the :class:`Emacs` object using one of the following
+two class methods rather than invoking the constructor directly.
+
+If you create the object with :meth:`Emacs.batch`, it will start a new Emacs
+process with the ``--batch`` argument each time you run a command or evaluate
+Elisp code. This will be slow if your ``init.el`` file takes a while to execute.
+
+Alternatively, :meth:`Emacs.client` will create an instance which connects to
+an already-running Emacs process using the ``emacsclient`` program. This should
+make most commands run much faster. If you use this method make sure to start
+the server in Emacs using ``(server-start)``.
+
+If the ``verbose`` keyword argument is set to 1 or higher, the subprocess'
+``stderr`` stream will be redirected to the console. If set to 2 ``stdout`` will
+be displayed as well.
+
+
+Low-level interface
+-------------------
+
+At the lowest level, you can call the :meth:`Emacs.run` or
+:meth:`Emacs.getoutput` methods to invoke the program with the given list of
+command line arguments. The difference between the two is that
+:meth:`Emacs.getoutput` returns the value of stdout as a string while
+:meth:`Emacs.run` returns an entire :class:`subprocess.CompletedProcess`
+instance.
+
+
+Executing Emacs lisp code
+-------------------------
+
+The main job of :class:`Emacs` is to execute elisp code.
+You can do this using the :meth:`Emacs.eval` method::
+
+    >>> emacs = Emacs.batch()
+    >>> emacs.eval('(print "Hello world!")')
+    '\n"Hello world!"\n'
+
+This method records the output from stdout and returns it as a string.
+
+Alternatively, you can use the :meth:`Emacs.getresult` method which returns the
+result of the execution as a Python value::
+
+    >>> emacs.getresult('(+ 1 2)')
+    3
+
+Note that it does this by converting the value to JSON in Emacs and then decoding
+it in Python, so the value must be json-encodable.