2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1994, 2001-2017 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
9 Most of the GNU Emacs text editor is written in the programming
10 language called Emacs Lisp. You can write new code in Emacs Lisp and
11 install it as an extension to the editor. However, Emacs Lisp is more
12 than a mere extension language; it is a full computer programming
13 language in its own right. You can use it as you would any other
16 Because Emacs Lisp is designed for use in an editor, it has special
17 features for scanning and parsing text as well as features for handling
18 files, buffers, displays, subprocesses, and so on. Emacs Lisp is
19 closely integrated with the editing facilities; thus, editing commands
20 are functions that can also conveniently be called from Lisp programs,
21 and parameters for customization are ordinary Lisp variables.
23 This manual attempts to be a full description of Emacs Lisp. For a
24 beginner's introduction to Emacs Lisp, see @cite{An Introduction to
25 Emacs Lisp Programming}, by Bob Chassell, also published by the Free
26 Software Foundation. This manual presumes considerable familiarity with
27 the use of Emacs for editing; see @cite{The GNU Emacs Manual} for this
30 Generally speaking, the earlier chapters describe features of Emacs
31 Lisp that have counterparts in many programming languages, and later
32 chapters describe features that are peculiar to Emacs Lisp or relate
33 specifically to editing.
37 edition @value{VERSION} of
39 the @cite{GNU Emacs Lisp Reference Manual},
40 corresponding to Emacs version @value{EMACSVER}.
43 * Caveats:: Flaws and a request for help.
44 * Lisp History:: Emacs Lisp is descended from Maclisp.
45 * Conventions:: How the manual is formatted.
46 * Version Info:: Which Emacs version is running?
47 * Acknowledgments:: The authors, editors, and sponsors of this manual.
52 @cindex bugs in this manual
54 This manual has gone through numerous drafts. It is nearly complete
55 but not flawless. There are a few topics that are not covered, either
56 because we consider them secondary (such as most of the individual
57 modes) or because they are yet to be written. Because we are not able
58 to deal with them completely, we have left out several parts
61 The manual should be fully correct in what it does cover, and it is
62 therefore open to criticism on anything it says---from specific examples
63 and descriptive text, to the ordering of chapters and sections. If
64 something is confusing, or you find that you have to look at the sources
65 or experiment to learn something not covered in the manual, then perhaps
66 the manual should be fixed. Please let us know.
69 As you use this manual, we ask that you mark pages with corrections so
70 you can later look them up and send them to us. If you think of a simple,
71 real-life example for a function or group of functions, please make an
72 effort to write it up and send it in. Please reference any comments to
73 the chapter name, section name, and function name, as appropriate, since
74 page numbers and chapter and section numbers will change and we may have
75 trouble finding the text you are talking about. Also state the version
76 of the edition you are criticizing.
80 As you use this manual, we ask that you send corrections as soon as you
81 find them. If you think of a simple, real life example for a function
82 or group of functions, please make an effort to write it up and send it
83 in. Please reference any comments to the node name and function or
84 variable name, as appropriate. Also state the number of the edition
90 Please send comments and corrections using @kbd{M-x report-emacs-bug}.
96 Lisp (LISt Processing language) was first developed in the late 1950s
97 at the Massachusetts Institute of Technology for research in artificial
98 intelligence. The great power of the Lisp language makes it ideal
99 for other purposes as well, such as writing editing commands.
103 Dozens of Lisp implementations have been built over the years, each
104 with its own idiosyncrasies. Many of them were inspired by Maclisp,
105 which was written in the 1960s at MIT's Project MAC@. Eventually the
106 implementers of the descendants of Maclisp came together and developed a
107 standard for Lisp systems, called Common Lisp. In the meantime, Gerry
108 Sussman and Guy Steele at MIT developed a simplified but very powerful
109 dialect of Lisp, called Scheme.
111 GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common
112 Lisp. If you know Common Lisp, you will notice many similarities.
113 However, many features of Common Lisp have been omitted or
114 simplified in order to reduce the memory requirements of GNU Emacs.
115 Sometimes the simplifications are so drastic that a Common Lisp user
116 might be very confused. We will occasionally point out how GNU Emacs
117 Lisp differs from Common Lisp. If you don't know Common Lisp, don't
118 worry about it; this manual is self-contained.
121 A certain amount of Common Lisp emulation is available via the
122 @file{cl-lib} library. @xref{Top,, Overview, cl, Common Lisp Extensions}.
124 Emacs Lisp is not at all influenced by Scheme; but the GNU project has
125 an implementation of Scheme, called Guile. We use it in all new GNU
126 software that calls for extensibility.
131 This section explains the notational conventions that are used in this
132 manual. You may want to skip this section and refer back to it later.
135 * Some Terms:: Explanation of terms we use in this manual.
136 * nil and t:: How the symbols @code{nil} and @code{t} are used.
137 * Evaluation Notation:: The format we use for examples of evaluation.
138 * Printing Notation:: The format we use when examples print text.
139 * Error Messages:: The format we use for examples of errors.
140 * Buffer Text Notation:: The format we use for buffer contents in examples.
141 * Format of Descriptions:: Notation for describing functions, variables, etc.
145 @subsection Some Terms
147 Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp
148 printer'' refer to those routines in Lisp that convert textual
149 representations of Lisp objects into actual Lisp objects, and vice
150 versa. @xref{Printed Representation}, for more details. You, the
151 person reading this manual, are thought of as the programmer and are
152 addressed as ``you''. The user is the person who uses Lisp
153 programs, including those you write.
155 @cindex typographic conventions
156 Examples of Lisp code are formatted like this: @code{(list 1 2 3)}.
157 Names that represent metasyntactic variables, or arguments to a function
158 being described, are formatted like this: @var{first-number}.
161 @subsection @code{nil} and @code{t}
167 In Emacs Lisp, the symbol @code{nil} has three separate meanings: it
168 is a symbol with the name @samp{nil}; it is the logical truth value
169 @var{false}; and it is the empty list---the list of zero elements.
170 When used as a variable, @code{nil} always has the value @code{nil}.
172 As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are
173 identical: they stand for the same object, the symbol @code{nil}. The
174 different ways of writing the symbol are intended entirely for human
175 readers. After the Lisp reader has read either @samp{()} or @samp{nil},
176 there is no way to determine which representation was actually written
179 In this manual, we write @code{()} when we wish to emphasize that it
180 means the empty list, and we write @code{nil} when we wish to emphasize
181 that it means the truth value @var{false}. That is a good convention to use
182 in Lisp programs also.
185 (cons 'foo ()) ; @r{Emphasize the empty list}
186 (setq foo-flag nil) ; @r{Emphasize the truth value @var{false}}
191 In contexts where a truth value is expected, any non-@code{nil} value
192 is considered to be @var{true}. However, @code{t} is the preferred way
193 to represent the truth value @var{true}. When you need to choose a
194 value that represents @var{true}, and there is no other basis for
195 choosing, use @code{t}. The symbol @code{t} always has the value
198 In Emacs Lisp, @code{nil} and @code{t} are special symbols that always
199 evaluate to themselves. This is so that you do not need to quote them
200 to use them as constants in a program. An attempt to change their
201 values results in a @code{setting-constant} error. @xref{Constant
204 @defun booleanp object
205 Return non-@code{nil} if @var{object} is one of the two canonical
206 boolean values: @code{t} or @code{nil}.
209 @node Evaluation Notation
210 @subsection Evaluation Notation
211 @cindex evaluation notation
212 @cindex documentation notation
215 A Lisp expression that you can evaluate is called a @dfn{form}.
216 Evaluating a form always produces a result, which is a Lisp object. In
217 the examples in this manual, this is indicated with @samp{@result{}}:
225 You can read this as ``@code{(car '(1 2))} evaluates to 1''.
227 When a form is a macro call, it expands into a new form for Lisp to
228 evaluate. We show the result of the expansion with
229 @samp{@expansion{}}. We may or may not show the result of the
230 evaluation of the expanded form.
234 @expansion{} (car (cdr (cdr '(a b c))))
238 To help describe one form, we sometimes show another form that
239 produces identical results. The exact equivalence of two forms is
240 indicated with @samp{@equiv{}}.
243 (make-sparse-keymap) @equiv{} (list 'keymap)
246 @node Printing Notation
247 @subsection Printing Notation
248 @cindex printing notation
250 Many of the examples in this manual print text when they are
251 evaluated. If you execute example code in a Lisp Interaction buffer
252 (such as the buffer @file{*scratch*}), the printed text is inserted into
253 the buffer. If you execute the example by other means (such as by
254 evaluating the function @code{eval-region}), the printed text is
255 displayed in the echo area.
257 Examples in this manual indicate printed text with @samp{@print{}},
258 irrespective of where that text goes. The value returned by
259 evaluating the form follows on a separate line with
264 (progn (prin1 'foo) (princ "\n") (prin1 'bar))
272 @subsection Error Messages
273 @cindex error message notation
275 Some examples signal errors. This normally displays an error message
276 in the echo area. We show the error message on a line starting with
277 @samp{@error{}}. Note that @samp{@error{}} itself does not appear in
282 @error{} Wrong type argument: number-or-marker-p, x
285 @node Buffer Text Notation
286 @subsection Buffer Text Notation
287 @cindex buffer text notation
289 Some examples describe modifications to the contents of a buffer, by
290 showing the before and after versions of the text. These
291 examples show the contents of the buffer in question between two lines
292 of dashes containing the buffer name. In addition, @samp{@point{}}
293 indicates the location of point. (The symbol for point, of course, is
294 not part of the text in the buffer; it indicates the place
295 @emph{between} two characters where point is currently located.)
298 ---------- Buffer: foo ----------
299 This is the @point{}contents of foo.
300 ---------- Buffer: foo ----------
304 ---------- Buffer: foo ----------
305 This is the changed @point{}contents of foo.
306 ---------- Buffer: foo ----------
309 @node Format of Descriptions
310 @subsection Format of Descriptions
311 @cindex description format
313 Functions, variables, macros, commands, user options, and special
314 forms are described in this manual in a uniform format. The first
315 line of a description contains the name of the item followed by its
318 The category---function, variable, or whatever---appears at the
319 beginning of the line.
322 The category---function, variable, or whatever---is printed next to the
325 The description follows on succeeding lines, sometimes with examples.
328 * A Sample Function Description:: A description of an imaginary
329 function, @code{foo}.
330 * A Sample Variable Description:: A description of an imaginary
332 @code{electric-future-map}.
335 @node A Sample Function Description
336 @subsubsection A Sample Function Description
337 @cindex function descriptions
338 @cindex command descriptions
339 @cindex macro descriptions
340 @cindex special form descriptions
342 In a function description, the name of the function being described
343 appears first. It is followed on the same line by a list of argument
344 names. These names are also used in the body of the description, to
345 stand for the values of the arguments.
347 The appearance of the keyword @code{&optional} in the argument list
348 indicates that the subsequent arguments may be omitted (omitted
349 arguments default to @code{nil}). Do not write @code{&optional} when
350 you call the function.
352 The keyword @code{&rest} (which must be followed by a single
353 argument name) indicates that any number of arguments can follow. The
354 single argument name following @code{&rest} receives, as its
355 value, a list of all the remaining arguments passed to the function.
356 Do not write @code{&rest} when you call the function.
358 Here is a description of an imaginary function @code{foo}:
360 @defun foo integer1 &optional integer2 &rest integers
361 The function @code{foo} subtracts @var{integer1} from @var{integer2},
362 then adds all the rest of the arguments to the result. If @var{integer2}
363 is not supplied, then the number 19 is used by default.
376 (foo @var{w} @var{x} @var{y}@dots{})
378 (+ (- @var{x} @var{w}) @var{y}@dots{})
382 By convention, any argument whose name contains the name of a type
383 (e.g., @var{integer}, @var{integer1} or @var{buffer}) is expected to
384 be of that type. A plural of a type (such as @var{buffers}) often
385 means a list of objects of that type. An argument named @var{object}
386 may be of any type. (For a list of Emacs object types, @pxref{Lisp
387 Data Types}.) An argument with any other sort of name
388 (e.g., @var{new-file}) is specific to the function; if the function
389 has a documentation string, the type of the argument should be
390 described there (@pxref{Documentation}).
392 @xref{Lambda Expressions}, for a more complete description of
393 arguments modified by @code{&optional} and @code{&rest}.
395 Command, macro, and special form descriptions have the same format,
396 but the word @samp{Function} is replaced by @samp{Command},
397 @samp{Macro}, or @samp{Special Form}, respectively. Commands are
398 simply functions that may be called interactively; macros process
399 their arguments differently from functions (the arguments are not
400 evaluated), but are presented the same way.
402 The descriptions of macros and special forms use a more complex
403 notation to specify optional and repeated arguments, because they can
404 break the argument list down into separate arguments in more
405 complicated ways. @samp{@r{[}@var{optional-arg}@r{]}} means that
406 @var{optional-arg} is optional and @samp{@var{repeated-args}@dots{}}
407 stands for zero or more arguments. Parentheses are used when several
408 arguments are grouped into additional levels of list structure. Here
411 @defspec count-loop (var [from to [inc]]) body@dots{}
412 This imaginary special form implements a loop that executes the
413 @var{body} forms and then increments the variable @var{var} on each
414 iteration. On the first iteration, the variable has the value
415 @var{from}; on subsequent iterations, it is incremented by one (or by
416 @var{inc} if that is given). The loop exits before executing @var{body}
417 if @var{var} equals @var{to}. Here is an example:
421 (prin1 i) (princ " ")
422 (prin1 (aref vector i))
426 If @var{from} and @var{to} are omitted, @var{var} is bound to
427 @code{nil} before the loop begins, and the loop exits if @var{var} is
428 non-@code{nil} at the beginning of an iteration. Here is an example:
437 In this special form, the arguments @var{from} and @var{to} are
438 optional, but must both be present or both absent. If they are present,
439 @var{inc} may optionally be specified as well. These arguments are
440 grouped with the argument @var{var} into a list, to distinguish them
441 from @var{body}, which includes all remaining elements of the form.
444 @node A Sample Variable Description
445 @subsubsection A Sample Variable Description
446 @cindex variable descriptions
447 @cindex option descriptions
449 A @dfn{variable} is a name that can be @dfn{bound} (or @dfn{set}) to
450 an object. The object to which a variable is bound is called a
451 @dfn{value}; we say also that variable holds that value.
452 Although nearly all variables can be set by the user, certain
453 variables exist specifically so that users can change them; these are
454 called @dfn{user options}. Ordinary variables and user options are
455 described using a format like that for functions, except that there
458 Here is a description of the imaginary @code{electric-future-map}
461 @defvar electric-future-map
462 The value of this variable is a full keymap used by Electric Command
463 Future mode. The functions in this map allow you to edit commands you
464 have not yet thought about executing.
467 User option descriptions have the same format, but @samp{Variable}
468 is replaced by @samp{User Option}.
471 @section Version Information
473 These facilities provide information about which version of Emacs is
476 @deffn Command emacs-version &optional here
477 This function returns a string describing the version of Emacs that is
478 running. It is useful to include this string in bug reports.
483 @result{} "GNU Emacs 24.5.1 (x86_64-unknown-linux-gnu, GTK+ Version 3.16)
488 If @var{here} is non-@code{nil}, it inserts the text in the buffer
489 before point, and returns @code{nil}. When this function is called
490 interactively, it prints the same information in the echo area, but
491 giving a prefix argument makes @var{here} non-@code{nil}.
494 @defvar emacs-build-time
495 The value of this variable indicates the time at which Emacs was
496 built. It is a list of four integers, like the value of
497 @code{current-time} (@pxref{Time of Day}).
502 @result{} (20614 63694 515336 438000)
507 @defvar emacs-version
508 The value of this variable is the version of Emacs being run. It is a
509 string such as @code{"23.1.1"}. The last number in this string is not
510 really part of the Emacs release version number; it is incremented
511 each time Emacs is built in any given directory. A value with four
512 numeric components, such as @code{"22.0.91.1"}, indicates an
513 unreleased test version.
516 @defvar emacs-major-version
517 The major version number of Emacs, as an integer. For Emacs version
518 23.1, the value is 23.
521 @defvar emacs-minor-version
522 The minor version number of Emacs, as an integer. For Emacs version
523 23.1, the value is 1.
526 @node Acknowledgments
527 @section Acknowledgments
529 This manual was originally written by Robert Krawitz, Bil Lewis, Dan
530 LaLiberte, Richard@tie{}M. Stallman and Chris Welty, the volunteers of
531 the GNU manual group, in an effort extending over several years.
532 Robert@tie{}J. Chassell helped to review and edit the manual, with the
533 support of the Defense Advanced Research Projects Agency, ARPA Order
534 6082, arranged by Warren@tie{}A. Hunt, Jr.@: of Computational Logic,
535 Inc. Additional sections have since been written by Miles Bader, Lars
536 Brinkhoff, Chong Yidong, Kenichi Handa, Lute Kamstra, Juri Linkov,
537 Glenn Morris, Thien-Thi Nguyen, Dan Nicolaescu, Martin Rudalics, Kim
538 F. Storm, Luc Teirlinck, and Eli Zaretskii, and others.
540 Corrections were supplied by Drew Adams, Juanma Barranquero, Karl
541 Berry, Jim Blandy, Bard Bloom, Stephane Boucher, David Boyes, Alan
542 Carroll, Richard Davis, Lawrence R. Dodd, Peter Doornbosch, David
543 A. Duff, Chris Eich, Beverly Erlebacher, David Eckelkamp, Ralf Fassel,
544 Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow, Jesper
545 Harder, George Hartzell, Nathan Hess, Masayuki Ida, Dan Jacobson, Jak
546 Kirman, Bob Knighten, Frederick M. Korz, Joe Lammens, Glenn M. Lewis,
547 K. Richard Magill, Brian Marick, Roland McGrath, Stefan Monnier, Skip
548 Montanaro, John Gardiner Myers, Thomas A. Peterson, Francesco Potortì,
549 Friedrich Pukelsheim, Arnold D. Robbins, Raul Rockwell, Jason Rumney,
550 Per Starbäck, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, Bill
551 Trost, Rickard Westman, Jean White, Eduard Wiebe, Matthew Wilding,
552 Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn.
554 For a more complete list of contributors, please see the relevant
555 change log entries in the Emacs source repository.