In this appendix:
• Basics
• Data Types
• Control Structures
• Code Objects
This appendix summarizes general Lisp syntax as used in Emacs, and some important Lisp functions. It does not summarize Emacs-specific features such as buffers, hook variables, keymaps, modes, and so on. For a complete Emacs Lisp reference, see The GNU Emacs Lisp Reference Manual. Details on obtaining it are in Appendix D, Obtaining and Building Emacs.
Basics
A Lisp expression is a unit of data that can be evaluated. The expression may be composed of subexpressions, as in the cases of lists and vectors.
Every Lisp expression has a way to produce a value when evaluated. Most kinds of expression are self-evaluating, which means that they are their own value.
A Lisp expression can be treated as literal data instead of being evaluated. Nonself-evaluating expressions must be quoted in order to use them as literals and prevent them from being evaluated.
The symbol nil denotes falsehood. It is exactly the same object as the empty list, ( ). Every other Lisp object denotes truth, but the symbol t is reserved to mean truth anyway.
Emacs Lisp (unlike some other dialects of Lisp) is case-sensitive.
Page 186
Data Types Numbers
Emacs Lisp supports integers and floating-point numbers. They're written in just the way you'd expect: as a string of base-10 digits with an optional leading minus sign and optional decimal point. Some functions that operate on numbers are:
(numberp x)
Test whether x is a number.
(integerp x)
Test whether x is an integer.
(zerop x)
Test whether x is zero.
(=a b)
Test whether two numbers are equal.
(+abc. . . ) Addition.
(-abc. . . ) Subtraction.
Characters
Single characters can be written in Emacs Lisp by preceding them with a question mark. For instance, ?a denotes lowercase a. Some special characters, particularly those that can be used to begin other kinds of Lisp expression, must be preceded with question mark-backslash, such as ?\'', ?\ (, and ? \). Some special characters can be written by combining a backslash with a letter. For instance, ?\t is a tab character, and ?\n is a newline character.
The result of evaluating a character is its ASCII code. For instance, evaluating ?a yields 97. In fact, integers can be used wherever characters are expected; Emacs Lisp does not distinguish between the two, except to allow the more convenient form of denoting characters.
(char-equal a b)
Test whether two characters are equal. Ignores case if the variable case- fold-search is non-nil.
(char-to-string c)
Create a one-character string containing c.
Page 187
Strings
A string is a sequence of characters, and is written by enclosing the characters in
double-quotes, "like this". If a double-quote or backslash appears in the string, it must be preceded with a backslash, "\"Like this,\" he said.". Strings are self-evaluating.
Emacs, being a text editor, has many functions for operating on strings. Here is a tiny sample:
(stringp x)
Test whether x is a string.
(string= s1 s2)
Test whether two strings are equal.
(string-lessp s1 s2)
Test whether string sl comes before string s2 according to ASCII sorting order.
(concat abc. . . )
Create a new string by concatenating other strings.
(length s)
Return the length in characters of string s.
(aref s i)
Return the ith character of string s, counting from 0.
(aset sich)
Set the ith character of string s to ch.
(substring sfim [to])
Extract the substring of s beginning at position from and extending to posi- tion to (or to the end of s if to is omitted).
Symbols
Symbols are names that can have certain kinds of data associated with them. The name of a symbol is a sequence of characters that must not look like a number, string, list, vector, or other Lisp data type.
Symbols can be used as variables, function names, or as atomic values themselves. The result of evaluating a symbol is its variable value.
(symbolp x)
Test whether x is a symbol.
(setq sym epr)
Use sym as a variable: assign the value of expr to sym.
Page 188
sym
A symbol evaluates to its value as a variable.
(defun sym. . . )
Use sym as a function name.
(sym arg1 arg2 . . . )
A list that starts with a symbol denotes a function call of the function named by sym.
Every symbol has a property list associated with it. The property list is a mapping where the keys are Lisp symbols and the values are arbitrary Lisp expressions.
(put sym key value)
In sym's property list, assign value to symbol key.
(get sym key)
Get the value previously assigned to symbol key in sym's property list, or nil if there was none.
Symbols are normally stored internally in a symbol table to prevent duplicate symbols from being created. It is possible to explicitly add entries to the symbol table or to create symbols that are not placed in the symbol table (and which may therefore duplicate the name of other symbols).
(intern string)
Return a symbol from the internal symbol table whose name is string. If one didn't previously exist, one is created.
(make-symbol string
Return a brand-new symbol whose name is string. The symbol is not placed in the internal symbol table, and is distinct from all other objects, including identically named symbols.
Lists
Lists are the foundation of Lisp. A list is a sequence of zero or more other Lisp expressions (including, potentially, other lists). A list is written by writing its subexpressions, separated by whitespace; and then surrounding the whole sequence with a pair of parentheses.
Lists are used to denote function calls in Lisp. When evaluated, the function designated by the first element of the list is invoked, with the values of the remaining elements as arguments.
Internally, a list is implemented as a chain of cons cells. Accessing an item in the list therefore entails traversing the chain until the element is found.
Page 189
(listp x)
Test whether x is a list.
(null x)
Test whether x is the empty list.
(consp x)
Test whether x is a non-empty list.
(car list)
Return the first element of list (or the first part of a cons cell).
(cdr list)
Return the remainder (all but the first element) of list (or the second part of a cons cell).
(list abc. . . )
Construct a new list, with the values of the given arguments as elements.
(cons a b)
Insert a at the beginning of list b (or create a new cons cell (a. b).
(append list list2 . . . )
Create a new list by (effectively) stripping off each sublist's outer parentheses, sticking all the elements together, and surrounding the whole thing with a new pair of parentheses.
(nth i list)
Return the ith subexpression of list, counting from 0.
(nthcdr i list)
Return the result of calling cdr on list i times.
Lists are covered in detail in Chapter 6, Lists.
Vectors
Like a list, a vector is a sequence of zero or more subexpressions, written with square brackets instead of parentheses. Unlike a list, a vector's elements can be randomly accessed (without first traversing an internal data structure). Vectors are self-evaluating.
When you write a vector, its subexpressions are automatically quoted. To construct a vector from elements that are evaluated first, use the vector function.
(vectorp x)
Test whether x is a vector.
(vector abc. . . )
Construct a new vector, with the values of the given arguments as elements.
Page 190
(length vector
Return the length of vector.
(aref vectori)
Return the ith subexpression of vector, counting from zero.
(aset vector i expr)
Set the ith element of vector to expr.
Sequences and Arrays
Some Emacs Lisp data types are related. Strings and vectors are both kinds of arrays. An array is a linear collection of data elements that permits random access to its elements. A string is an array of characters, while a vector is an array of arbitrary expressions. The
functions aref and aset are for manipulating arrays, and work on vectors as well as strings.
A sequence is an even more general kind of data structure that includes arrays and lists. A sequence is a linear collection of data elements, period. The function length works on lists, strings, and arrays.
(arrayp x)
Test whether x is an array.
(sequencep x)
Test whether x is a sequence.
(copy-sequence sequence)
Return a copy of the list, string, or vector sequence.
Control Structures Variables
To reference a variable, simply use its name (a symbol). To assign a variable, use setq.
(setq x 17) ;assign 17 to variable x x = 17 ; value ofvariable x
To make temporary variables that are in effect only in a certain region of code, use let.
(let ( (var1 vauue]) (ar2 value2) . . . )
bodyl body2 .. .)
Page 191
In a let, all the values are computed in an unspecified order before any of the vats are
assigned. The variant let* (whose syntax is identical to let) evaluates valuei and assigns it to vari before evaluating valuei+1.
Sequencing
To evaluate a sequence of expressions where only a single expression is allowed, use progn.
(progn expr1 expr2 . . . )
Evaluates each expr in turn. Returns the value of the last expr.
To evaluate a sequence of expressions and return the value of the first subexpression instead of the last, use progl.
Conditionals
Emacs Lisp has two kinds of conditional expression: if and cond.
(if test then
else1 else2 . . . )
Evaluates test. If the result is non-nil, evaluates then. Otherwise, evaluates each else expression in turn. Returns the value of the last expression it evaluates.
(cond ( (test1 od body12 . ..) ( st2 bod)1 body22 . .. )
Evaluates test1. If the result is non-nil, evaluates each body1 in turn. Otherwise evaluates test2. If the result is non-nil, evaluates each body2, and so on with each 'cond clause." Returns the value of the last expression it evaluates. A common practice is to place a catch-all clause at the end like this:
(cond ( (test1 bodyll body12 . ..) ( test2 body21 body2 . . .
(t bodyn1 bodyn2 . . . )))
The logical operators and, or, and not are often used in conjunction with—and sometimes as substitutes for—conditionals.
(and exprl expr2 . . . )
Evaluates each expr until one returns nil (or it runs out of subexpressions), then returns. The result is the value of the last expression evaluated. This is the logical operation "and" because and returns truth if and only if none of its subexpressions is false.
Page 192
The expressions
(if eprl (if expr2
(if arn-l ePn) ) )
and
(if (and expr1 expr . . . nprl)
earn )
are frequently condensed to
(and eprl expr2 . . . xprn1 exprn) The expression
(or epr1 eaxpr2 . . . )
evaluates each expr until one returns non-nil (or it runs out of subexpressions), then returns.
The result is the value of the last expression evaluated. This is the logical operation "or"
because or returns falsehood if and only if none of its subexpressions is true.
The expression
(if aab)
is often condensed to
(or a b)
Finally,
(not expr)
returns the logical negation of expr. If expr evaluates true, return nil. If expr evaluates false, return t. (Interestingly, not is the same exact function as null.)
Looping
Emacs Lisp has one looping function, while.
(while test
boded bodyj . . . )
Evaluates test. If the result is non-nil, evaluates each body in turn. Then repeats. Returns when test yields nil.
Page 193
Function Call
To call a function, write a list whose first element is the function name and whose remaining elements are the arguments to the function.
(function arg1 arg2 . . . )
Calls function with the given arguments; returns the result of function.
Literal Data
To make a literal out of a control structure—i.e., to prevent an expression from being evaluated-quote it by preceding it with '
expr ⇒ epr
(quote expr) ⇒ epr ;same thing
To make a literal list in which individual subexpressions can be evaluated, backquote it, then
unquote the individual subexpressions.
'(a b c) ⇒ (a b c)
(backquote (a b c)) ⇒ (a b c) ;samething '(a ,b c) ⇒ (a value-of-b c)
To unquote a list-valued expression and "splice" its elements into the containing backquote template, use the splicing unquote operator, ",@".
(setq b '(x y z))
'(a ,@b c) ⇒ (a x y z c)
Code Objects Functions
A function is a list in the following form:
(lambda (parameters . . . ) "documentation string"
body1' body2 . . . )
The documentation string is optional.
When the function is invoked, the actual arguments will be bound to the parameters listed in the parameter list. The keyword &optional appearing in the parameter list means the following parameters are optional. If the function is called without a value for an optional parameter, the parameter is assigned nil. The last parameter may be preceded by the keyword
&rest, meaning that all remaining unused arguments are placed in a list and assigned to that parameter.
The result of invoking a function is the result of the last body expression.
Page 194
To define a function with a name, use defun.
(defun name (prammetes . . . ) "documentation string"
Ibody' body4 .. )
This creates a lambda expression and assigns it to the function value of the symbol name.
This is different from name's variable value, so there is no conflict between function names and variable names.
Macro Functions
A macro function is a list like a lambda expression, but instead of lambda, macro is used.
When a macro is invoked, its arguments are not evaluated. Instead, they are used in their literal form to compute a new Lisp expression. Then that is evaluated.
To define a macro with a name, use defmacro exactly like defun.
Page 195