A macro receives its arguments as unevaluated Lisp data and returns a form to be evaluated in its place. Together with the special operators they are the syntax of Common Lisp. The HyperSpec documents 89 macro names on its macro pages; and, or, lambda and setf are filed with other kinds of entry but are macros too. These tables list them all. loop has its own page, and the condition macros are repeated on Conditions.
Definitions
| Macro | Syntax | Defines |
|---|---|---|
defun | (defun name lambda-list [doc] declaration* form*) | a global function, in a block named name; name may be (setf x) |
defmacro | (defmacro name macro-lambda-list [doc] declaration* form*) | a global macro |
define-compiler-macro | (define-compiler-macro name lambda-list …) | an optimising expansion the compiler may use for calls of the function name |
defvar | (defvar name [value [doc]]) | a special (dynamic) variable; the value is assigned only if the variable is unbound |
defparameter | (defparameter name value [doc]) | a special variable, always assigned |
defconstant | (defconstant name value [doc]) | a constant; redefining it with a value that is not eql is an error |
define-symbol-macro | (define-symbol-macro name expansion) | a global symbol macro |
deftype | (deftype name lambda-list form*) | a type specifier that expands into another |
defstruct | (defstruct (name option*) [doc] slot*) | a structure type with constructor, predicate, copier and accessors; options :conc-name :constructor :copier :predicate :include :print-function :print-object :type :named :initial-offset |
defclass | (defclass name (superclass*) (slot*) option*) | a class; see CLOS |
defgeneric | (defgeneric name lambda-list option* method*) | a generic function |
defmethod | (defmethod name qualifier* specialised-lambda-list form*) | a method |
define-method-combination | (define-method-combination name …) | a method combination, short or long form |
define-condition | (define-condition name (parent*) (slot*) option*) | a condition type |
defsetf | (defsetf access-fn update-fn) or long form | how setf stores into a place, simple form |
define-setf-expander | (define-setf-expander access-fn lambda-list form*) | a general setf expander |
define-modify-macro | (define-modify-macro name lambda-list function [doc]) | a macro like incf for any function |
defpackage | (defpackage name option*) | a package; see Symbols and packages |
in-package | (in-package name) | selects the current package |
declaim | (declaim declaration-spec*) | global declarations at compile time (proclaim is the function) |
A documentation string in a defun, defmacro, defgeneric, defmethod (and the lambda forms) comes after the lambda list and before the declarations, and is only a documentation string when other forms follow it; (documentation 'name 'function) reads it. defvar, defparameter and defconstant take it as the third argument. defclass and define-condition take it as (:documentation …). The viewer colours these strings like comments.
Conditionals and clauses
| Macro | Syntax | Does |
|---|---|---|
when | (when test form*) | forms if test is true, otherwise nil |
unless | (unless test form*) | forms if test is false |
cond | (cond (test form*)*) | the first clause with a true test; a clause with no forms returns the test value |
case, ecase, ccase | (case key ((k*) form*)* [(otherwise form*)]) | chooses by eql against the keys, a single atom or a list of keys; t or otherwise is the default (last only); ecase signals an error if nothing matches and ccase offers a restart and needs a place as key. A lone nil key must be (nil). |
typecase, etypecase, ctypecase | (typecase key (type form*)* …) | the same, by typep |
and, or | (and form*) | short-circuit; return the last or first deciding value; (and) is t and (or) is nil |
otherwise | in a case clause | an alias for t in the last clause |
Iteration and blocks
| Macro | Syntax | Does |
|---|---|---|
dolist | (dolist (var list [result]) form*) | binds var to each element; an implicit nil block |
dotimes | (dotimes (var count [result]) form*) | binds var to 0 to count-1 |
do, do* | (do ((var init step)*) (end-test result*) form*) | the general loop; do binds and steps in parallel, do* in sequence; the body is a tagbody |
do-symbols, do-external-symbols, do-all-symbols | (do-symbols (var [package [result]]) form*) | iterate over symbols |
loop, loop-finish | see Loop | simple and extended iteration; loop-finish leaves from inside |
return | (return [result]) | (return-from nil result) |
prog, prog* | (prog (binding*) declaration* {tag | form}*) | let or let* with an implicit block nil and tagbody |
prog1, prog2 | (prog1 first form*) | evaluate all; return the first (or second) value only |
Binding and multiple values
| Macro | Syntax | Does |
|---|---|---|
multiple-value-bind | (multiple-value-bind (var*) values-form declaration* form*) | binds variables to the values; missing ones are nil |
multiple-value-list | (multiple-value-list form) | the values as a list |
multiple-value-setq | (multiple-value-setq (var*) form) | assigns to variables |
nth-value | (nth-value n form) | one value, counting from 0 |
destructuring-bind | (destructuring-bind lambda-list expression declaration* form*) | takes a list apart by a lambda list |
lambda | (lambda lambda-list form*) | shorthand for #'(lambda …) |
with-slots, with-accessors | (with-slots (slot*) instance form*) | access slots or accessors as variables |
call-method, make-method | inside define-method-combination and method qualifiers | call a method and build an anonymous method |
Places
A place is a form that names a location: a variable, or a call such as (car x), (aref a i), (gethash k h), (getf plist key), (slot-value o 's), (ldb bytespec integer), (the type place), (values a b), (apply …), or a user-defined place.
| Macro | Syntax | Does |
|---|---|---|
setf | (setf {place value}*) | stores, in order; returns the last value |
psetf, psetq | (psetf {place value}*) | stores in parallel (all values first) |
incf, decf | (incf place [delta]) | adds or subtracts; delta defaults to 1 |
push, pushnew | (push item place) | conses onto the list in a place (pushnew only if absent, tested with :test, :key) |
pop | (pop place) | removes and returns the first element |
remf | (remf place indicator) | removes a property from a plist in a place |
rotatef, shiftf | (rotatef place*) | rotates values among places; shiftf shifts left and returns the old first |
Conditions and restarts
| Macro | Syntax | Does |
|---|---|---|
assert | (assert test [(place*) [format-control arg*]]) | signals a correctable error with a continue restart when the test is false |
check-type | (check-type place type [string]) | a correctable type-error with a store-value restart |
handler-case | (handler-case form (type ([var]) form*)* [(:no-error …)]) | run the form; on a condition of a type, unwind and run the clause |
handler-bind | (handler-bind ((type handler)*) form*) | run handlers without unwinding |
ignore-errors | (ignore-errors form*) | returns nil and the condition as a second value on error |
restart-case, restart-bind | (restart-case form (name lambda-list option* form*)*) | establish restarts |
with-simple-restart | (with-simple-restart (name format-control arg*) form*) | a restart that returns nil and t |
with-condition-restarts | (with-condition-restarts condition restarts form*) | associates restarts with a condition |
Input, output and the system
| Macro | Syntax | Does |
|---|---|---|
with-open-file | (with-open-file (stream path option*) form*) | opens a file and closes it on exit, even on error (:direction, :element-type, :if-exists, :if-does-not-exist, :external-format) |
with-open-stream | (with-open-stream (var stream) form*) | closes the stream on exit |
with-input-from-string | (with-input-from-string (var string option*) form*) | a string as an input stream |
with-output-to-string | (with-output-to-string (var [string]) form*) | collects output into a string |
with-standard-io-syntax | (with-standard-io-syntax form*) | binds the printer and reader variables to their standard values |
print-unreadable-object | (print-unreadable-object (object stream :type t :identity t) form*) | writes #<…> for a print-object method |
formatter | (formatter control-string) | compiles a format string to a function of a stream and arguments |
pprint-logical-block, pprint-pop, pprint-exit-if-list-exhausted | (pprint-logical-block (stream list :prefix p :suffix s) form*) | pretty-printer blocks |
with-hash-table-iterator, with-package-iterator | (with-hash-table-iterator (next table) form*) | local iterator functions for a table or package |
with-compilation-unit | (with-compilation-unit (option*) form*) | defers undefined-function warnings to the end of the unit |
step, time, trace, untrace | (time form) | the development tools: single-step, report run time and memory, trace and untrace functions |