This is elisp, produced by makeinfo version 4.0f from ./elisp.texi. INFO-DIR-SECTION Editors START-INFO-DIR-ENTRY * Elisp: (elisp). The Emacs Lisp Reference Manual. END-INFO-DIR-ENTRY This Info file contains edition 2.8 of the GNU Emacs Lisp Reference Manual, corresponding to Emacs version 21.2. Published by the Free Software Foundation 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "Copying", with the Front-Cover texts being "A GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License". (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."  File: elisp, Node: Symbol Plists, Next: Other Plists, Prev: Plists and Alists, Up: Property Lists Property List Functions for Symbols ----------------------------------- - Function: symbol-plist symbol This function returns the property list of SYMBOL. - Function: setplist symbol plist This function sets SYMBOL's property list to PLIST. Normally, PLIST should be a well-formed property list, but this is not enforced. (setplist 'foo '(a 1 b (2 3) c nil)) => (a 1 b (2 3) c nil) (symbol-plist 'foo) => (a 1 b (2 3) c nil) For symbols in special obarrays, which are not used for ordinary purposes, it may make sense to use the property list cell in a nonstandard fashion; in fact, the abbrev mechanism does so (*note Abbrevs::). - Function: get symbol property This function finds the value of the property named PROPERTY in SYMBOL's property list. If there is no such property, `nil' is returned. Thus, there is no distinction between a value of `nil' and the absence of the property. The name PROPERTY is compared with the existing property names using `eq', so any object is a legitimate property. See `put' for an example. - Function: put symbol property value This function puts VALUE onto SYMBOL's property list under the property name PROPERTY, replacing any previous property value. The `put' function returns VALUE. (put 'fly 'verb 'transitive) =>'transitive (put 'fly 'noun '(a buzzing little bug)) => (a buzzing little bug) (get 'fly 'verb) => transitive (symbol-plist 'fly) => (verb transitive noun (a buzzing little bug))  File: elisp, Node: Other Plists, Prev: Symbol Plists, Up: Property Lists Property Lists Outside Symbols ------------------------------ These functions are useful for manipulating property lists that are stored in places other than symbols: - Function: plist-get plist property This returns the value of the PROPERTY property stored in the property list PLIST. For example, (plist-get '(foo 4) 'foo) => 4 - Function: plist-put plist property value This stores VALUE as the value of the PROPERTY property in the property list PLIST. It may modify PLIST destructively, or it may construct a new list structure without altering the old. The function returns the modified property list, so you can store that back in the place where you got PLIST. For example, (setq my-plist '(bar t foo 4)) => (bar t foo 4) (setq my-plist (plist-put my-plist 'foo 69)) => (bar t foo 69) (setq my-plist (plist-put my-plist 'quux '(a))) => (bar t foo 69 quux (a)) You could define `put' in terms of `plist-put' as follows: (defun put (symbol prop value) (setplist symbol (plist-put (symbol-plist symbol) prop value))) - Function: plist-member plist property This returns non-`nil' if PLIST contains the given PROPERTY. Unlike `plist-get', this allows you to distinguish between a missing property and a property with the value `nil'. The value is actually the tail of PLIST whose `car' is PROPERTY.  File: elisp, Node: Evaluation, Next: Control Structures, Prev: Symbols, Up: Top Evaluation ********** The "evaluation" of expressions in Emacs Lisp is performed by the "Lisp interpreter"--a program that receives a Lisp object as input and computes its "value as an expression". How it does this depends on the data type of the object, according to rules described in this chapter. The interpreter runs automatically to evaluate portions of your program, but can also be called explicitly via the Lisp primitive function `eval'. * Menu: * Intro Eval:: Evaluation in the scheme of things. * Forms:: How various sorts of objects are evaluated. * Quoting:: Avoiding evaluation (to put constants in the program). * Eval:: How to invoke the Lisp interpreter explicitly.  File: elisp, Node: Intro Eval, Next: Forms, Up: Evaluation Introduction to Evaluation ========================== The Lisp interpreter, or evaluator, is the program that computes the value of an expression that is given to it. When a function written in Lisp is called, the evaluator computes the value of the function by evaluating the expressions in the function body. Thus, running any Lisp program really means running the Lisp interpreter. How the evaluator handles an object depends primarily on the data type of the object. A Lisp object that is intended for evaluation is called an "expression" or a "form". The fact that expressions are data objects and not merely text is one of the fundamental differences between Lisp-like languages and typical programming languages. Any object can be evaluated, but in practice only numbers, symbols, lists and strings are evaluated very often. It is very common to read a Lisp expression and then evaluate the expression, but reading and evaluation are separate activities, and either can be performed alone. Reading per se does not evaluate anything; it converts the printed representation of a Lisp object to the object itself. It is up to the caller of `read' whether this object is a form to be evaluated, or serves some entirely different purpose. *Note Input Functions::. Do not confuse evaluation with command key interpretation. The editor command loop translates keyboard input into a command (an interactively callable function) using the active keymaps, and then uses `call-interactively' to invoke the command. The execution of the command itself involves evaluation if the command is written in Lisp, but that is not a part of command key interpretation itself. *Note Command Loop::. Evaluation is a recursive process. That is, evaluation of a form may call `eval' to evaluate parts of the form. For example, evaluation of a function call first evaluates each argument of the function call, and then evaluates each form in the function body. Consider evaluation of the form `(car x)': the subform `x' must first be evaluated recursively, so that its value can be passed as an argument to the function `car'. Evaluation of a function call ultimately calls the function specified in it. *Note Functions::. The execution of the function may itself work by evaluating the function definition; or the function may be a Lisp primitive implemented in C, or it may be a byte-compiled function (*note Byte Compilation::). The evaluation of forms takes place in a context called the "environment", which consists of the current values and bindings of all Lisp variables.(1) Whenever a form refers to a variable without creating a new binding for it, the value of the variable's binding in the current environment is used. *Note Variables::. Evaluation of a form may create new environments for recursive evaluation by binding variables (*note Local Variables::). These environments are temporary and vanish by the time evaluation of the form is complete. The form may also make changes that persist; these changes are called "side effects". An example of a form that produces side effects is `(setq foo 1)'. The details of what evaluation means for each kind of form are described below (*note Forms::). ---------- Footnotes ---------- (1) This definition of "environment" is specifically not intended to include all the data that can affect the result of a program.  File: elisp, Node: Forms, Next: Quoting, Prev: Intro Eval, Up: Evaluation Kinds of Forms ============== A Lisp object that is intended to be evaluated is called a "form". How Emacs evaluates a form depends on its data type. Emacs has three different kinds of form that are evaluated differently: symbols, lists, and "all other types". This section describes all three kinds, one by one, starting with the "all other types" which are self-evaluating forms. * Menu: * Self-Evaluating Forms:: Forms that evaluate to themselves. * Symbol Forms:: Symbols evaluate as variables. * Classifying Lists:: How to distinguish various sorts of list forms. * Function Indirection:: When a symbol appears as the car of a list, we find the real function via the symbol. * Function Forms:: Forms that call functions. * Macro Forms:: Forms that call macros. * Special Forms:: ``Special forms'' are idiosyncratic primitives, most of them extremely important. * Autoloading:: Functions set up to load files containing their real definitions.  File: elisp, Node: Self-Evaluating Forms, Next: Symbol Forms, Up: Forms Self-Evaluating Forms --------------------- A "self-evaluating form" is any form that is not a list or symbol. Self-evaluating forms evaluate to themselves: the result of evaluation is the same object that was evaluated. Thus, the number 25 evaluates to 25, and the string `"foo"' evaluates to the string `"foo"'. Likewise, evaluation of a vector does not cause evaluation of the elements of the vector--it returns the same vector with its contents unchanged. '123 ; A number, shown without evaluation. => 123 123 ; Evaluated as usual--result is the same. => 123 (eval '123) ; Evaluated "by hand"--result is the same. => 123 (eval (eval '123)) ; Evaluating twice changes nothing. => 123 It is common to write numbers, characters, strings, and even vectors in Lisp code, taking advantage of the fact that they self-evaluate. However, it is quite unusual to do this for types that lack a read syntax, because there's no way to write them textually. It is possible to construct Lisp expressions containing these types by means of a Lisp program. Here is an example: ;; Build an expression containing a buffer object. (setq print-exp (list 'print (current-buffer))) => (print #) ;; Evaluate it. (eval print-exp) -| # => #  File: elisp, Node: Symbol Forms, Next: Classifying Lists, Prev: Self-Evaluating Forms, Up: Forms Symbol Forms ------------ When a symbol is evaluated, it is treated as a variable. The result is the variable's value, if it has one. If it has none (if its value cell is void), an error is signaled. For more information on the use of variables, see *Note Variables::. In the following example, we set the value of a symbol with `setq'. Then we evaluate the symbol, and get back the value that `setq' stored. (setq a 123) => 123 (eval 'a) => 123 a => 123 The symbols `nil' and `t' are treated specially, so that the value of `nil' is always `nil', and the value of `t' is always `t'; you cannot set or bind them to any other values. Thus, these two symbols act like self-evaluating forms, even though `eval' treats them like any other symbol. A symbol whose name starts with `:' also self-evaluates in the same way; likewise, its value ordinarily cannot be changed. *Note Constant Variables::.  File: elisp, Node: Classifying Lists, Next: Function Indirection, Prev: Symbol Forms, Up: Forms Classification of List Forms ---------------------------- A form that is a nonempty list is either a function call, a macro call, or a special form, according to its first element. These three kinds of forms are evaluated in different ways, described below. The remaining list elements constitute the "arguments" for the function, macro, or special form. The first step in evaluating a nonempty list is to examine its first element. This element alone determines what kind of form the list is and how the rest of the list is to be processed. The first element is _not_ evaluated, as it would be in some Lisp dialects such as Scheme.  File: elisp, Node: Function Indirection, Next: Function Forms, Prev: Classifying Lists, Up: Forms Symbol Function Indirection --------------------------- If the first element of the list is a symbol then evaluation examines the symbol's function cell, and uses its contents instead of the original symbol. If the contents are another symbol, this process, called "symbol function indirection", is repeated until it obtains a non-symbol. *Note Function Names::, for more information about using a symbol as a name for a function stored in the function cell of the symbol. One possible consequence of this process is an infinite loop, in the event that a symbol's function cell refers to the same symbol. Or a symbol may have a void function cell, in which case the subroutine `symbol-function' signals a `void-function' error. But if neither of these things happens, we eventually obtain a non-symbol, which ought to be a function or other suitable object. More precisely, we should now have a Lisp function (a lambda expression), a byte-code function, a primitive function, a Lisp macro, a special form, or an autoload object. Each of these types is a case described in one of the following sections. If the object is not one of these types, the error `invalid-function' is signaled. The following example illustrates the symbol indirection process. We use `fset' to set the function cell of a symbol and `symbol-function' to get the function cell contents (*note Function Cells::). Specifically, we store the symbol `car' into the function cell of `first', and the symbol `first' into the function cell of `erste'. ;; Build this function cell linkage: ;; ------------- ----- ------- ------- ;; | # | <-- | car | <-- | first | <-- | erste | ;; ------------- ----- ------- ------- (symbol-function 'car) => # (fset 'first 'car) => car (fset 'erste 'first) => first (erste '(1 2 3)) ; Call the function referenced by `erste'. => 1 By contrast, the following example calls a function without any symbol function indirection, because the first element is an anonymous Lisp function, not a symbol. ((lambda (arg) (erste arg)) '(1 2 3)) => 1 Executing the function itself evaluates its body; this does involve symbol function indirection when calling `erste'. The built-in function `indirect-function' provides an easy way to perform symbol function indirection explicitly. - Function: indirect-function function This function returns the meaning of FUNCTION as a function. If FUNCTION is a symbol, then it finds FUNCTION's function definition and starts over with that value. If FUNCTION is not a symbol, then it returns FUNCTION itself. Here is how you could define `indirect-function' in Lisp: (defun indirect-function (function) (if (symbolp function) (indirect-function (symbol-function function)) function))  File: elisp, Node: Function Forms, Next: Macro Forms, Prev: Function Indirection, Up: Forms Evaluation of Function Forms ---------------------------- If the first element of a list being evaluated is a Lisp function object, byte-code object or primitive function object, then that list is a "function call". For example, here is a call to the function `+': (+ 1 x) The first step in evaluating a function call is to evaluate the remaining elements of the list from left to right. The results are the actual argument values, one value for each list element. The next step is to call the function with this list of arguments, effectively using the function `apply' (*note Calling Functions::). If the function is written in Lisp, the arguments are used to bind the argument variables of the function (*note Lambda Expressions::); then the forms in the function body are evaluated in order, and the value of the last body form becomes the value of the function call.  File: elisp, Node: Macro Forms, Next: Special Forms, Prev: Function Forms, Up: Forms Lisp Macro Evaluation --------------------- If the first element of a list being evaluated is a macro object, then the list is a "macro call". When a macro call is evaluated, the elements of the rest of the list are _not_ initially evaluated. Instead, these elements themselves are used as the arguments of the macro. The macro definition computes a replacement form, called the "expansion" of the macro, to be evaluated in place of the original form. The expansion may be any sort of form: a self-evaluating constant, a symbol, or a list. If the expansion is itself a macro call, this process of expansion repeats until some other sort of form results. Ordinary evaluation of a macro call finishes by evaluating the expansion. However, the macro expansion is not necessarily evaluated right away, or at all, because other programs also expand macro calls, and they may or may not evaluate the expansions. Normally, the argument expressions are not evaluated as part of computing the macro expansion, but instead appear as part of the expansion, so they are computed when the expansion is evaluated. For example, given a macro defined as follows: (defmacro cadr (x) (list 'car (list 'cdr x))) an expression such as `(cadr (assq 'handler list))' is a macro call, and its expansion is: (car (cdr (assq 'handler list))) Note that the argument `(assq 'handler list)' appears in the expansion. *Note Macros::, for a complete description of Emacs Lisp macros.  File: elisp, Node: Special Forms, Next: Autoloading, Prev: Macro Forms, Up: Forms Special Forms ------------- A "special form" is a primitive function specially marked so that its arguments are not all evaluated. Most special forms define control structures or perform variable bindings--things which functions cannot do. Each special form has its own rules for which arguments are evaluated and which are used without evaluation. Whether a particular argument is evaluated may depend on the results of evaluating other arguments. Here is a list, in alphabetical order, of all of the special forms in Emacs Lisp with a reference to where each is described. `and' *note Combining Conditions:: `catch' *note Catch and Throw:: `cond' *note Conditionals:: `condition-case' *note Handling Errors:: `defconst' *note Defining Variables:: `defmacro' *note Defining Macros:: `defun' *note Defining Functions:: `defvar' *note Defining Variables:: `function' *note Anonymous Functions:: `if' *note Conditionals:: `interactive' *note Interactive Call:: `let' `let*' *note Local Variables:: `or' *note Combining Conditions:: `prog1' `prog2' `progn' *note Sequencing:: `quote' *note Quoting:: `save-current-buffer' *note Current Buffer:: `save-excursion' *note Excursions:: `save-restriction' *note Narrowing:: `save-window-excursion' *note Window Configurations:: `setq' *note Setting Variables:: `setq-default' *note Creating Buffer-Local:: `track-mouse' *note Mouse Tracking:: `unwind-protect' *note Nonlocal Exits:: `while' *note Iteration:: `with-output-to-temp-buffer' *note Temporary Displays:: Common Lisp note: Here are some comparisons of special forms in GNU Emacs Lisp and Common Lisp. `setq', `if', and `catch' are special forms in both Emacs Lisp and Common Lisp. `defun' is a special form in Emacs Lisp, but a macro in Common Lisp. `save-excursion' is a special form in Emacs Lisp, but doesn't exist in Common Lisp. `throw' is a special form in Common Lisp (because it must be able to throw multiple values), but it is a function in Emacs Lisp (which doesn't have multiple values).  File: elisp, Node: Autoloading, Prev: Special Forms, Up: Forms Autoloading ----------- The "autoload" feature allows you to call a function or macro whose function definition has not yet been loaded into Emacs. It specifies which file contains the definition. When an autoload object appears as a symbol's function definition, calling that symbol as a function automatically loads the specified file; then it calls the real definition loaded from that file. *Note Autoload::.  File: elisp, Node: Quoting, Next: Eval, Prev: Forms, Up: Evaluation Quoting ======= The special form `quote' returns its single argument, as written, without evaluating it. This provides a way to include constant symbols and lists, which are not self-evaluating objects, in a program. (It is not necessary to quote self-evaluating objects such as numbers, strings, and vectors.) - Special Form: quote object This special form returns OBJECT, without evaluating it. Because `quote' is used so often in programs, Lisp provides a convenient read syntax for it. An apostrophe character (`'') followed by a Lisp object (in read syntax) expands to a list whose first element is `quote', and whose second element is the object. Thus, the read syntax `'x' is an abbreviation for `(quote x)'. Here are some examples of expressions that use `quote': (quote (+ 1 2)) => (+ 1 2) (quote foo) => foo 'foo => foo ''foo => (quote foo) '(quote foo) => (quote foo) ['foo] => [(quote foo)] Other quoting constructs include `function' (*note Anonymous Functions::), which causes an anonymous lambda expression written in Lisp to be compiled, and ``' (*note Backquote::), which is used to quote only part of a list, while computing and substituting other parts.  File: elisp, Node: Eval, Prev: Quoting, Up: Evaluation Eval ==== Most often, forms are evaluated automatically, by virtue of their occurrence in a program being run. On rare occasions, you may need to write code that evaluates a form that is computed at run time, such as after reading a form from text being edited or getting one from a property list. On these occasions, use the `eval' function. The functions and variables described in this section evaluate forms, specify limits to the evaluation process, or record recently returned values. Loading a file also does evaluation (*note Loading::). *Note:* it is generally cleaner and more flexible to store a function in a data structure, and call it with `funcall' or `apply', than to store an expression in the data structure and evaluate it. Using functions provides the ability to pass information to them as arguments. - Function: eval form This is the basic function evaluating an expression. It evaluates FORM in the current environment and returns the result. How the evaluation proceeds depends on the type of the object (*note Forms::). Since `eval' is a function, the argument expression that appears in a call to `eval' is evaluated twice: once as preparation before `eval' is called, and again by the `eval' function itself. Here is an example: (setq foo 'bar) => bar (setq bar 'baz) => baz ;; Here `eval' receives argument `foo' (eval 'foo) => bar ;; Here `eval' receives argument `bar', which is the value of `foo' (eval foo) => baz The number of currently active calls to `eval' is limited to `max-lisp-eval-depth' (see below). - Command: eval-region start end &optional stream read-function This function evaluates the forms in the current buffer in the region defined by the positions START and END. It reads forms from the region and calls `eval' on them until the end of the region is reached, or until an error is signaled and not handled. If STREAM is non-`nil', the values that result from evaluating the expressions in the region are printed using STREAM. *Note Output Streams::. If READ-FUNCTION is non-`nil', it should be a function, which is used instead of `read' to read expressions one by one. This function is called with one argument, the stream for reading input. You can also use the variable `load-read-function' (*note How Programs Do Loading::) to specify this function, but it is more robust to use the READ-FUNCTION argument. `eval-region' always returns `nil'. - Command: eval-current-buffer &optional stream This is like `eval-region' except that it operates on the whole buffer. - Variable: max-lisp-eval-depth This variable defines the maximum depth allowed in calls to `eval', `apply', and `funcall' before an error is signaled (with error message `"Lisp nesting exceeds max-lisp-eval-depth"'). This limit, with the associated error when it is exceeded, is one way that Lisp avoids infinite recursion on an ill-defined function. The depth limit counts internal uses of `eval', `apply', and `funcall', such as for calling the functions mentioned in Lisp expressions, and recursive evaluation of function call arguments and function body forms, as well as explicit calls in Lisp code. The default value of this variable is 300. If you set it to a value less than 100, Lisp will reset it to 100 if the given value is reached. Entry to the Lisp debugger increases the value, if there is little room left, to make sure the debugger itself has room to execute. `max-specpdl-size' provides another limit on nesting. *Note Local Variables::. - Variable: values The value of this variable is a list of the values returned by all the expressions that were read, evaluated, and printed from buffers (including the minibuffer) by the standard Emacs commands which do this. The elements are ordered most recent first. (setq x 1) => 1 (list 'A (1+ 2) auto-save-default) => (A 3 t) values => ((A 3 t) 1 ...) This variable is useful for referring back to values of forms recently evaluated. It is generally a bad idea to print the value of `values' itself, since this may be very long. Instead, examine particular elements, like this: ;; Refer to the most recent evaluation result. (nth 0 values) => (A 3 t) ;; That put a new element on, ;; so all elements move back one. (nth 1 values) => (A 3 t) ;; This gets the element that was next-to-most-recent ;; before this example. (nth 3 values) => 1  File: elisp, Node: Control Structures, Next: Variables, Prev: Evaluation, Up: Top Control Structures ****************** A Lisp program consists of expressions or "forms" (*note Forms::). We control the order of execution of these forms by enclosing them in "control structures". Control structures are special forms which control when, whether, or how many times to execute the forms they contain. The simplest order of execution is sequential execution: first form A, then form B, and so on. This is what happens when you write several forms in succession in the body of a function, or at top level in a file of Lisp code--the forms are executed in the order written. We call this "textual order". For example, if a function body consists of two forms A and B, evaluation of the function evaluates first A and then B. The result of evaluating B becomes the value of the function. Explicit control structures make possible an order of execution other than sequential. Emacs Lisp provides several kinds of control structure, including other varieties of sequencing, conditionals, iteration, and (controlled) jumps--all discussed below. The built-in control structures are special forms since their subforms are not necessarily evaluated or not evaluated sequentially. You can use macros to define your own control structure constructs (*note Macros::). * Menu: * Sequencing:: Evaluation in textual order. * Conditionals:: `if', `cond', `when', `unless'. * Combining Conditions:: `and', `or', `not'. * Iteration:: `while' loops. * Nonlocal Exits:: Jumping out of a sequence.  File: elisp, Node: Sequencing, Next: Conditionals, Up: Control Structures Sequencing ========== Evaluating forms in the order they appear is the most common way control passes from one form to another. In some contexts, such as in a function body, this happens automatically. Elsewhere you must use a control structure construct to do this: `progn', the simplest control construct of Lisp. A `progn' special form looks like this: (progn A B C ...) and it says to execute the forms A, B, C, and so on, in that order. These forms are called the "body" of the `progn' form. The value of the last form in the body becomes the value of the entire `progn'. `(progn)' returns `nil'. In the early days of Lisp, `progn' was the only way to execute two or more forms in succession and use the value of the last of them. But programmers found they often needed to use a `progn' in the body of a function, where (at that time) only one form was allowed. So the body of a function was made into an "implicit `progn'": several forms are allowed just as in the body of an actual `progn'. Many other control structures likewise contain an implicit `progn'. As a result, `progn' is not used as much as it was many years ago. It is needed now most often inside an `unwind-protect', `and', `or', or in the THEN-part of an `if'. - Special Form: progn forms... This special form evaluates all of the FORMS, in textual order, returning the result of the final form. (progn (print "The first form") (print "The second form") (print "The third form")) -| "The first form" -| "The second form" -| "The third form" => "The third form" Two other control constructs likewise evaluate a series of forms but return a different value: - Special Form: prog1 form1 forms... This special form evaluates FORM1 and all of the FORMS, in textual order, returning the result of FORM1. (prog1 (print "The first form") (print "The second form") (print "The third form")) -| "The first form" -| "The second form" -| "The third form" => "The first form" Here is a way to remove the first element from a list in the variable `x', then return the value of that former element: (prog1 (car x) (setq x (cdr x))) - Special Form: prog2 form1 form2 forms... This special form evaluates FORM1, FORM2, and all of the following FORMS, in textual order, returning the result of FORM2. (prog2 (print "The first form") (print "The second form") (print "The third form")) -| "The first form" -| "The second form" -| "The third form" => "The second form"  File: elisp, Node: Conditionals, Next: Combining Conditions, Prev: Sequencing, Up: Control Structures Conditionals ============ Conditional control structures choose among alternatives. Emacs Lisp has four conditional forms: `if', which is much the same as in other languages; `when' and `unless', which are variants of `if'; and `cond', which is a generalized case statement. - Special Form: if condition then-form else-forms... `if' chooses between the THEN-FORM and the ELSE-FORMS based on the value of CONDITION. If the evaluated CONDITION is non-`nil', THEN-FORM is evaluated and the result returned. Otherwise, the ELSE-FORMS are evaluated in textual order, and the value of the last one is returned. (The ELSE part of `if' is an example of an implicit `progn'. *Note Sequencing::.) If CONDITION has the value `nil', and no ELSE-FORMS are given, `if' returns `nil'. `if' is a special form because the branch that is not selected is never evaluated--it is ignored. Thus, in the example below, `true' is not printed because `print' is never called. (if nil (print 'true) 'very-false) => very-false - Macro: when condition then-forms... This is a variant of `if' where there are no ELSE-FORMS, and possibly several THEN-FORMS. In particular, (when CONDITION A B C) is entirely equivalent to (if CONDITION (progn A B C) nil) - Macro: unless condition forms... This is a variant of `if' where there is no THEN-FORM: (unless CONDITION A B C) is entirely equivalent to (if CONDITION nil A B C) - Special Form: cond clause... `cond' chooses among an arbitrary number of alternatives. Each CLAUSE in the `cond' must be a list. The CAR of this list is the CONDITION; the remaining elements, if any, the BODY-FORMS. Thus, a clause looks like this: (CONDITION BODY-FORMS...) `cond' tries the clauses in textual order, by evaluating the CONDITION of each clause. If the value of CONDITION is non-`nil', the clause "succeeds"; then `cond' evaluates its BODY-FORMS, and the value of the last of BODY-FORMS becomes the value of the `cond'. The remaining clauses are ignored. If the value of CONDITION is `nil', the clause "fails", so the `cond' moves on to the following clause, trying its CONDITION. If every CONDITION evaluates to `nil', so that every clause fails, `cond' returns `nil'. A clause may also look like this: (CONDITION) Then, if CONDITION is non-`nil' when tested, the value of CONDITION becomes the value of the `cond' form. The following example has four clauses, which test for the cases where the value of `x' is a number, string, buffer and symbol, respectively: (cond ((numberp x) x) ((stringp x) x) ((bufferp x) (setq temporary-hack x) ; multiple body-forms (buffer-name x)) ; in one clause ((symbolp x) (symbol-value x))) Often we want to execute the last clause whenever none of the previous clauses was successful. To do this, we use `t' as the CONDITION of the last clause, like this: `(t BODY-FORMS)'. The form `t' evaluates to `t', which is never `nil', so this clause never fails, provided the `cond' gets to it at all. For example, (setq a 5) (cond ((eq a 'hack) 'foo) (t "default")) => "default" This `cond' expression returns `foo' if the value of `a' is `hack', and returns the string `"default"' otherwise. Any conditional construct can be expressed with `cond' or with `if'. Therefore, the choice between them is a matter of style. For example: (if A B C) == (cond (A B) (t C))  File: elisp, Node: Combining Conditions, Next: Iteration, Prev: Conditionals, Up: Control Structures Constructs for Combining Conditions =================================== This section describes three constructs that are often used together with `if' and `cond' to express complicated conditions. The constructs `and' and `or' can also be used individually as kinds of multiple conditional constructs. - Function: not condition This function tests for the falsehood of CONDITION. It returns `t' if CONDITION is `nil', and `nil' otherwise. The function `not' is identical to `null', and we recommend using the name `null' if you are testing for an empty list. - Special Form: and conditions... The `and' special form tests whether all the CONDITIONS are true. It works by evaluating the CONDITIONS one by one in the order written. If any of the CONDITIONS evaluates to `nil', then the result of the `and' must be `nil' regardless of the remaining CONDITIONS; so `and' returns `nil' right away, ignoring the remaining CONDITIONS. If all the CONDITIONS turn out non-`nil', then the value of the last of them becomes the value of the `and' form. Just `(and)', with no CONDITIONS, returns `t', appropriate because all the CONDITIONS turned out non-`nil'. (Think about it; which one did not?) Here is an example. The first condition returns the integer 1, which is not `nil'. Similarly, the second condition returns the integer 2, which is not `nil'. The third condition is `nil', so the remaining condition is never evaluated. (and (print 1) (print 2) nil (print 3)) -| 1 -| 2 => nil Here is a more realistic example of using `and': (if (and (consp foo) (eq (car foo) 'x)) (message "foo is a list starting with x")) Note that `(car foo)' is not executed if `(consp foo)' returns `nil', thus avoiding an error. `and' can be expressed in terms of either `if' or `cond'. For example: (and ARG1 ARG2 ARG3) == (if ARG1 (if ARG2 ARG3)) == (cond (ARG1 (cond (ARG2 ARG3)))) - Special Form: or conditions... The `or' special form tests whether at least one of the CONDITIONS is true. It works by evaluating all the CONDITIONS one by one in the order written. If any of the CONDITIONS evaluates to a non-`nil' value, then the result of the `or' must be non-`nil'; so `or' returns right away, ignoring the remaining CONDITIONS. The value it returns is the non-`nil' value of the condition just evaluated. If all the CONDITIONS turn out `nil', then the `or' expression returns `nil'. Just `(or)', with no CONDITIONS, returns `nil', appropriate because all the CONDITIONS turned out `nil'. (Think about it; which one did not?) For example, this expression tests whether `x' is either `nil' or the integer zero: (or (eq x nil) (eq x 0)) Like the `and' construct, `or' can be written in terms of `cond'. For example: (or ARG1 ARG2 ARG3) == (cond (ARG1) (ARG2) (ARG3)) You could almost write `or' in terms of `if', but not quite: (if ARG1 ARG1 (if ARG2 ARG2 ARG3)) This is not completely equivalent because it can evaluate ARG1 or ARG2 twice. By contrast, `(or ARG1 ARG2 ARG3)' never evaluates any argument more than once.  File: elisp, Node: Iteration, Next: Nonlocal Exits, Prev: Combining Conditions, Up: Control Structures Iteration ========= Iteration means executing part of a program repetitively. For example, you might want to repeat some computation once for each element of a list, or once for each integer from 0 to N. You can do this in Emacs Lisp with the special form `while': - Special Form: while condition forms... `while' first evaluates CONDITION. If the result is non-`nil', it evaluates FORMS in textual order. Then it reevaluates CONDITION, and if the result is non-`nil', it evaluates FORMS again. This process repeats until CONDITION evaluates to `nil'. There is no limit on the number of iterations that may occur. The loop will continue until either CONDITION evaluates to `nil' or until an error or `throw' jumps out of it (*note Nonlocal Exits::). The value of a `while' form is always `nil'. (setq num 0) => 0 (while (< num 4) (princ (format "Iteration %d." num)) (setq num (1+ num))) -| Iteration 0. -| Iteration 1. -| Iteration 2. -| Iteration 3. => nil To write a "repeat...until" loop, which will execute something on each iteration and then do the end-test, put the body followed by the end-test in a `progn' as the first argument of `while', as shown here: (while (progn (forward-line 1) (not (looking-at "^$")))) This moves forward one line and continues moving by lines until it reaches an empty line. It is peculiar in that the `while' has no body, just the end test (which also does the real work of moving point). The `dolist' and `dotimes' macros provide convenient ways to write two common kinds of loops. - Macro: dolist (var list [result]) body... This construct executes BODY once for each element of LIST, using the variable VAR to hold the current element. Then it returns the value of evaluating RESULT, or `nil' if RESULT is omitted. For example, here is how you could use `dolist' to define the `reverse' function: (defun reverse (list) (let (value) (dolist (elt list value) (setq value (cons elt value))))) - Macro: dotimes (var count [result]) body... This construct executes BODY once for each integer from 0 (inclusive) to COUNT (exclusive), using the variable VAR to hold the integer for the current iteration. Then it returns the value of evaluating RESULT, or `nil' if RESULT is omitted. Here is an example of using `dotimes' do something 100 times: (dotimes (i 100) (insert "I will not obey absurd orders\n"))  File: elisp, Node: Nonlocal Exits, Prev: Iteration, Up: Control Structures Nonlocal Exits ============== A "nonlocal exit" is a transfer of control from one point in a program to another remote point. Nonlocal exits can occur in Emacs Lisp as a result of errors; you can also use them under explicit control. Nonlocal exits unbind all variable bindings made by the constructs being exited. * Menu: * Catch and Throw:: Nonlocal exits for the program's own purposes. * Examples of Catch:: Showing how such nonlocal exits can be written. * Errors:: How errors are signaled and handled. * Cleanups:: Arranging to run a cleanup form if an error happens.  File: elisp, Node: Catch and Throw, Next: Examples of Catch, Up: Nonlocal Exits Explicit Nonlocal Exits: `catch' and `throw' -------------------------------------------- Most control constructs affect only the flow of control within the construct itself. The function `throw' is the exception to this rule of normal program execution: it performs a nonlocal exit on request. (There are other exceptions, but they are for error handling only.) `throw' is used inside a `catch', and jumps back to that `catch'. For example: (defun foo-outer () (catch 'foo (foo-inner))) (defun foo-inner () ... (if x (throw 'foo t)) ...) The `throw' form, if executed, transfers control straight back to the corresponding `catch', which returns immediately. The code following the `throw' is not executed. The second argument of `throw' is used as the return value of the `catch'. The function `throw' finds the matching `catch' based on the first argument: it searches for a `catch' whose first argument is `eq' to the one specified in the `throw'. If there is more than one applicable `catch', the innermost one takes precedence. Thus, in the above example, the `throw' specifies `foo', and the `catch' in `foo-outer' specifies the same symbol, so that `catch' is the applicable one (assuming there is no other matching `catch' in between). Executing `throw' exits all Lisp constructs up to the matching `catch', including function calls. When binding constructs such as `let' or function calls are exited in this way, the bindings are unbound, just as they are when these constructs exit normally (*note Local Variables::). Likewise, `throw' restores the buffer and position saved by `save-excursion' (*note Excursions::), and the narrowing status saved by `save-restriction' and the window selection saved by `save-window-excursion' (*note Window Configurations::). It also runs any cleanups established with the `unwind-protect' special form when it exits that form (*note Cleanups::). The `throw' need not appear lexically within the `catch' that it jumps to. It can equally well be called from another function called within the `catch'. As long as the `throw' takes place chronologically after entry to the `catch', and chronologically before exit from it, it has access to that `catch'. This is why `throw' can be used in commands such as `exit-recursive-edit' that throw back to the editor command loop (*note Recursive Editing::). Common Lisp note: Most other versions of Lisp, including Common Lisp, have several ways of transferring control nonsequentially: `return', `return-from', and `go', for example. Emacs Lisp has only `throw'. - Special Form: catch tag body... `catch' establishes a return point for the `throw' function. The return point is distinguished from other such return points by TAG, which may be any Lisp object except `nil'. The argument TAG is evaluated normally before the return point is established. With the return point in effect, `catch' evaluates the forms of the BODY in textual order. If the forms execute normally (without error or nonlocal exit) the value of the last body form is returned from the `catch'. If a `throw' is executed during the execution of BODY, specifying the same value TAG, the `catch' form exits immediately; the value it returns is whatever was specified as the second argument of `throw'. - Function: throw tag value The purpose of `throw' is to return from a return point previously established with `catch'. The argument TAG is used to choose among the various existing return points; it must be `eq' to the value specified in the `catch'. If multiple return points match TAG, the innermost one is used. The argument VALUE is used as the value to return from that `catch'. If no return point is in effect with tag TAG, then a `no-catch' error is signaled with data `(TAG VALUE)'.  File: elisp, Node: Examples of Catch, Next: Errors, Prev: Catch and Throw, Up: Nonlocal Exits Examples of `catch' and `throw' ------------------------------- One way to use `catch' and `throw' is to exit from a doubly nested loop. (In most languages, this would be done with a "go to".) Here we compute `(foo I J)' for I and J varying from 0 to 9: (defun search-foo () (catch 'loop (let ((i 0)) (while (< i 10) (let ((j 0)) (while (< j 10) (if (foo i j) (throw 'loop (list i j))) (setq j (1+ j)))) (setq i (1+ i)))))) If `foo' ever returns non-`nil', we stop immediately and return a list of I and J. If `foo' always returns `nil', the `catch' returns normally, and the value is `nil', since that is the result of the `while'. Here are two tricky examples, slightly different, showing two return points at once. First, two return points with the same tag, `hack': (defun catch2 (tag) (catch tag (throw 'hack 'yes))) => catch2 (catch 'hack (print (catch2 'hack)) 'no) -| yes => no Since both return points have tags that match the `throw', it goes to the inner one, the one established in `catch2'. Therefore, `catch2' returns normally with value `yes', and this value is printed. Finally the second body form in the outer `catch', which is `'no', is evaluated and returned from the outer `catch'. Now let's change the argument given to `catch2': (catch 'hack (print (catch2 'quux)) 'no) => yes We still have two return points, but this time only the outer one has the tag `hack'; the inner one has the tag `quux' instead. Therefore, `throw' makes the outer `catch' return the value `yes'. The function `print' is never called, and the body-form `'no' is never evaluated.