View on GitHub


Quick reference to the core language of Emacs ---Editor MACroS.


Quick reference to the core language of Emacs —Editor MACroS.


( It’s mostly Common Lisp in Elisp syntax, for now; based on reading Land of Lisp. )

The listing sheet, as PDF, can be found here, while below is an unruly html rendition.

This reference sheet is built around an Org-mode CheatSheet system.

Table of Contents

  1. Functions
  2. Quotes, Quasi-Quotes, and Unquotes
  3. Reads
  4. Variables
  5. Lists and List-Like Structures
  6. Generic Setters
  7. Records
  8. Block of Code
  9. Conditionals
  10. Loops
  11. Exception Handling
  12. Types & Overloading
  13. Macros
  14. read and print

Everything is a list!


Functions are first-class values but variables and functions have separate namespaces —“Elisp is a Lisp-2 Language”. The function represented by the name g is obtained by the call (function g), which is also denoted #'g. The sharp quote behaves like the usual quote but causes its argument to be compiled. lambda is a macro that calls function and so there is rarely any need to quote lambdas. If h is a variable referring to a function, then (funcall h x₀ … xₙ) calls that function on arguments xᵢ.

`(apply 'g x₀…xₖ '(xₖ…xₙ)) ≈ (funcall #'g x₀…xₙ) ≈ (g x₀…xₙ)`
;; Recursion with the ‘tri’angle numbers: tri n = Σⁿᵢ₌₀ i.
(defun tri (f n) (if (<= n 0) 0 (+ (funcall f n) (tri f (- n 1)))))
(tri #'identity 100)           ;; ⇒ 5050
(tri (lambda (x) (/ x 2)) 100) ;; ⇒ 2500

;; Run “C-h o tri” to see TWO items! Location determines dispatch.
(setq tri 100) (tri #'identity tri)      ;; ⇒ 5050
(setq tri (lambda (x) x)) (tri tri 100)  ;; ⇒ 5050

We may have positional optional arguments, or optional but named arguments —for which position does not matter. Un-supplied optional arguments are bound to nil.

(cl-defun f (a &optional b (c 5)) (format "%s %s %s" a b c)) (f 'a) ;; ⇒ "a nil 5" (f 'a 'b) ;; ⇒ "a b 5" (f 'a 'b 'c) ;; ⇒ "a b c" (cl-defun g (a &key (b 'nice) c) (format "%s %s %s" a b c)) (g 1 :c 3 :b 2) ;; ⇒ "1 2 3" (g 1 :c 3) ;; ⇒ "1 nice 3"

Keywords begin with a colon, :k is a constant whose value is :k.

Quotes, Quasi-Quotes, and Unquotes

Quotes: 'x refers to the name rather than the value of x.

Akin to English, quoting a word refers to the word and not what it denotes.

This lets us treat code as data! E.g., '(+ 1 2) evaluates to (+ 1 2), a function call, not the value 3! Another example, * is code but '* is data, and so (funcall '* 2 4) yields 8.

Elisp expressions are either atoms or function application –nothing else!

‘Atoms’ are the simplest objects in Elisp: They evaluate to themselves; \newline e.g., 5, "a", 2.78, 'hello, [1 "two" three].

An English sentence is a list of words; if we want to make a sentence where some of the words are parameters, then we use a quasi-quote –it’s like a quote, but allows us to evaluate data if we prefix it with a comma. It’s usually the case that the quasi-quoted sentence happens to be a function call! In which case, we use eval which executes code that is in data form; i.e., is quoted.

Macros are essentially functions that return sentences, lists, which may happen to contain code.

;; Quotes / sentences / data '(I am a sentence) '(+ 1 (+ 1 1)) ;; Executing data as code (eval '(+ 1 (+ 1 1))) ;; ⇒ 3 (setq name "Jasim") ;; Quasi-quotes: Sentences with a ;; computation, code, in them. `(Hello ,name and welcome) `(+ 1 ,(+ 1 1)) ;; ⇒ '(+ 1 2)

As the final example shows, Lisp treats data and code interchangeably. A language that uses the same structure to store data and code is called ‘homoiconic’.



Lists and List-Like Structures

E.g., (cons 1 (cons "a" (cons 'nice nil))) ≈ (list 1 "a" 'nice) ≈ '(1 "a" nice).

Since variables refer to literals and functions have lambdas as literals, we can produce forms that take functions as arguments. E.g., the standard mapcar may be construed:

(defun my-mapcar (f xs)
  (if (null xs) xs
   (cons (funcall f (car xs)) (my-mapcar f (cdr xs)))))

(my-mapcar (lambda (x) (* 2 x)) '(0 1 2 3 4 5)) ;; ⇒ (0 2 4 6 8 10)
(my-mapcar 'upcase '("a" "b" "cat")) ;; ⇒ ("A" "B" "CAT")

Pairs: (x . y) ≈ (cons x y).

An association list, or alist, is a list formed of such pairs. They’re useful for any changeable collection of key-value pairs. The assoc function takes a key and an alist and returns the first pair having that key. In the end, alists are just lists.

(Rose) Trees in lisp are easily formed as lists of lists where each inner list is of length 2: The first symbol is the parent node and the second is the list of children.

Lists are formed by chains of cons cells, so getting and setting are very slow; likewise for alists. If performance is desired, one uses arrays and hash tables, respectively, instead. In particular, the performance of arrays and hash tables always requires a constant amount of time whereas the performance of lists and alists grows in proportion with their lengths.

However, the size of an array is fixed —it cannot change and thus grow— and hash tables have a lookup cost as well as issues with “hash collisions”. Their use is worth it for large amounts of data, otherwise lists are the way to go.

An array is created like a list but using [only square brackets] with getter (aref arr index).

A hash table is created with (make-hash-table) with getter (gethash key table).

What if you look up a key and get nil, is there no value for that key or is the value nil? gethash takes a final, optional, argument which is the value to return when the key is not found; it is nil by default.

Generic Setters

Since everything is a list in lisp, if G is a way to get a value from variable x, then (setf G e) updates x so that the location G now refers to element e. Hence, once you have a getter G you freely obtain a setter (setf G ⋯).

;; Element update
(setq x '(0 1 2 3))    ;; x ⇒ '(0 1 2     3)
(setf (nth 2 x) 'nice) ;; x ⇒ '(0 1 'nice 3)

;; Circular list
(setq y '(a b c))   ;; y ⇒ '(a b c)
(setf (cdddr y) y)  ;; y ⇒ '(a b c a b . #2)
;; “#2” means repeat from index 2.
(nth 99 y) ;; ⇒ a


If we want to keep a list of related properties in a list, then we have to remember which position keeps track of which item and may write helper functions to keep track of this. Instead we could use a structure.

(defstruct X "Record with fields/slots fᵢ having defaults dᵢ"
  (f₀ d₀) ⋯ (fₖ dₖ))

;; Automatic constructor is “make-X” with keyword parameters for
;; initialising any subset of the fields!
;; Hence (expt 2 (1+ k)) kinds of possible constructor combinations!
(make-X :f₀ val₀ :f₁ val₁ ⋯ :fₖ valₖ) ;; Any, or all, fᵢ may be omitted

;; Automatic runtime predicate for the new type.
(X-p (make-X)) ;; ⇒ true
(X-p 'nope)    ;; ⇒ nil

;; Field accessors “X-fᵢ” take an X record and yield its value.

;; Field update: (setf (X-fᵢ x) valᵢ)

(defstruct book
  title  (year  0))

(setq ladm (make-book :title "Logical Approach to Discrete Math" :year 1993))
(book-title ladm) ;; ⇒ "Logical Approach to Discrete Math"
(setf (book-title ladm) "LADM")
(book-title ladm) ;; ⇒ "LADM"

Advanced OOP constructs can be found within the CLOS, Common Lisp Object System; which is also used as a research tool for studying OOP ideas.

Block of Code

Use the progn function to treat multiple expressions as a single expression. E.g.,

  (message "hello")
  (setq x  (if (< 2 3) 'two-less-than-3))
  (sleep-for 0 500)
  (message (format "%s" x))
  (sleep-for 0 500)
  23    ;; Explicit return value

This’ like curly-braces in C or Java. The difference is that the last expression is considered the ‘return value’ of the block.

Herein, a ‘block’ is a number of sequential expressions which needn’t be wrapped with a progn form.


(cond (test₀ actionBlock₀) (test₁ actionBlock₁) … (t ;; optional defaultActionBlock)) \columnbreak ;; pattern matching on any type (defun go (x) (pcase x ('bob 1972) (`(,a ,_ ,c) (+ a c)) (otherwise "Shucks!"))) (go 'bob) ;; ⇒ 1972 (go '(1 2 3)) ;; ⇒ 4 (go 'hallo) ;; "Shucks!"

Avoid nested if-then-else clauses by using a cond statement –a (lazy) generalisation of switch statements: It sequentially evaluates the expressions testᵢ and performs only the action of the first true test; yielding nil when no tests are true. Or use pattern matching; which even allows predicates in the case position —C-h o ;-)

Hint: If you write a predicate, think of what else you can return besides t; such as a witness to why you’re returning truth –all non-nil values denote true after all. E.g., (member e xs) returns the sublist of xs that begins with e.


Let’s sum the first 100 numbers in 3 ways.

(let ((n 100) (i 0) (sum 0)) (while (<= i n) (incf sum i) (incf i)) (message (format "sum: %s" sum))) \columnbreak
C Elisp
`x += y` `(incf x y)`
`x -= y` `(decf x y)`
`y` is optional, and is 1 by default.
;; Repeat body n times, where i is current iteration.
(let ((result 0) (n 100))
  (dotimes (i (1+ n) result) (incf result i)))

;; A for-each loop: Iterate through the list [0..100].
(let ((result 0) (mylist (number-sequence 0 100)))
  (dolist (e mylist result) (incf result e)))

In both loops, result is optional and defaults to nil. It is the return value of the loop expression.

**Example of Above Constructs**
(defun my/cool-function (N D)
  "Sum the numbers 0..N that are not divisible by D"
  (catch 'return
    (when (< N 0) (throw 'return 0)) ;; early exit
    (let ((counter 0) (sum 0))
      (catch 'break
    (while 'true
      (catch 'continue
        (incf counter)
        (cond ((equal counter N)       (throw 'break sum   ))
           ((zerop (% counter D))  (throw 'continue nil))
           ('otherwise             (incf sum counter   )) )))))))

(my/cool-function  100 3)  ;; ⇒ 3267
(my/cool-function  100 5)  ;; ⇒ 4000
(my/cool-function -100 7)  ;; ⇒ 0

The special loop construct provides immensely many options to form nearly any kind of imperative loop. E.g., Python-style ‘downfrom’ for-loops and Java do-while loops. I personally prefer functional programming, so wont look into this much.

Exception Handling

We can attempt a dangerous clause and catch a possible exceptional case –below we do not do so via nil– for which we have an associated handler.

(condition-case nil attemptClause (error recoveryBody))

  (ignore-errors attemptBody)
≈ (condition-case nil (progn attemptBody) (error nil))

(ignore-errors (+ 1 "nope")) ;; ⇒ nil

Types & Overloading

Since Lisp is dynamically typed, a variable can have any kind of data, possibly different kinds if data at different times in running a program. We can use type-of to get the type of a given value; suffixing that with p gives the associated predicate; \newline e.g., function ↦ functionp.

;; Difficult to maintain as more types are added.
(defun sad-add (a b)
  (if (and (numberp a) (numberp b))
      (+ a b)
      (format "%s + %s" a b))

(sad-add 2 3)       ;; ⇒ 5
(sad-add 'nice "3") ;; ⇒ "nice + 3"

;; Better: Seperation of concerns.
(cl-defmethod add ((a number) (b number)) (+ a b))      ;; number types
(cl-defmethod add ((a t) (b t)) (format "%s + %s" a b)) ;; catchall types

(add 2 3)       ;; ⇒ 5
(add 'nice "3") ;; ⇒ "nice + 3"

While list specific functions like list-length and mapcar may be more efficient than generic functions, which require extra type checking, the generic ones are easier to remember. The following generic functions work on lists, arrays, and strings:

dash is a modern list library for Emacs that uses Haskell-like names for list operations ;-) Likewise, s is a useful Emacs string manipulation library.

In-fact, we can write Emacs extensions using Haskell directly.


Macros let us add new syntax, like let1 for single lets:

;; Noisy parens! (let ((x "5")) (message x)) ;; Better. (let1 x "5" (message x)) ;; How? (defmacro let1 (var val &rest body) `(let ((,var ,val)) ,@body)) ;; What does it look like? (macroexpand '(let1 x "5" (message x))) ;; ⇒ (let ((x 5)) (message x)) \columnbreak ;; No progn; (first x y z) ≈ x (defmacro first (&rest body) (car `,@body)) ;; Need to use “progn”! (defmacro not-first (&rest body) `(progn ,@(cdr `,@body))) (macroexpand '(not-first x y z)) ;; `,@body ⇒ (x y z) ;; (cdr `,@body) ⇒ (y z) ;; `(progn ,@(cdr `,@body)) ;; ⇒ (progn y z)
  1. Certain problems are elegantly solved specific language constructs; e.g., list operations are generally best defined by pattern matching.

  2. Macros let us make the best way to solve a problem when our language does not give it to us.

  3. Macro expansion happens before runtime, function execution, and so the arguments passed to a macro will contain raw source code.

    Backquotes let us use the comma to cause the actual variable names and values to be used –e.g., x is a ‘meta-variable’ and its value, ,x, refers to a real variable or value.

    The &rest marker allows us to have multiple statements at the end of the macro: The macro expander provides all remaining expressions in the macro as a list, the contents of which may be inserted in place, not as a list, using the ,@ splice comma –we need to ensure there’s a progn.

    Use list elements in-place:

    `` `(pre ,@(list s₀ ⋯ sₙ) post) ≈ `(pre s₀ ⋯ sₙ post) ``


read and print

‘Reading’ means parsing an expression in textual form and producing a lisp object. E.g., this is a way to load a lisp file. ‘Printing’ a lisp object mean producing a textual representation. These operations, in lisp, are mostly inverse.

The read-from-string command works just like the read command, but lets us read a lisp object from a string instead of directly from the console.

(defun sum-two ()
  (let (fst snd)
    (setq fst (read))
    (setq snd (read))
    (+ (eval fst) (eval snd))

;; Run (sum-two) with inputs (+ 1 2) and (* 3 4)  ;-)

Lisp makes writing a REPL astonishingly easy: “Loop as follows: Print the result of evaluating what is read at the prompt.”

(loop (print (eval (read))))  ;; Beautiful ♥‿♥

The print and read commands work on all kinds of data, such as lists of data structures. Hence, we must use quotes if we want to read a string rather than a symbol, for example.

A major problem with this REPL is that eval executes any, potentially malicious, Lisp command entered by the user. Ideally one checks the read lisp object is safe —say, it is one of some allowable commands— and only then evaluates it.