-This is Info file ../info/cl.info, produced by Makeinfo version 1.68
-from the input file cl.texi.
+This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
operate on generalized variables. Many are interesting and useful even
when the PLACE is just a variable name.
- - Special Form: psetf [PLACE FORM]...
+ - Special Form: psetf [place form]...
This macro is to `setf' what `psetq' is to `setq': When several
PLACEs and FORMs are involved, the assignments take place in
parallel rather than sequentially. Specifically, all subforms are
evaluated from left to right, then all the assignments are done
(in an undefined order).
- - Special Form: incf PLACE &optional X
+ - Special Form: incf place &optional x
This macro increments the number stored in PLACE by one, or by X
if specified. The incremented value is returned. For example,
`(incf i)' is equivalent to `(setq i (1+ i))', and `(incf (car x)
appears to increment `i' once, then increment the element of `vec'
addressed by `i'; this is indeed exactly what it does, which means
- the above form is *not* equivalent to the "obvious" expansion,
+ the above form is _not_ equivalent to the "obvious" expansion,
(setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong!
As a more Emacs-specific example of `incf', the expression `(incf
(point) N)' is essentially equivalent to `(forward-char N)'.
- - Special Form: decf PLACE &optional X
+ - Special Form: decf place &optional x
This macro decrements the number stored in PLACE by one, or by X
if specified.
- - Special Form: pop PLACE
+ - Special Form: pop place
This macro removes and returns the first element of the list stored
in PLACE. It is analogous to `(prog1 (car PLACE) (setf PLACE (cdr
PLACE)))', except that it takes care to evaluate all subforms only
once.
- - Special Form: push X PLACE
+ - Special Form: push x place
This macro inserts X at the front of the list stored in PLACE. It
is analogous to `(setf PLACE (cons X PLACE))', except for
evaluation of the subforms.
- - Special Form: pushnew X PLACE &key :test :test-not :key
+ - Special Form: pushnew x place &key :test :test-not :key
This macro inserts X at the front of the list stored in PLACE, but
only if X was not `eql' to any existing element of the list. The
optional keyword arguments are interpreted in the same way as for
`adjoin'. *Note Lists as Sets::.
- - Special Form: shiftf PLACE... NEWVALUE
+ - Special Form: shiftf place... newvalue
This macro shifts the PLACEs left by one, shifting in the value of
NEWVALUE (which may be any Lisp expression, not just a generalized
variable), and returning the value shifted out of the first PLACE.
except that the subforms of A, B, and C are actually evaluated
only once each and in the apparent order.
- - Special Form: rotatef PLACE...
+ - Special Form: rotatef place...
This macro rotates the PLACEs left by one in circular fashion.
Thus, `(rotatef A B C D)' is equivalent to
The following macros were invented for this package; they have no
analogues in Common Lisp.
- - Special Form: letf (BINDINGS...) FORMS...
+ - Special Form: letf (bindings...) forms...
This macro is analogous to `let', but for generalized variables
rather than just symbols. Each BINDING should be of the form
`(PLACE VALUE)'; the original contents of the PLACEs are saved,
not bound on entry, it is simply made unbound by `makunbound' or
`fmakunbound' on exit.
- - Special Form: letf* (BINDINGS...) FORMS...
+ - Special Form: letf* (bindings...) forms...
This macro is to `letf' what `let*' is to `let': It does the
bindings in sequential rather than parallel order.
that `callf' is an extension to standard Common Lisp.
- Special Form: callf2 FUNCTION ARG1 PLACE ARGS...
- This macro is like `callf', except that PLACE is the *second*
+ This macro is like `callf', except that PLACE is the _second_
argument of FUNCTION rather than the first. For example, `(push X
PLACE)' is equivalent to `(callf2 cons X PLACE)'.
The `callf' and `callf2' macros serve as building blocks for other
macros like `incf', `pushnew', and `define-modify-macro'. The `letf'
and `letf*' macros are used in the processing of symbol macros; *note
-Macro Bindings::..
+Macro Bindings::.
\1f
File: cl.info, Node: Customizing Setf, Prev: Modify Macros, Up: Generalized Variables
`define-setf-method', that allow the user to extend generalized
variables in various ways.
- - Special Form: define-modify-macro NAME ARGLIST FUNCTION [DOC-STRING]
+ - Special Form: define-modify-macro name arglist function [doc-string]
This macro defines a "read-modify-write" macro similar to `incf'
and `decf'. The macro NAME is defined to take a PLACE argument
followed by additional arguments described by ARGLIST. The call
`get-setf-method', or consult the source file `cl-macs.el' to see
how to use the internal `setf' building blocks.
- - Special Form: defsetf ACCESS-FN UPDATE-FN
+ - Special Form: defsetf access-fn update-fn
This is the simpler of two `defsetf' forms. Where ACCESS-FN is
the name of a function which accesses a place, this declares
UPDATE-FN to be the corresponding store function. From now on,
(defsetf symbol-value set)
(defsetf buffer-name rename-buffer t)
- - Special Form: defsetf ACCESS-FN ARGLIST (STORE-VAR) FORMS...
+ - Special Form: defsetf access-fn arglist (store-var) forms...
This is the second, more complex, form of `defsetf'. It is rather
like `defmacro' except for the additional STORE-VAR argument. The
FORMS should return a Lisp form which stores the value of
(defsetf nth (n x) (store)
(list 'setcar (list 'nthcdr n x) store))
- - Special Form: define-setf-method ACCESS-FN ARGLIST FORMS...
+ - Special Form: define-setf-method access-fn arglist forms...
This is the most general way to create new place forms. When a
`setf' to ACCESS-FN with arguments described by ARGLIST is
expanded, the FORMS are evaluated and must return a list of five
optimize away most temporaries that turn out to be unnecessary, so
there is little reason for the setf-method itself to optimize.
- - Function: get-setf-method PLACE &optional ENV
+ - Function: get-setf-method place &optional env
This function returns the setf-method for PLACE, by invoking the
definition previously recorded by `defsetf' or
`define-setf-method'. The result is a list of five values as
Modern Common Lisp defines a second, independent way to specify the
`setf' behavior of a function, namely "`setf' functions" whose names
are lists `(setf NAME)' rather than symbols. For example, `(defun
-(setf foo) ...)' defines the function that is used when `setf' is
+(setf foo) ...)' defines the function that is used when `setf' is
applied to `foo'. This package does not currently support `setf'
functions. In particular, it is a compile-time error to use `setf' on
a form which has not already been `defsetf''d or otherwise declared; in
compile-time. The `progv' form provides an easy way to bind variables
whose names are computed at run-time.
- - Special Form: progv SYMBOLS VALUES FORMS...
+ - Special Form: progv symbols values forms...
This form establishes `let'-style variable bindings on a set of
variables computed at run-time. The expressions SYMBOLS and
VALUES are evaluated, and must return lists of symbols and values,
The "CL" package defines the following macro which more closely follows
the Common Lisp `let' form:
- - Special Form: lexical-let (BINDINGS...) FORMS...
+ - Special Form: lexical-let (bindings...) forms...
This form is exactly like `let' except that the bindings it
establishes are purely lexical. Lexical bindings are similar to
local variables in a language like C: Only the code physically
The `lexical-let' form is an extension to Common Lisp. In true
Common Lisp, all bindings are lexical unless declared otherwise.
- - Special Form: lexical-let* (BINDINGS...) FORMS...
+ - Special Form: lexical-let* (bindings...) forms...
This form is just like `lexical-let', except that the bindings are
made sequentially in the manner of `let*'.
These forms make `let'-like bindings to functions instead of variables.
- - Special Form: flet (BINDINGS...) FORMS...
+ - Special Form: flet (bindings...) forms...
This form establishes `let'-style bindings on the function cells
of symbols rather than on the value cells. Each BINDING must be a
list of the form `(NAME ARGLIST FORMS...)', which defines a
enclosed in an implicit block as if by `defun*'. *Note Program
Structure::.
- - Special Form: labels (BINDINGS...) FORMS...
+ - Special Form: labels (bindings...) forms...
The `labels' form is a synonym for `flet'. (In Common Lisp,
`labels' and `flet' differ in ways that depend on their lexical
scoping; these distinctions vanish in dynamically scoped Emacs
These forms create local macros and "symbol macros."
- - Special Form: macrolet (BINDINGS...) FORMS...
+ - Special Form: macrolet (bindings...) forms...
This form is analogous to `flet', but for macros instead of
functions. Each BINDING is a list of the same form as the
arguments to `defmacro*' (i.e., a macro name, argument list, and
that appear physically within the body FORMS, possibly after
expansion of other macros in the body.
- - Special Form: symbol-macrolet (BINDINGS...) FORMS...
+ - Special Form: symbol-macrolet (bindings...) forms...
This form creates "symbol macros", which are macros that look like
variable references rather than function calls. Each BINDING is a
list `(VAR EXPANSION)'; any reference to VAR within the body FORMS
=> (2 3 4 5)
In this example, the `my-dolist' macro is similar to `dolist'
- (*note Iteration::.) except that the variable `x' becomes a true
+ (*note Iteration::) except that the variable `x' becomes a true
reference onto the elements of the list. The `my-dolist' call
shown here expands to
These conditional forms augment Emacs Lisp's simple `if', `and', `or',
and `cond' forms.
- - Special Form: when TEST FORMS...
+ - Special Form: when test forms...
This is a variant of `if' where there are no "else" forms, and
possibly several "then" forms. In particular,
(if TEST (progn A B C) nil)
- - Special Form: unless TEST FORMS...
+ - Special Form: unless test forms...
This is a variant of `if' where there are no "then" forms, and
possibly several "else" forms:
(when (not TEST) A B C)
- - Special Form: case KEYFORM CLAUSE...
+ - Special Form: case keyform clause...
This macro evaluates KEYFORM, then compares it with the key values
listed in the various CLAUSEs. Whichever clause matches the key
is executed; comparison is done by `eql'. If no clause matches,
((?\r ?\n) (do-ret-thing))
(t (do-other-thing)))
- - Special Form: ecase KEYFORM CLAUSE...
+ - Special Form: ecase keyform clause...
This macro is just like `case', except that if the key does not
match any of the clauses, an error is signalled rather than simply
returning `nil'.
- - Special Form: typecase KEYFORM CLAUSE...
+ - Special Form: typecase keyform clause...
This macro is a version of `case' that checks for types rather
than values. Each CLAUSE is of the form `(TYPE BODY...)'. *Note
Type Predicates::, for a description of type specifiers. For
`otherwise' is also allowed. To make one clause match any of
several types, use an `(or ...)' type specifier.
- - Special Form: etypecase KEYFORM CLAUSE...
+ - Special Form: etypecase keyform clause...
This macro is just like `typecase', except that if the key does
not match any of the clauses, an error is signalled rather than
simply returning `nil'.
costly `catch' step if the body of the block does not actually
`return-from' the block.
- - Special Form: block NAME FORMS...
+ - Special Form: block name forms...
The FORMS are evaluated as if by a `progn'. However, if any of
the FORMS execute `(return-from NAME)', they will jump out and
return directly from the `block' form. The `block' returns the
that `do' loops and `defun*' functions which don't use `return'
don't pay the overhead to support it.
- - Special Form: return-from NAME [RESULT]
+ - Special Form: return-from name [result]
This macro returns from the block named NAME, which must be an
(unevaluated) symbol. If a RESULT form is specified, it is
evaluated to produce the result returned from the `block'.
Otherwise, `nil' is returned.
- - Special Form: return [RESULT]
+ - Special Form: return [result]
This macro is exactly like `(return-from nil RESULT)'. Common
Lisp loops like `do' and `dolist' implicitly enclose themselves in
`nil' blocks.
The macros described here provide more sophisticated, high-level
looping constructs to complement Emacs Lisp's basic `while' loop.
- - Special Form: loop FORMS...
+ - Special Form: loop forms...
The "CL" package supports both the simple, old-style meaning of
`loop' and the extremely powerful and flexible feature known as
the "Loop Facility" or "Loop Macro". This more advanced facility
- is discussed in the following section; *note Loop Facility::..
- The simple form of `loop' is described here.
+ is discussed in the following section; *note Loop Facility::. The
+ simple form of `loop' is described here.
If `loop' is followed by zero or more Lisp expressions, then
`(loop EXPRS...)' simply creates an infinite loop executing the
the above notation would simply access and throw away the value of
a variable.)
- - Special Form: do (SPEC...) (END-TEST [RESULT...]) FORMS...
+ - Special Form: do (spec...) (end-test [result...]) forms...
This macro creates a general iterative loop. Each SPEC is of the
form
VAR has no STEP form, it is bound to its INIT value but not
otherwise modified during the `do' loop (unless the code
explicitly modifies it); this case is just a shorthand for putting
- a `(let ((VAR INIT)) ...)' around the loop. If INIT is also
+ a `(let ((VAR INIT)) ...)' around the loop. If INIT is also
omitted it defaults to `nil', and in this case a plain `VAR' can
be used in place of `(VAR)', again following the analogy with
`let'.
((or (null x) (null y))
(nreverse z)))
- - Special Form: do* (SPEC...) (END-TEST [RESULT...]) FORMS...
+ - Special Form: do* (spec...) (end-test [result...]) forms...
This is to `do' what `let*' is to `let'. In particular, the
initial values are bound as if by `let*' rather than `let', and
the steps are assigned as if by `setq' rather than `psetq'.
(nreverse z))
(push (f x y) z))
- - Special Form: dolist (VAR LIST [RESULT]) FORMS...
+ - Special Form: dolist (var list [result]) forms...
This is a more specialized loop which iterates across the elements
of a list. LIST should evaluate to a list; the body FORMS are
executed with VAR bound to each element of the list in turn.
`nil' to produce the result returned by the loop. The loop is
surrounded by an implicit `nil' block.
- - Special Form: dotimes (VAR COUNT [RESULT]) FORMS...
+ - Special Form: dotimes (var count [result]) forms...
This is a more specialized loop which iterates a specified number
of times. The body is executed with VAR bound to the integers
from zero (inclusive) to COUNT (exclusive), in turn. Then the
return value for the loop form. The loop is surrounded by an
implicit `nil' block.
- - Special Form: do-symbols (VAR [OBARRAY [RESULT]]) FORMS...
+ - Special Form: do-symbols (var [obarray [result]]) forms...
This loop iterates over all interned symbols. If OBARRAY is
specified and is not `nil', it loops over all symbols in that
obarray. For each symbol, the body FORMS are evaluated with VAR
bound to `nil') to get the return value. The loop is surrounded
by an implicit `nil' block.
- - Special Form: do-all-symbols (VAR [RESULT]) FORMS...
+ - Special Form: do-all-symbols (var [result]) forms...
This is identical to `do-symbols' except that the OBARRAY argument
is omitted; it always iterates over the default obarray.
place at byte-compile time; compiled `loop's are just as efficient as
the equivalent `while' loops written longhand.
- - Special Form: loop CLAUSES...
+ - Special Form: loop clauses...
A loop construct consists of a series of CLAUSEs, each introduced
by a symbol like `for' or `do'. Clauses are simply strung
together in the argument list of `loop', with minimal extra