Contents|Symbol Index|Prev: 4. Types and Classes|Next: 6. Iteration

5. Data and Control Flow

5.1 Generalized Reference#

Generalized Reference

Moon thinks terms "generalized reference" and "place" need to be rationalized throughout. Done! -kmp 16-Jul-93

5.1.1 Overview of Places and Generalized Reference#

A generalized reference is the use of a form, sometimes called a place, as if it were a variable that could be read and written. The value of a place is the object to which the place form evaluates. The value of a place can be changed by using setf. The concept of binding a place is not defined in Common Lisp, but an implementation is permitted to extend the language by defining this concept.

The next figure contains examples of the use of setf. Note that the values returned by evaluating the forms in column two are not necessarily the same as those obtained by evaluating the forms in column three. 7.2.0 18In general, the exact macro expansion of a setf form is not guaranteed and can even be implementation-dependent; all that is guaranteed is that the expansion is an update form that works for that particular implementation, that the left-to-right evaluation of subforms is preserved, and 7.2.0 19 that the ultimate result of evaluating setf is the value or values being stored.

Access functionUpdate FunctionUpdate using setf
x(setq x datum)(setf x datum)
(car x)(rplaca x datum)(setf (car x) datum)
(symbol-value x)(set x datum)(setf (symbol-value x) datum)

Figure 5–1. Examples of setf

The next figure shows operators relating to places and generalized reference.

assertdefsetfpush
ccaseget-setf-expansionremf
ctypecasegetfrotatef
decfincfsetf
define-modify-macropopshiftf
define-setf-expanderpsetf

Figure 5–2. Operators relating to places and generalized reference.

!!! Should defmethod be here for the sake of SETF methods?? -kmp 8-May-91

Some of the operators above manipulate places and some manipulate setf expanders. 7.2.0 57A setf expansion can be derived from any place. 7.2.0 20New setf expanders can be defined by using defsetf and define-setf-expander.

Moon thinks this follows from rule 2 below, and asked that it be commented out. 7.2.0 29 7.2.0 30 These operators evaluate the \term{subforms} of \term{places} exactly as many times as they appear in the source program, and exactly in the same order (left-to-right) as they appear in the source. \issue{PUSH-EVALUATION-ORDER:ITEM-FIRST} The left-to-right rule does not remove the obligation on writers of \term{macros} and users of \issue{SETF-METHOD-VS-SETF-METHOD:RENAME-OLD-TERMS} \macref{define-setf-expander} \endissue{SETF-METHOD-VS-SETF-METHOD:RENAME-OLD-TERMS} to ensure left-to-right order, however. \endissue{PUSH-EVALUATION-ORDER:ITEM-FIRST} 7.2.0 31 For example, in {\tt (setf \param{reference} \param{value})} \param{value} will be evaluated after all the \term{subforms} of \param{reference} because \param{value} appears to the right of them.

7.2.0 32 The expansion of these operators must consist of code that follows these rules or has the same effect as such code. This is accomplished by introducing temporary variables bound to the \issue{PUSH-EVALUATION-ORDER:ITEM-FIRST} \term{subforms} of the macro call. \endissue{PUSH-EVALUATION-ORDER:ITEM-FIRST} As an optimization in the implementation, temporary variables can be eliminated whenever removing them has no effect on the semantics of the program. For example, a constant need never be saved in a temporary variable. A variable or any \term{form} that does not have side effects need not be saved in a temporary variable if it can be proven that its value will not change within the scope of the \term{place}.

5.1.1.1 Evaluation of Subforms to Places#

The following rules apply to the evaluation of subforms in a place:

Rules 2, 3 and 4 cover all standardized macros that manipulate places.

5.1.1.1.1 Examples of Evaluation of Subforms to Places#
 (let ((ref2 (list '())))
   (push (progn (princ "1") 'ref-1)
         (car (progn (princ "2") ref2)))) 
⊳ 12
→ (REF1)

 (let (x)
    (push (setq x (list 'a))
          (car (setq x (list 'b))))
     x)
→ (((A) . B))

push first evaluates (setq x (list 'a)) → (a), then evaluates (setq x (list 'b)) → (b), then modifies the car of this latest value to be ((a) . b).

!!! Uses of "access", "accessing", etc. here are suspect. -kmp 18-Apr-91

5.1.1.2 Setf Expansions#

7.2.0 59Sometimes it is possible to avoid evaluating subforms of a place multiple times or in the wrong order. A setf expansion for a given access form can be expressed as an ordered collection of five objects:

!!! Andy Latto is concerned about whether "temporaries" mustn't or might be proclaimed special. And if they must not, must an implementation check? Would some elaboration of what a "temporary" is here be of help? -kmp 5-Dec-91

7.2.0 60

7.2.0 66The value returned by the accessing form is affected by execution of the storing form, but either of these forms might be evaluated any number of times.

7.2.0 67 Redundant with next paragraph. The temporary variables and the store variables must be generated names (see \funref{gensym} or \funref{gentemp}).

It is possible to do more than one setf in parallel via psetf, shiftf, and rotatef. Because of this, the setf expander must produce new temporary and store variable names every time. For examples of how to do this, see gensym. and \funref{gentemp}.

For each standardized accessor function F, unless it is explicitly documented otherwise, it is implementation-dependent whether the ability to use an F form as a setf place is implemented by a setf expander or a setf function. Also, it follows from this that it is implementation-dependent whether the name (setf F) is fbound.

5.1.1.2.1 Examples of Setf Expansions#
Examples of the contents of the constituents of setf expansions follow.

7.2.0 69For a variable x:

() ;list of temporary variables
() ;list of value forms
(g0001) ;list of store variables
(setq x g0001) ;storing form
x ;accessing form

Figure 5–3. Sample Setf Expansion of a Variable

7.2.0 70For (car exp):

(g0002) ;list of temporary variables
(exp) ;list of value forms
(g0003) ;list of store variables
(progn (rplaca g0002 g0003) g0003) ;storing form
(car g0002) ;accessing form

Figure 5–4. Sample Setf Expansion of a CAR Form

7.2.0 71For (subseq seq s e):

(g0004 g0005 g0006) ;list of temporary variables
(seq s e) ;list of value forms
(g0007) ;list of store variables
(progn (replace g0004 g0007 :start1 g0005 :end1 g0006) g0007)
;storing form
(subseq g0004 g0005 g0006) ; accessing form

Figure 5–5. Sample Setf Expansion of a SUBSEQ Form

In some cases, if a subform of a place is itself a place, it is necessary to expand the subform in order to compute some of the values in the expansion of the outer place. For (ldb bs (car exp)):

(g0001 g0002) ;list of temporary variables
(bs exp) ;list of value forms
(g0003) ;list of store variables
(progn (rplaca g0002 (dpb g0003 g0001 (car g0002))) g0003)
;storing form
(ldb g0001 (car g0002)) ; accessing form

Figure 5–6. Sample Setf Expansion of a LDB Form

5.1.2 Kinds of Places#

7.2.0 7Several kinds of places are defined by Common Lisp; this section enumerates them. This set can be extended by implementations and by programmer code.

7.2.0 8

5.1.2.1 Variable Names as Places#

The name of a lexical variable or dynamic variable can be used as a place.

7.2.0 9

5.1.2.2 Function Call Forms as Places#

A function form can be used as a place if it falls into one of the following categories:

This section added. --sjl 4 Mar 92

5.1.2.3 VALUES Forms as Places#

A values form can be used as a place, provided that each of its subforms is also a place form.

A form such as

(setf (values place-1 … place-n) values-form)

does the following:

The storing form in the setf expansion of values returns as multiple values2 the values of the store variables in step 2. That is, the number of values returned is the same as the number of place forms. This may be more or fewer values than are produced by the values-form.

There probably ought to be some examples here.

5.1.2.4 THE Forms as Places#

A the form can be used as a place, in which case the declaration is transferred to the newvalue form, and the resulting setf is analyzed. For example, 

 (setf (the integer (cadr x)) (+ y 3))
is processed as if it were 

 (setf (cadr x) (the integer (+ y 3)))

5.1.2.5 APPLY Forms as Places#

The following situations involving setf of apply must be supported:

In all three cases, the element of array designated by the concatenation of subscripts and more-subscripts (i.e., the same element which would be read by the call to apply if it were not part of a setf form) is changed to have the value given by new-element. For these usages, the function name (aref, bit, or sbit) must refer to the global function definition, rather than a locally defined function.

No other standardized function is required to be supported, but an implementation may define such support. An implementation may also define support for implementation-defined operators.

If a user-defined function is used in this context, the following equivalence is true, except that care is taken to preserve proper left-to-right evaluation of argument subforms: 

 (setf (apply #'name {arg}*) val)
 ≡ (apply #'(setf name) val {arg}*)

Removed reference to (setf (apply #'name a1 a2 ...) (values v1 v2 ...)) as bogus.

5.1.2.6 Setf Expansions and Places#

Any compound form for which the operator has a setf expander defined can be used as a place. The function name that is the \param{access-fn} argument to \macref{defsetf} or \issue{SETF-METHOD-VS-SETF-METHOD:RENAME-OLD-TERMS} \macref{define-setf-expander} \endissue{SETF-METHOD-VS-SETF-METHOD:RENAME-OLD-TERMS} previous phrase replaced by Moon as just "operator" -kmp 4-Dec-91operator must refer to the global function definition, rather than a locally defined function or macro.

7.2.0 16

5.1.2.7 Macro Forms as Places#

A macro form can be used as a place, in which case Common Lisp expands the macro form as if by macroexpand-1 and then uses the macro expansion in place of the original place. This is true for GET-SETF-EXPANSION, too, but there's no obvious place to say that. -kmp 5-Jun-91Such macro expansion is attempted only after exhausting all other possibilities other than expanding into a call to a function named (setf reader).

I moved this section here from below. --sjl 5 Mar 92

5.1.2.8 Symbol Macros as Places#

A reference to a symbol that has been established as a symbol macro can be used as a place. In this case, setf expands the reference and then analyzes the resulting form.

5.1.2.9 Other Compound Forms as Places#

For any other compound form for which the operator is a symbol f, the setf form expands into a call to the function named (setf f). The first argument in the newly constructed function form is newvalue and the remaining arguments are the remaining elements of place. This expansion occurs regardless of whether f or (setf f) is defined as a function locally, globally, or not at all. For example,

(setf (f arg1 arg2 ...) new-value)

expands into a form with the same effect and value as 

 (let ((#:temp-1 arg1)          ;force correct order of evaluation
       (#:temp-2 arg2)
       ...
       (#:temp-0 new-value))
   (funcall (function (setf f)) #:temp-0 #:temp-1 #:temp-2...))

A function named (setf f) must return its first argument as its only value in order to preserve the semantics of setf.

I moved the symbol macro section up to be with the ordinary macro section. --sjl 5 Mar 92

5.1.3 Treatment of Other Macros Based on SETF#

For each of the “read-modify-write” operators in the next figure, and for any additional macros defined by the programmer using define-modify-macro, an exception is made to the normal rule of left-to-right evaluation of arguments. Evaluation of argument forms occurs in left-to-right order, with the exception that for the place argument, the actual read of the “old value” from that place happens after all of the argument form evaluations, and just before a “new value” is computed and written back into the place.

Specifically, each of these operators can be viewed as involving a form with the following general syntax: 

 (operator {preceding-form}* place {following-form}*)

The evaluation of each such form proceeds like this:

decfpoppushnew
incfpushremf

Figure 5–9. Read-Modify-Write Macros

5.2 Transfer of Control to an Exit Point#

Exit Extents

This text was originally duplicated in each of GO, RETURN-FROM, and THROW. I thought it would be less redundant to centralize it here. --sjl 7 Mar 92

When a transfer of control is initiated by go, return-from, or throw the following events occur in order to accomplish the transfer of control. Note that for go, the exit point is the form within the tagbody that is being executed at the time the go is performed; for return-from, the exit point is the corresponding block form; and for throw, the exit point is the corresponding catch form.

The extent of an exit being “abandoned” because it is being passed over ends as soon as the transfer of control is initiated. That is, event 1 occurs at the beginning of the initiation of the transfer of control. The consequences are undefined if an attempt is made to transfer control to an exit point whose dynamic extent has ended.

Moon had me add the part about "interleaved" -kmp 13-Feb-92Events 2 and 3 are actually performed interleaved, in the order corresponding to the reverse order in which they were established. The effect of this is that the cleanup clauses of an unwind-protect see the same dynamic bindings of variables and catch tags as were visible when the unwind-protect was entered.

Event 4 occurs at the end of the transfer of control.

Dictionary

Contents|Symbol Index|Prev: 4. Types and Classes|Next: 6. Iteration
Rendered from the TeX sources of the draft ANSI Common Lisp standard (X3J13/92-102)