Emacs Lisp Source Code Blocks in Babel

Babel support for Emacs Lisp

Introduction

Emacs Lisp is an interpreted dialect of the Lisp programming language with extensions to support text editing. Babel and Org mode are both written in Emacs Lisp.

Requirements and Setup

If your Emacs is up and running, then Emacs Lisp is installed, configured, and running. Emacs Lisp source blocks are activated by default.

Babel Features for Emacs Lisp Source Code Blocks

Header Arguments

:lexical: A switch for evaluation scoping; "yes" or t indicates lexical scoping, "no" or NIL indicates dynamic scoping. Default: "no".

Sessions

Emacs is an Emacs Lisp session.

Examples of Use

The ability to evaluate Emacs Lisp code in the context of your Emacs session is wonderful and scary at the same time. The following examples scratch the surface of this enticing practice. Caveat emptor!

Hello World!

Here is the obligatory Hello World! example. Note that it uses the elisp source language alias for emacs-lisp.

In the Org mode buffer:

#+name: emacs-lisp-hello-world
#+begin_src elisp :exports both 
(princ "Hello World!")
#+end_src

HTML export of the source block:

(princ "Hello World!")

HTML export of the results:

Hello World!

Tangle and Export Concurrently

This bit of fanciness with running code in header arguments is taken from Eric Schulte's org-scraps.

One block in the Org mode buffer to tangle:

#+BEGIN_SRC emacs-lisp :tangle yes
  (message "I am tangled")
#+END_SRC

HTML export of the source block:

(message "I am tangled")

HTML export of the results:

I am tangled

Another block in the Org mode buffer to export:

#+BEGIN_SRC emacs-lisp :exports results :var foo=(org-babel-tangle)
  (message "I just tangled %S during export." foo)
#+END_SRC

HTML export of the results:

I just tangled ("ob-doc-elisp.el") during export.

Emacs-Lisp Printing with Output to String

Another example from Eric Schulte's org-scraps.

The first source block packages the results as a string.

Source block in the Org mode buffer:

#+name: emacs-lisp-print-to-string
#+begin_src emacs-lisp :results output
  (let ((dog (sqrt 2))
        (cat 7))
    (print (format "%s %f" "Dog: " (eval dog)))
    (print (format "%s %d" "Cat: " (eval cat)) nil)
    (print "Fish."))
#+end_src

HTML export of the source block:

(let ((dog (sqrt 2))
      (cat 7))
  (print (format "%s %f" "Dog: " (eval dog)))
  (print (format "%s %d" "Cat: " (eval cat)) nil)
  (print "Fish."))

HTML export of the result:


"Dog:  1.414214"

"Cat:  7"

"Fish."

The second source block returns a table.

Second source block in the Org mode buffer:

#+name: emacs-lisp-print-to-table
#+begin_src emacs-lisp
  (let ((dog (sqrt 2))
        (cat 7))
    `((dog ,dog)
      (cat ,cat)
      (fish)))
#+end_src

HTML export of the source block:

(let ((dog (sqrt 2))
      (cat 7))
  `((dog ,dog)
    (cat ,cat)
    (fish)))

HTML export of the results:

dog	1.4142135623730951
cat	7
fish

Executing Emacs-Lisp on Export

This example from Eric Schulte's org-scraps shows how to evaluate Emacs Lisp code during export.

Here is the source block in the Org mode buffer:

#+name: eric-error
#+begin_src emacs-lisp
  (error "eric")
#+end_src

Enabling HTML export of the source block with :exports code or :exports both aborts export with an error.

HTML export of the results when the source block isn't exported:

(error "eric")

Scalar Emacs Lisp Results

This example is from Eric Schulte's org-scraps.

Here is the source block in the Org mode buffer:

#+name: emacs-lisp-scalar
#+begin_src emacs-lisp :results scalar :exports both
  '(1 2 3)
#+end_src

HTML export of the source block:

'(1 2 3)

HTML export of the results:

(1 2 3)

Convert Results to All String

This example from Eric Schulte's org scraps shows one way to ensure that all elements in a table are rendered as strings.

Given the following table:

1	2	3	4
a	b	c	d

And given this Emacs Lisp source block:

#+name: all-to-string
#+begin_src emacs-lisp :var tbl='()
  (defun all-to-string (tbl)
    (if (listp tbl)
        (mapcar #'all-to-string tbl)
      (if (stringp tbl)
          tbl
        (format "%s" tbl))))
  (all-to-string tbl)
#+end_src

(defun all-to-string (tbl)
  (if (listp tbl)
      (mapcar #'all-to-string tbl)
    (if (stringp tbl)
        tbl
      (format "%s" tbl))))
(all-to-string tbl)

Then a reference to hetero-table indicates a mixture of strings and non-strings:

#+name: do-not-pass-to-all-string
#+begin_src emacs-lisp :var tbl=hetero-table
  (mapcar (lambda (row) (mapcar (lambda (cell) (stringp cell)) row)) tbl)
#+end_src

(mapcar (lambda (row) (mapcar (lambda (cell) (stringp cell)) row)) tbl)

nil	nil	nil	nil
t	t	t	t

But passing hetero-table through all-to-string in the header argument ensures that all the elements are strings:

#+name: pass-to-all-to-string
#+begin_src emacs-lisp :var tbl=all-to-string(hetero-table)
  (mapcar (lambda (row) (mapcar (lambda (cell) (stringp cell)) row)) tbl)
#+end_src

(mapcar (lambda (row) (mapcar (lambda (cell) (stringp cell)) row)) tbl)

t	t	t	t
t	t	t	t