Emacs Lisp

A dialect of Lisp that serves as the extension language of Emacs. The Emacs editor is largely written in it, and you use it to configure and extend Emacs. It is a dynamically-typed, primarily dynamically-scoped (historically) Lisp with deep integration into the editor (buffers, windows, text properties).

• C-x C-e evaluates the expression before point (eval-last-sexp).
• M-x eval-expression (M-:) prompts for an expression in the minibuffer.
• M-x eval-buffer / eval-region evaluate larger chunks.
• ielm opens an interactive Elisp REPL.

They are used almost interchangeably. A form is any Lisp object meant to be evaluated. Self-evaluating forms (numbers, strings, keywords), symbol forms (variables), and list forms (function/macro/special-form calls) are the categories.

With a semicolon ;. Conventions:

• ; inline comment after code.
• ;; comment aligned to the code's indentation.
• ;;; top-level/section comment.
• ;;;; heading.

Integers, floats, symbols, strings, characters (which are integers), cons cells/lists, vectors, hash tables, and more specialized types like markers, buffers, and overlays.

defvar declares a special (dynamic) variable and assigns a default only if it is not already bound. setq simply assigns a value to an existing binding. Use defvar for global configuration variables so re-evaluating a file doesn't clobber a user's value.

Adding (interactive ...) as its first form. Commands can be invoked via M-x and bound to keys.

(defun my-greet ()
  (interactive)
  (message "Hello!"))

Displays a formatted string in the echo area and logs it to the *Messages* buffer. Uses format-style directives: %s, %d, %S, etc.

nil is the canonical false value and also the empty list (). t is the canonical true value. Everything other than nil is truthy.

Yes. () and nil are identical objects in Elisp.

(list 1 (+ 1 1)) evaluates its arguments → (1 2). '(1 (+ 1 1)) does not evaluate → (1 (+ 1 1)). 'x is shorthand for (quote x).

car returns the first element of a cons cell; cdr returns the rest. For a list (1 2 3): (car list) → 1, (cdr list) → (2 3).

• eq — identity (same object); good for symbols, small integers.
• eql — like eq but also compares numbers of the same type.
• equal — structural equality (lists, strings).
• = — numeric equality (numbers only).
• string= — string equality.

when runs its body if the condition is non-nil (no else). unless runs its body if the condition is nil. Both allow multiple body forms without progn.

Evaluates several forms in sequence and returns the value of the last. Useful where a single form is expected but you need several.

A multi-branch conditional:

(cond
((< x 0) "negative")
((= x 0) "zero")
(t       "positive"))

let binds all variables in parallel (initializers can't see each other). let* binds sequentially so later bindings can reference earlier ones.

(let* ((a 1) (b (+ a 1))) b)  ; => 2  (let would error: a unbound)

(format "Name: %s, Age: %d" "Bob" 42)

format-message additionally translates quote characters for messages.

%s uses princ-style (human-readable, no quotes on strings). %S uses prin1-style (a readable, re-parseable representation with quotes/escapes).

• C-h f (describe-function)
• C-h v (describe-variable)
• C-h k (describe-key)
• C-h o (describe-symbol) — function or variable.

A first-class named object with four cells: name, value (variable binding), function (function binding), and property list. Symbols are interned in obarray so identical names refer to the same object.

A symbol can simultaneously name a variable and a function. (foo) uses the function cell; foo as a value uses the value cell. This is why Elisp is a "Lisp-2".

A symbol starting with : (e.g. :foo). It is self-evaluating and used as a constant marker, frequently in plists and keyword arguments.

The buffer that Elisp functions operate on by default. Most editing functions implicitly act on it. current-buffer returns it.

The location of the cursor / insertion position in a buffer, between two characters. (point) returns its integer position; point-min and point-max give the buffer boundaries.

A macro that saves point (and the current buffer) and restores them after its body runs — even on non-local exit. Use it when you move point temporarily.

(save-excursion
  (goto-char (point-min))
  (insert "header\n"))

Saves and restores the buffer's narrowing state (the visible region set by narrow-to-region / widen).

switch-to-buffer makes a buffer visible in the selected window (interactive, display-oriented). set-buffer only changes the current buffer for Elisp; it does not change what is displayed and is not preserved after the command.

Creates a temporary buffer, makes it current for the body, and kills it afterward. Ideal for text processing that shouldn't touch user buffers.

kbd converts a human-readable key description ("C-c C-x") into the internal key sequence representation. It's portable and clearer than raw string/vector forms.

p passes the numeric prefix argument as a number. P passes the raw prefix argument (e.g. nil, (4), a number). Many codes exist: s string, n number, r region, b buffer name, etc.

(buffer-substring-no-properties (region-beginning) (region-end))

For commands, declare (interactive "r") to receive start and end.

Use after-init-hook or emacs-startup-hook:

(add-hook 'emacs-startup-hook #'my-startup-fn)

An anonymous function:

(lambda (x) (* x x))
(funcall (lambda (x) (* x x)) 5)  ; => 25

#'foo is shorthand for (function foo). It quotes a function, and for lambdas it signals to the byte-compiler that the form is a function (enabling compilation of the lambda).

funcall calls a function with individual arguments. apply calls it with the last argument being a list that is spread into the remaining arguments.

(funcall #'+ 1 2 3)        ; => 6
(apply #'+ 1 2 '(3 4))     ; => 10

Dynamic scope: a variable's binding is visible to all code called during the binding's extent. Lexical scope: a variable is visible only within the textual region where it's defined. Modern Elisp files should enable lexical binding.

Put this as the first line of the file:

;;; -*- lexical-binding: t; -*-

It is the default in Emacs 30+ for new files but should be declared explicitly.

Only with lexical binding do lambdas capture their surrounding variables to form true closures.

(defun make-adder (n)
  (lambda (x) (+ x n)))   ; n captured lexically
(funcall (make-adder 3) 10)  ; => 13

Variables declared with defvar=/=defconst (special variables) remain dynamically scoped even under lexical binding. This is intentional — it's how let-rebinding of configuration variables works.

A flat list of alternating keys and values:

(setq pl '(:name "Bob" :age 42))
(plist-get pl :name)             ; => "Bob"
(plist-put pl :age 43)

A list of cons cells (key . value):

(setq al '((a . 1) (b . 2)))
(assq 'a al)        ; => (a . 1)
(alist-get 'b al)   ; => 2
(cdr (assoc "k" al))

For large collections or frequent lookups — hash tables give O(1) access vs alists' O(n).

(let ((h (make-hash-table :test 'equal)))
  (puthash "k" 1 h)
  (gethash "k" h))     ; => 1

eq, eql, equal (built-in), and you can define custom ones with define-hash-table-test. Use equal for string keys.

(maphash (lambda (k v) (message "%s=%s" k v)) h)

Or (hash-table-keys h) / (hash-table-values h) from subr-x=/=map.

• mapcar — applies fn to each element, returns a new list of results.
• mapc — applies fn for side effects, returns the input list.
• mapcan — like mapcar but destructively concatenates the (list) results.

A generic sequence-manipulation library (seq.el) that works uniformly across lists, vectors, and strings: seq-map, seq-filter, seq-find, seq-reduce, seq-do, seq-uniq, etc.

A popular third-party functional library providing -map, -filter, -reduce, threading macros -> / -->, etc. Many prefer built-in seq now, but dash remains common in the wild.

(sort '(3 1 2) #'<)            ; => (1 2 3)
(sort my-list :key #'car :lessp #'<) ; Emacs 30+ keyword form

Note: sort may be destructive; copy first if you need the original.

Destructive functions (nreverse, nconc, setcar, delete) modify their arguments' structure in place; non-destructive ones (reverse, append, remove) return fresh copies. Destructive variants are faster but risk aliasing bugs.

The Common Lisp compatibility library shipped with Emacs. It provides cl-loop, cl-defun, cl-destructuring-bind, cl-case, generic sequence functions, structures (cl-defstruct), and more. Always (require 'cl-lib).

(cl-case x
  (1 "one")
  ((2 3) "two or three")
  (t "other"))

pcase is the more powerful, idiomatic modern choice.

A pattern-matching case. It destructures and matches by structure, type, predicate, etc.

(pcase value
  ((pred stringp) "a string")
  (`(,a . ,b) (format "cons %s %s" a b))
  ((or 1 2 3) "small number")
  (_ "anything else"))

A function that runs at expansion time, receiving unevaluated code and returning new code to be evaluated. Macros let you extend the language syntax and control evaluation.

• Backquote starts a template where most things are literal.
• , unquotes — evaluates and inserts the value.
• ,@ splices a list's elements into the surrounding list.

(macroexpand '(my-unless t (foo)))
(macroexpand-1 ...)     ; one level
(macroexpand-all ...)   ; fully

M-x emacs-lisp-macroexpand or pp-macroexpand-last-sexp for interactive use.

When a macro introduces a binding whose name collides with user code, causing bugs. Avoid it by generating unique symbols with gensym=/=cl-gensym or make-symbol.

(defmacro my-swap (a b)
  (let ((tmp (gensym)))
    `(let ((,tmp ,a)) (setf ,a ,b) (setf ,b ,tmp))))

Use a function by default. Use a macro only when you must control evaluation (delay/repeat/skip arguments), introduce binding forms, or generate code at compile time. Macros don't compose like functions (can't funcall them).

Guarantees cleanup forms run whether or not the protected body exits normally or via error/non-local exit — like try/finally.

(unwind-protect
    (do-something)
  (cleanup))

ignore-errors evaluates body and returns nil on any error. with-demoted-errors turns errors into messages (useful in hooks/init so one failure doesn't abort everything).

A non-local exit mechanism by tag:

(catch 'found
  (dolist (x list)
    (when (match-p x) (throw 'found x))))

A lexical exit construct from cl-lib. cl-return-from exits a named block; cl-defun establishes an implicit block named after the function.

A very powerful iteration macro from cl-lib:

(cl-loop for i from 1 to 5
         when (cl-oddp i)
         collect (* i i))     ; => (1 9 25)

(when (re-search-forward "foo\\(bar\\)?" nil t)
  (match-string 0))

The third arg t means "return nil instead of erroring on failure."

Because the regexp is written as a string, and string syntax also uses backslash escapes. So a regexp group \(...\) must be written \\(...\\) in the string literal. rx avoids this.

A macro that builds regexps from readable s-expressions, eliminating backslash soup:

(rx bol (group (+ digit)) "-" (group (+ alpha)) eol)

looking-at tests whether text starting at point matches a regexp without moving point. re-search-forward scans forward and moves point past the match.

(narrow-to-region start end)   ; restrict visible/operable text
(widen)                        ; restore

Wrap in save-restriction when narrowing temporarily.

Objects that point to a position in a buffer and move automatically as text is inserted/deleted, unlike plain integer positions. Use them when you need a position to stay valid across edits.

Attributes attached to characters in a buffer/string (e.g. face, read-only, custom keys). They travel with the text.

(put-text-property start end 'face 'bold)
(propertize "hi" 'face 'warning)
(get-text-property pos 'face)

Text properties are part of the buffer text (copied/saved with it). Overlays are separate objects layered over a region, independent of the text, ideal for transient highlighting (e.g. search, flycheck). Overlays can be slower in large numbers.

bobp → point is at beginning of buffer; eobp → point is at end of buffer. Also bolp / eolp for line beginning/end.

A mode that defines the primary behavior of a buffer (syntax, keymap, font-locking, indentation). Each buffer has exactly one major mode. Defined with define-derived-mode.

A toggleable feature that augments behavior independently of the major mode (e.g. flyspell-mode). Many minor modes can be active at once. Defined with define-minor-mode.

A variable holding a list of functions run at a defined point (e.g. prog-mode-hook, before-save-hook). Add functions with add-hook.

It makes the intent (a function reference) explicit and lets the byte-compiler warn if the function is undefined. Plain symbols work too, but lambdas in hooks are hard to remove and should generally be avoided.

setq-local sets a buffer-local value. setq-default sets the default value that buffers without a local binding see. make-local-variable / make-variable-buffer-local control buffer-locality.

A variable whose value can differ per buffer. Mode code commonly uses setq-local to configure per-buffer behavior without affecting other buffers.

Declares a user-customizable variable integrated with the Customize UI, including a type, group, and docstring.

(defcustom my-width 80
  "Preferred width."
  :type 'integer
  :group 'my-group)

defgroup declares a customization group to organize options. defface declares a customizable face (font/color set) used for text display.

Set its safe-local-variable property with a predicate, or use the :safe keyword in defcustom:

(defcustom my-opt 1 "..." :type 'integer :safe #'integerp)

add-to-list adds an element only if not already present (using equal by default) and evaluates its arguments; it's meant for list-valued variables. push always prepends and is a generalized-variable macro. For defcustom lists, prefer setting via Customize or add-to-list.

A macro (built into Emacs 29+) for declarative, organized package configuration — deferring loading, binding keys, setting variables, and adding hooks in one tidy form.

(use-package magit
  :bind ("C-x g" . magit-status)
  :config (setq magit-diff-refine-hunk t))

An autoload registers a function name so that calling it loads the defining file on demand. Created via the ;;;###autoload magic comment and generated autoload files, or autoload directly. It speeds startup by deferring loads.

Compiling .el to .elc bytecode for faster loading/execution and earlier warnings. byte-compile-file, M-x byte-recompile-directory. Warnings catch undefined functions, unused vars, etc.

Emacs 28+ can compile Elisp to native machine code via libgccjit (native-comp), giving significant speedups. .eln files are produced and cached. Triggered automatically (native-comp-jit-compilation) or via native-compile.

Use the built-in profiler:

(profiler-start 'cpu)
;; ... do work ...
(profiler-report)
(profiler-stop)

nth=/=length on long lists are O(n). For random access use vectors; for keyed lookup use hash tables. Building a list with repeated append is O(n²); prefer push + nreverse.

push prepends (O(1)), building the list in reverse. nreverse flips it to the intended order at the end — an idiomatic, efficient way to accumulate a list.

Use lexical binding, prefer built-in primitives, avoid consing in loops, preallocate vectors, use cl-loop with collect, and byte/native compile. Raise gc-cons-threshold temporarily for bulk work.

Effectively yes for Lisp execution. Emacs 26+ has cooperative threads (make-thread) but they don't run truly in parallel — they yield at blocking points. Long computations still block the UI.

• run-with-timer / run-with-idle-timer for deferred work.
• Process-based async via make-process / start-process with filters and sentinels.
• url-retrieve for async HTTP; libraries like async.el for subprocess Lisp.

A filter function receives output chunks from an asynchronous process. A sentinel is called when the process changes state (e.g. exits). Together they let you handle subprocess I/O without blocking.

(make-process :name "ls" :command '("ls")
              :filter (lambda (proc out) (message "%s" out))
              :sentinel (lambda (proc ev) (message "done: %s" ev)))

A scheduled callback. run-with-timer fires after a delay (optionally repeating); run-with-idle-timer fires when Emacs has been idle for a period. Cancel with cancel-timer.

Delaying an action until input settles. Implement by canceling a pending timer and rescheduling on each event:

(defvar my--timer nil)
(defun my-debounced ()
  (when my--timer (cancel-timer my--timer))
  (setq my--timer (run-with-idle-timer 0.5 nil #'my-do-work)))