14. Evaluation

The evaluation of expressions in SXEmacs 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.

14.1 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. See section 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. See section 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. See section Functions and Commands. 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 (see section 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.(2) Whenever the form refers to a variable without creating a new binding for it, the value of the binding in the current environment is used. See section Variables.

Evaluation of a form may create new environments for recursive evaluation by binding variables (see section 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 (see section Kinds of Forms).

14.2 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.

Please note: it is generally cleaner and more flexible to call functions that are stored in data structures, rather than to evaluate expressions stored in data structures. Using functions provides the ability to pass information to them as arguments.

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 (see section Loading).

Function: eval form

This is the basic function for performing evaluation. It evaluates form in the current environment and returns the result. How the evaluation proceeds depends on the type of the object (see section Kinds of 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 ;; eval receives argument bar, which is the value of foo (eval foo) ⇒ baz (eval 'foo) ⇒ bar

The number of currently active calls to eval is limited to max-lisp-eval-depth (see below).

Command: eval-region start end &optional stream

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 supplied, standard-output is bound to it during the evaluation.

You can use the variable load-read-function to specify a function for eval-region to use instead of read for reading expressions. See section How Programs Do Loading.

eval-region always returns nil.

Command: eval-buffer buffer &optional stream

This is like eval-region except that it operates on the whole contents of 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 counts internal uses of those functions, such as for calling the functions mentioned in Lisp expressions, and recursive evaluation of function call arguments and function body forms.

This limit, with the associated error when it is exceeded, is one way that Lisp avoids infinite recursion on an ill-defined function.

The default value of this variable is 1000. If you set it to a value less than 100, Lisp will reset it to 100 if the given value is reached.

max-specpdl-size provides another limit on nesting. See section Local Variables.

Variable: values

The value of this variable is a list of the values returned by all the expressions that were read from buffers (including the minibuffer), evaluated, and printed. 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

14.3 Kinds of Forms

A Lisp object that is intended to be evaluated is called a form. How SXEmacs evaluates a form depends on its data type. SXEmacs has three different kinds of form that are evaluated differently: symbols, lists, and "all other types". This section describes all three kinds, starting with "all other types" which are self-evaluating forms.

14.3.1 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               ; An object, 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 buffer (list 'print (current-buffer)))
     ⇒ (print #<buffer eval.texi>)
;; Evaluate it.
(eval buffer)
     -| #<buffer eval.texi>
     ⇒ #<buffer eval.texi>

14.3.2 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 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.

14.3.3 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.

14.3.4 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. See section Naming a Function, 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 (see section Accessing Function Cell Contents). 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:
;;   -------------       -----        -------        -------
;;  | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
;;   -------------       -----        -------        -------

(symbol-function 'car)
     ⇒ #<subr 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 object

This function returns the meaning of object as a function. If object is a symbol, then it finds object's function definition and starts over with that value. If object is not a symbol, then it returns object itself.

Here is how you could define indirect-function in Lisp:

(defun indirect-function (function) (if (symbolp function) (indirect-function (symbol-function function)) function))

14.3.5 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 (see section Calling Functions).

If the function is written in Lisp, the arguments are used to bind the argument variables of the function (see section 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.

14.3.6 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 computed.

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: The argument (assq 'handler list) appears in the expansion.

See section Macros, for a complete description of SXEmacs Lisp macros.

14.3.7 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 SXEmacs Lisp with a reference to where each is described.

and

see section Constructs for Combining Conditions

catch

see section Explicit Nonlocal Exits: catch and throw

cond

see section Conditionals

condition-case

see section Writing Code to Handle Errors

defconst

see section Defining Global Variables

defmacro

see section Defining Macros

defun

see section Defining Functions

defvar

see section Defining Global Variables

function

see section Anonymous Functions

if

see section Conditionals

interactive

see section Interactive Call

let

let*

see section Local Variables

or

see section Constructs for Combining Conditions

prog1

prog2

progn

see section Sequencing

quote

see section Quoting

save-current-buffer

see section Excursions

save-excursion

see section Excursions

save-restriction

see section Narrowing

save-selected-window

see section Excursions

save-window-excursion

see section Window Configurations

setq

see section How to Alter a Variable Value

setq-default

see section Creating and Deleting Buffer-Local Bindings

unwind-protect

see section Nonlocal Exits

while

see section Iteration

with-output-to-temp-buffer

see section Temporary Displays

Common Lisp note: here are some comparisons of special forms in SXEmacs Lisp and Common Lisp. setq, if, and catch are special forms in both SXEmacs Lisp and Common Lisp. defun is a special form in SXEmacs Lisp, but a macro in Common Lisp. save-excursion is a special form in SXEmacs Lisp, but does not 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 SXEmacs Lisp (which doesn't have multiple values).

14.3.8 Autoloading

The autoload feature allows you to call a function or macro whose function definition has not yet been loaded into SXEmacs. 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. See section Autoload.

14.4 Quoting

Quoting is a technique to modify the evaluation behaviour of expressions. This is achieved by wrapping the expression into a special form. The lisp reader will now evualate this special form instead of the original expression.

SXEmacs basically knows about 3 quoting forms: quote, function and backquote. Moreover, all of these possess an alternative read syntax, ', #' and ` respectively. In programs you will find almost exclusively the abbreviated variants which also facilitate human reading of program sources. You can test yourself in the example section below.

14.4.1 Quoting with quote

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)]

Numeric constants, indefinite symbols, string constants, character constants and the special forms t and nil evaluate themselves. Quoting them is allowed but optional. Vector constants created with the bracket notation ([ ]) are also immune against quoting. See section Self-Evaluating Forms.

'12
  ⇒ 12
'2.333
  ⇒ 2.333
'1/2
  ⇒ 1/2
'2+5Z
  ⇒ 2+5Z
'Z/12Z
  ⇒ Z/12Z
'1+2i
  ⇒ 1+2i
'0.5-0.5i
  ⇒ 0.50000-0.50000i

'+infinity
  ⇒ +infinity
'-infinity
  ⇒ -infinity
'complex-infinity
  ⇒ complex-infinity
'not-a-number
  ⇒ not-a-number

'"string"
  ⇒ "string"
(eval ''#r"\a\b\c")
  ⇒ "\\a\\b\\c"

'?a
  ⇒ ?a
'?'
  ⇒ ?\'

't
  ⇒ t
'nil
  ⇒ nil

[a b c]
  ⇒ [a b c]
'[a b c]
  ⇒ [a b c]

14.4.2 Quoting with function

The special form function returns its single argument, as written, without evaluating it, and indicates thereby that this argument is to be treated as function. This is mandatory only if you intend to compile your program and want the byte-compiler to optimise your code accordingly. Any other lisp code will accept both the ordinarily quoted and the function-quoted form. Because of this SXEmacs does allow you to evaluate the value cell of a function-quoted object. However, this is bad style and may lead to problems in case of byte-compilation.

Special Form: function function-object

This special form returns function-object without evaluating it. In this, it is equivalent to quote. However, it serves as a note to the SXEmacs Lisp compiler that function-object is intended to be used only as a function, and therefore can safely be compiled. Contrast this with quote, in Quoting with quote.

As for quote, there is also an abbreviated read syntax for function. A sharpsign character followed by an apostrophe (`#'') followed by a a Lisp object in read syntax expands to a list whose first element is function, and whose second element is the object. Thus, the read syntax #'y is an abbreviation for (function y).

This effect can be used in macros to distinguish explicitly between variable and function bindings, see example below, also see section Macros. However, since the rest of SXEmacs accepts both the quoted and the function-quoted form equally and coerces them to the desired form internally, macros or functions which diverge from this norm should contain a clear remark in their docstring.

Here are some examples of expressions that use function:

(function car)
  ⇒ car
#'car
  ⇒ car
'#'car
  => (function car)
(symbol-function #'funcall)
  ⇒ #<subr funcall>
(symbol-value #'nil)
  ⇒ nil

As mentioned above, an example for a macro which distinguishes between `'' and `#''.

(defmacro picky-funcall (symbol &rest arguments)
  (let ((type (car-safe symbol))
        (name (car (cdr-safe symbol)))
        (qargs (list 'quote arguments)))
    (cond ((eq type 'function)
           (list 'apply symbol qargs))
          ((eq type 'quote)
           (list 'apply name qargs))
          (t
           (error "I don't know what to do with `%s'." symbol)))))

Now we define both a function with the name `test' and a variable with the name `test'. Afterwards we apply each to our picky-funcall.

(defun test (a b)
  (+ a b))
  ⇒ test
(defvar test '-)
  ⇒ test

(picky-funcall #'test 4 2)
  ⇒ 6
(picky-funcall 'test 4 2)
  ⇒ 2

(picky-funcall test 4 2)
error--> Cannot decide if `test' contains a variable or function.

Again, the behaviour of picky-funcall is unusual in SXEmacs, you should try to avoid it wherever you can. In contrast, quoting functions with `#'' (or the function form) is usual and even recommended because it clarifies your intention to both human readers and the lisp expression reader.

Also note, in a function definition you have no definite chance to distinguish between any of the quoting forms. This would revert function indirection anyway. However, if you intend to treat variables different from functions you could try to guess using symbol-name, symbol-function and symbol-value (see section Symbols).

As for quoting, self-evaluating forms are not affected by function quotation. However, function quoting such forms is most likely wrong anyway so we will not give examples here.

Nonetheless there is a macro definition to turn lambda-lists (see section Anonymous Functions) into self-evaluating objects.

(lambda (x) (+ x x))
  ⇒ (lambda (x) (+ x x))

The true expansion of (lambda …) is (function (lambda …)).

14.4.3 Quoting with ` (backquote)

While ' quotes its expression completely it is very complicated to quote, say, a list of several elements but leave one element unquoted (i.e. evaluate it). The result would probably look like:

(setq e 5)
(list 'a 'b 'c 'd e 'e 'e 'e)
  ⇒ (a b c d 5 e e e)

In this sense, a backquote is somewhat the reverse operation of a `''. Backquote allows you to quote the entire list, but selectively evaluate elements of that list. However, in the simplest case, it is identical to quote. These two forms yield identical results:

`(a list of (+ 2 3) elements)
  ⇒ (a list of (+ 2 3) elements)
'(a list of (+ 2 3) elements)
  ⇒ (a list of (+ 2 3) elements)

However, unlike quote which has a special read-syntax, backquoting is implemented as macro and the routines backquote and ` do not coincide.

The `,' marker

The special marker `,' can be used inside of the argument to inhibit the quotation for this particular expression. Thus the backquote alternative of the motivation example above could be:

(setq e 10)
`(a b c d ,e e e e)
  ⇒ (a b c d 10 e e e)

Please note, the comma is not treated specially by the lisp reader, thus it is a perfectly valid part of a symbol. If you want to protect against strange behaviour do not use a leading `,' in your variable or function names. In reality symbols with leading commas can be of great use in nested quoting constructions, see section Nested quoting. However, make sure that none of such bindings escapes to the normal lisp environment.

The `,@' marker

With the special marker `,@' inside of a backquoted expression you can splice an evaluated value into the resulting list. The elements of the spliced list become elements at the same level as the other elements of the resulting list. The equivalent code without using ``' is often unreadable.

Like the comma operator `,@' is not treated specially by the lisp reader either. You will have to take care for symbol names with leading `,@' in foreign (i.e. non-backquoting) contexts and their bindings yourself.

Let us now look at a more pragmatic example of backquoting.

(defun interior (function fix-arg)
  "Return the insertion of FIX-ARG in FUNCTION,
that is a function which is derived from FUNCTION by fixating the
first argument to FIX-ARG and keeping the rest variable.

This process is often referred to as currying.
Mathematically it is a special interior product (hence the name)."
  (let* ((body (indirect-function function))
         (args
          (cond ((subrp body)
                 (error "Error: Cannot handle built-in functions."))
                ((compiled-function-p body)
                 (compiled-function-arglist body))
                (t
                 (cadr body))))
         (newarglist
          (if args
              (cdr args)
            (error "Error: %s accepts no arguments." function)))
         (newargs
          (delq '&optional (copy-list newarglist))))
    `(lambda ,newarglist
       (,function ',fix-arg ,@newargs))))
  ⇒ interior

This definition is far from perfect but sufficient for our purposes. Since we excluded built-in functions in the above code we define a simple lisp equivalent of the list function.

(defun list-demo (a b c d)
  "Return the list (A B C D)."
  (list a b c d))
  ⇒ list-demo

(list-demo 1 'a 2 t)
  ⇒ (1 a 2 t)

Now we look at the interior product of `?a' and list-demo.

(interior #'list-demo ?a)
  ⇒ (lambda (b c d) (list-demo (quote ?a) b c d))

As you can see, ,function and ,fix-arg have been replaced with the according argument passed to interior. Additionally we quote the replace of ,fix-arg to prevent another expansion of the replacement during the call of the resulting function. Also note how the list in newargs which had the local binding `(b c d)' within interior has been spliced into the function call expression.

(fset #'list-demo-a (interior #'list-demo ?a))
  ⇒ (lambda (b c d) (list-demo (quote ?a) b c d))
(list-demo-a 'and 3 'args)
  => (?a and 3 args)

Now let's have a glance at a prominent annoyance. The function argument of the mapcar function is passed exactly one argument (an element of the given list). Sometimes it is wishful to map a two-argument function whose first argument is constant during the mapping anyway. In this scenario our interior comes in very handy.

(defvar demo-hook nil)
  => demo-hook
(mapcar (interior #'add-hook 'demo-hook) '(first-fun another-fun))
  ⇒ ((first-fun) (another-fun first-fun))
demo-hook
  ⇒ (another-fun first-fun)

The `,.' marker

Instead of the splicing operator `,@' which internally uses append to splice an expression into the list at place, you can always use the destructive form `,.' instead which internally uses nconc. Refer to the documentation of nconc for more information, see section Functions that Rearrange Lists.

(setq test-list '(a b))
  ⇒ (a b)

`(,.test-list ,(+ 2 3))
  ⇒ (a b 5)
`(,.test-list ,(+ 3 4))
  ⇒ (a b 5 7)

test-list
  ⇒ (a b 5 7)

14.4.4 Nested quoting

Simple nested quotations have already been used throughout this section. Indeed, function quoting and symbol quoting may be used combined in order and any nesting level. Trying to quote of a self-evaluating or special form necessarily leads to double quoting it. Thus ''?a will become (quote ?a).

Furthermore, we have already seen that backquoting empowers us to create a mixture of quoted and evaluated parts of an expression. We shall now look at the various oddities which may arise particularly in nested quotation scenarios.

(setq y 'x
      x 'y)

`(,y `(,y ,@(+ 2 3)) ,@(+ 2 3))
  ⇒ (x (bq-list* y (+ 2 3)) . 5)

`(,y ,`(,y ,@(+ 2 3)) ,@(+ 2 3))
  => (x (x . 5) . 5)

`(,y ,'`(,y ,@(+ 2 3)) ,@(+ 2 3))
  ⇒ (x (backquote ((\, y) (\, (+ 2 3)))) . 5)

In the first example, you can behold the dequoting strategy of nested backquotes. Like other lisp implementations and dialects the nested structure is somewhat preserved. Substitutions are made only for dequoted (or marked as such) elements appearing at the same nesting level as the outermost backquote. But evaluation takes place at all nesting levels likewise. Inner backquote lists are evaluated but remain quoted within the outer backquote list unless these are marked themselves for dequoting and substitution. For your information, the bq-list* macro behaves like Common Lisp's list* form.

Evaluation of the inner expression yields:

(bq-list* y (+ 2 3))
  ⇒ (x . 5)

This evaluation explains the second example.

Sometimes it is useful to leave inner backquote lists entirely untouched, for example in macros which in turn define other macros which then use backquote lists in their definition. Example 3 demonstrates how this can be achieved.

Dequoting across nesting bounds

There is no definite concept (yet). You will achieve what you want if you carefully quote your expressions. Although you need to use the expanded names for `, ,, ,@ and ,..

(let ((y 'x)
      (x 'y))
  `(,y (,'backquote (,y  ,',y))))
  ⇒ (x (backquote (x (\, y))))

With growing nesting complexity list constructors may well be more flexible.

(let ((y 'x)
      (x 'y))
  (list y (list 'backquote (list y '(\, y)))))
  ⇒ (x (backquote (x (\, y))))

In the future we may provide a more comprehensible concept where the above scenario would simply read `(,y ``(,y ,,y)). On the other hand you can create your own solutions of backquotations using - better said abusing - the comma read-syntax. The idea is to locally make all variables self-evaluating and explicitly specify an expansion for commatised variables. To get this right, this is one method out of many and it it a matter of personal taste. The next (very) simple example merely demonstrates the idea and does not represent a concept nor a special elisp feature at all:

(let* ((x 'x)
       (y 'y)
       (,x 'top-level)
       (,y x)
       (,,x ,x)
       (,,y ,x))
  (list x y ,x ,y ,,x ,,y))

This document was generated by Steve Youngs on September, 23 2008 using texi2html 1.76.