xemacs-beta: man/cl.texi comparison

comparison man/cl.texi @ 5547:a46c5c8d6564

Avoid calling various macros "special operators" in the manuals. 2011-08-09 Aidan Kehoe <kehoea@parhasard.net> * cl.texi (Argument Lists): * cl.texi (Time of Evaluation): * cl.texi (Type Predicates): * cl.texi (Assignment): * cl.texi (Basic Setf): * cl.texi (Modify Macros): * cl.texi (Customizing Setf): * cl.texi (Dynamic Bindings): * cl.texi (Lexical Bindings): * cl.texi (Function Bindings): * cl.texi (Macro Bindings): * cl.texi (Conditionals): * cl.texi (Blocks and Exits): * cl.texi (Iteration): * cl.texi (Loop Basics): * cl.texi (Macros): * cl.texi (Declarations): * cl.texi (Property Lists): * cl.texi (Structures): * cl.texi (Assertions): * cl.texi (Efficiency Concerns): * lispref/compile.texi (Eval During Compile): * lispref/compile.texi (Compiled-Function Objects): * lispref/eval.texi (Multiple values): * lispref/frames.texi (Input Focus): * lispref/internationalization.texi (Level 3 Primitives): * lispref/positions.texi (Excursions): * lispref/positions.texi (Narrowing): * lispref/searching.texi (Saving Match Data): * lispref/specifiers.texi (Adding Specifications): * lispref/windows.texi: Correct the manuals to avoid using the term "special operator" when #'special-operator-p would give nil.

author	Aidan Kehoe <kehoea@parhasard.net>
date	Tue, 09 Aug 2011 17:17:44 +0100
parents	62b9ef1ed4ac
children	4654c01af32b

comparison

equal deleted inserted replaced

-:d54278e74d71
+:a46c5c8d6564
 Since argument parsing is built-in to Emacs, there is no way for
 this package to implement Common Lisp argument lists seamlessly.
 Instead, this package defines alternates for several Lisp forms
 which you must use if you need Common Lisp argument lists.
-@deffn {Special Operator} defun* name arglist body...
+@defmac defun* name arglist body...
 This form is identical to the regular @code{defun} form, except
 that @var{arglist} is allowed to be a full Common Lisp argument
 list.  Also, the function body is enclosed in an implicit block
 called @var{name}; @pxref{Blocks and Exits}.
-@end deffn
+@end defmac
-@deffn {Special Operator} defsubst* name arglist body...
+@defmac defsubst* name arglist body...
 This is just like @code{defun*}, except that the function that
 is defined is automatically proclaimed @code{inline}, i.e.,
 calls to it may be expanded into in-line code by the byte compiler.
 This is analogous to the @code{defsubst} form in Emacs 19;
 @code{defsubst*} uses a different method (compiler macros) which
 works in all version of Emacs, and also generates somewhat more
 efficient inline expansions.  In particular, @code{defsubst*}
 arranges for the processing of keyword arguments, default values,
 etc., to be done at compile-time whenever possible.
-@end deffn
+@end defmac
-@deffn {Special Operator} defmacro* name arglist body...
+@defmac defmacro* name arglist body...
 This is identical to the regular @code{defmacro} form,
 except that @var{arglist} is allowed to be a full Common Lisp
 argument list.  The @code{&environment} keyword is supported as
 described in Steele.  The @code{&whole} keyword is supported only
 within destructured lists (see below); top-level @code{&whole}
 cannot be implemented with the current Emacs Lisp interpreter.
 The macro expander body is enclosed in an implicit block called
 @var{name}.
-@end deffn
+@end defmac
-@deffn {Special Operator} function* symbol-or-lambda
+@defmac function* symbol-or-lambda
 This is identical to the regular @code{function} form,
 except that if the argument is a @code{lambda} form then that
 form may use a full Common Lisp argument list.
-@end deffn
+@end defmac
 Also, all forms (such as @code{defsetf} and @code{flet}) defined
 in this package that include @var{arglist}s in their syntax allow
 full Common Lisp argument lists.
 would like to have certain top-level forms evaluated at compile-time.
 For example, the compiler effectively evaluates @code{defmacro} forms
 at compile-time so that later parts of the file can refer to the
 macros that are defined.
-@deffn {Special Operator} eval-when (situations...) forms...
+@defmac eval-when (situations...) forms...
 This form controls when the body @var{forms} are evaluated.
 The @var{situations} list may contain any set of the symbols
 @code{compile}, @code{load}, and @code{eval} (or their long-winded
 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
 and @code{:execute}).
 Note that @code{(eval-when (load eval) @dots{})} is equivalent
 to @code{(progn @dots{})} in all contexts.  The compiler treats
 certain top-level forms, like @code{defmacro} (sort-of) and
 @code{require}, as if they were wrapped in @code{(eval-when
 (compile load eval) @dots{})}.
-@end deffn
+@end defmac
 Emacs 19 includes two special operators related to @code{eval-when}.
 One of these, @code{eval-when-compile}, is not quite equivalent to
 any @code{eval-when} construct and is described below.  This package
 defines a version of @code{eval-when-compile} for the benefit of
 The other form, @code{(eval-and-compile @dots{})}, is exactly
 equivalent to @samp{(eval-when (compile load eval) @dots{})} and
 so is not itself defined by this package.
-@deffn {Special Operator} eval-when-compile forms...
+@defmac eval-when-compile forms...
 The @var{forms} are evaluated at compile-time; at execution time,
 this form acts like a quoted constant of the resulting value.  Used
 at top-level, @code{eval-when-compile} is just like @samp{eval-when
 (compile eval)}.  In other contexts, @code{eval-when-compile}
 allows code to be evaluated once at compile-time for efficiency
 or other reasons.
 This form is similar to the @samp{#.} syntax of true Common Lisp.
-@end deffn
+@end defmac
-@deffn {Special Operator} load-time-value form
+@defmac load-time-value form
 The @var{form} is evaluated at load-time; at execution time,
 this form acts like a quoted constant of the resulting value.
 Early Common Lisp had a @samp{#,} syntax that was similar to
 this, but ANSI Common Lisp replaced it with @code{load-time-value}
 ", compiled on: "
 '"Wed Jun 23 18:33:43 1993"
 ", and loaded on: "
 --temp--))
 @end example
-@end deffn
+@end defmac
 @node Function Aliases, , Time of Evaluation, Program Structure
 @section Function Aliases
 @noindent
 then integers can be coerced in versions of Emacs that support
 floats.  In all other circumstances, @code{coerce} signals an
 error.
 @end defun
-@deffn {Special Operator} deftype name arglist forms...
+@defmac deftype name arglist forms...
 This macro defines a new type called @var{name}.  It is similar
 to @code{defmacro} in many ways; when @var{name} is encountered
 as a type name, the body @var{forms} are evaluated and should
 return a type specifier that is equivalent to the type.  The
 @var{arglist} is a Common Lisp argument list of the sort accepted
 @noindent
 The last example shows how the Common Lisp @code{unsigned-byte}
 type specifier could be implemented if desired; this package does
 not implement @code{unsigned-byte} by default.
-@end deffn
+@end defmac
 The @code{typecase} and @code{check-type} macros also use type
 names.  @xref{Conditionals}.  @xref{Assertions}.  The @code{map},
 @code{concatenate}, and @code{merge} functions take type-name
 arguments to specify the type of sequence to return.  @xref{Sequences}.
 @noindent
 The @code{psetq} form is just like @code{setq}, except that multiple
 assignments are done in parallel rather than sequentially.
-@deffn {Special Operator} psetq [symbol form]@dots{}
+@defmac psetq [symbol form]@dots{}
 This macro is used to assign to several
 variables simultaneously.  Given only one @var{symbol} and @var{form},
 it has the same effect as @code{setq}.  Given several @var{symbol}
 and @var{form} pairs, it evaluates all the @var{form}s in advance
 and then stores the corresponding variables afterwards.
 exchanges the values of two variables.  (The @code{rotatef} form
 provides an even more convenient way to swap two variables;
 @pxref{Modify Macros}.)
 @code{psetq} always returns @code{nil}.
-@end deffn
+@end defmac
 @node Generalized Variables, Variable Bindings, Assignment, Control Structure
 @section Generalized Variables
 @noindent
 @noindent
 The @code{setf} macro is the most basic way to operate on generalized
 variables.
-@deffn {Special Operator} setf [place form]@dots{}
+@defmac setf [place form]@dots{}
 This macro evaluates @var{form} and stores it in @var{place}, which
 must be a valid generalized variable form.  If there are several
 @var{place} and @var{form} pairs, the assignments are done sequentially
 just as with @code{setq}.  @code{setf} returns the value of the last
 @var{form}.
 @noindent
 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
 evaluate @var{b} first, then @var{a}, just as in an actual call
 to @code{wrong-order}.
-@end deffn
+@end defmac
 @node Modify Macros, Customizing Setf, Basic Setf, Generalized Variables
 @subsection Modify Macros
 @noindent
 This package defines a number of other macros besides @code{setf}
 that operate on generalized variables.  Many are interesting and
 useful even when the @var{place} is just a variable name.
-@deffn {Special Operator} psetf [place form]@dots{}
+@defmac psetf [place form]@dots{}
 This macro is to @code{setf} what @code{psetq} is to @code{setq}:
 When several @var{place}s and @var{form}s 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).
-@end deffn
+@end defmac
-@deffn {Special Operator} incf place &optional x
+@defmac incf place &optional x
 This macro increments the number stored in @var{place} by one, or
 by @var{x} if specified.  The incremented value is returned.  For
 example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and
 @code{(incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
 the other generalized-variable macros.
 As a more Emacs-specific example of @code{incf}, the expression
 @code{(incf (point) @var{n})} is essentially equivalent to
 @code{(forward-char @var{n})}.
-@end deffn
+@end defmac
-@deffn {Special Operator} decf place &optional x
+@defmac decf place &optional x
 This macro decrements the number stored in @var{place} by one, or
 by @var{x} if specified.
-@end deffn
+@end defmac
-@deffn {Special Operator} pop place
+@defmac pop place
 This macro removes and returns the first element of the list stored
 in @var{place}.  It is analogous to @code{(prog1 (car @var{place})
 (setf @var{place} (cdr @var{place})))}, except that it takes care
 to evaluate all subforms only once.
-@end deffn
+@end defmac
-@deffn {Special Operator} push x place
+@defmac push x place
 This macro inserts @var{x} at the front of the list stored in
 @var{place}.  It is analogous to @code{(setf @var{place} (cons
 @var{x} @var{place}))}, except for evaluation of the subforms.
-@end deffn
+@end defmac
-@deffn {Special Operator} pushnew x place @t{&key :test :test-not :key}
+@defmac pushnew x place @t{&key :test :test-not :key}
 This macro inserts @var{x} at the front of the list stored in
 @var{place}, but only if @var{x} was not @code{eql} to any
 existing element of the list.  The optional keyword arguments
 are interpreted in the same way as for @code{adjoin}.
 @xref{Lists as Sets}.
-@end deffn
+@end defmac
-@deffn {Special Operator} shiftf place@dots{} newvalue
+@defmac shiftf place@dots{} newvalue
 This macro shifts the @var{place}s left by one, shifting in the
 value of @var{newvalue} (which may be any Lisp expression, not just
 a generalized variable), and returning the value shifted out of
 the first @var{place}.  Thus, @code{(shiftf @var{a} @var{b} @var{c}
 @var{d})} is equivalent to
 @end example
 @noindent
 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
 evaluated only once each and in the apparent order.
-@end deffn
+@end defmac
-@deffn {Special Operator} rotatef place@dots{}
+@defmac rotatef place@dots{}
 This macro rotates the @var{place}s left by one in circular fashion.
 Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
 @example
 (psetf @var{a} @var{b}
 @noindent
 except for the evaluation of subforms.  @code{rotatef} always
 returns @code{nil}.  Note that @code{(rotatef @var{a} @var{b})}
 conveniently exchanges @var{a} and @var{b}.
-@end deffn
+@end defmac
 The following macros were invented for this package; they have no
 analogues in Common Lisp.
-@deffn {Special Operator} letf (bindings@dots{}) forms@dots{}
+@defmac letf (bindings@dots{}) forms@dots{}
 This macro is analogous to @code{let}, but for generalized variables
 rather than just symbols.  Each @var{binding} should be of the form
 @code{(@var{place} @var{value})}; the original contents of the
 @var{place}s are saved, the @var{value}s are stored in them, and
 then the body @var{form}s are executed.  Afterwards, the @var{places}
 In most cases, the @var{place} must have a well-defined value on
 entry to the @code{letf} form.  The only exceptions are plain
 variables and calls to @code{symbol-value} and @code{symbol-function}.
 If the symbol is not bound on entry, it is simply made unbound by
 @code{makunbound} or @code{fmakunbound} on exit.
-@end deffn
+@end defmac
-@deffn {Special Operator} letf* (bindings@dots{}) forms@dots{}
+@defmac letf* (bindings@dots{}) forms@dots{}
 This macro is to @code{letf} what @code{let*} is to @code{let}:
 It does the bindings in sequential rather than parallel order.
-@end deffn
+@end defmac
-@deffn {Special Operator} callf @var{function} @var{place} @var{args}@dots{}
+@defmac callf @var{function} @var{place} @var{args}@dots{}
 This is the ``generic'' modify macro.  It calls @var{function},
 which should be an unquoted function name, macro name, or lambda.
 It passes @var{place} and @var{args} as arguments, and assigns the
 result back to @var{place}.  For example, @code{(incf @var{place}
 @var{n})} is the same as @code{(callf + @var{place} @var{n})}.
 @end example
 @xref{Customizing Setf}, for @code{define-modify-macro}, a way
 to create even more concise notations for modify macros.  Note
 again that @code{callf} is an extension to standard Common Lisp.
-@end deffn
+@end defmac
-@deffn {Special Operator} callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
+@defmac callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
 This macro is like @code{callf}, except that @var{place} is
 the @emph{second} argument of @var{function} rather than the
 first.  For example, @code{(push @var{x} @var{place})} is
 equivalent to @code{(callf2 cons @var{x} @var{place})}.
-@end deffn
+@end defmac
 The @code{callf} and @code{callf2} macros serve as building
 blocks for other macros like @code{incf}, @code{pushnew}, and
 @code{define-modify-macro}.  The @code{letf} and @code{letf*}
 macros are used in the processing of symbol macros;
 @noindent
 Common Lisp defines three macros, @code{define-modify-macro},
 @code{defsetf}, and @code{define-setf-method}, that allow the
 user to extend generalized variables in various ways.
-@deffn {Special Operator} define-modify-macro name arglist function [doc-string]
+@defmac define-modify-macro name arglist function [doc-string]
 This macro defines a ``read-modify-write'' macro similar to
 @code{incf} and @code{decf}.  The macro @var{name} is defined
 to take a @var{place} argument followed by additional arguments
 described by @var{arglist}.  The call
 @code{push} takes its arguments in the wrong order, and @code{pop}
 is completely irregular.  You can define these macros ``by hand''
 using @code{get-setf-method}, or consult the source file
 @file{cl-macs.el} to see how to use the internal @code{setf}
 building blocks.
-@end deffn
+@end defmac
-@deffn {Special Operator} defsetf access-fn update-fn
+@defmac defsetf access-fn update-fn
 This is the simpler of two @code{defsetf} forms.  Where
 @var{access-fn} is the name of a function which accesses a place,
 this declares @var{update-fn} to be the corresponding store
 function.  From now on,
 @example
 (defsetf car setcar)
 (defsetf symbol-value set)
 (defsetf buffer-name rename-buffer t)
 @end example
-@end deffn
+@end defmac
-@deffn {Special Operator} defsetf access-fn arglist (store-var) forms@dots{}
+@defmac defsetf access-fn arglist (store-var) forms@dots{}
 This is the second, more complex, form of @code{defsetf}.  It is
 rather like @code{defmacro} except for the additional @var{store-var}
 argument.  The @var{forms} should return a Lisp form which stores
 the value of @var{store-var} into the generalized variable formed
 by a call to @var{access-fn} with arguments described by @var{arglist}.
 @example
 (defsetf nth (n x) (store)
 (list 'setcar (list 'nthcdr n x) store))
 @end example
-@end deffn
+@end defmac
-@deffn {Special Operator} define-setf-method access-fn arglist forms@dots{}
+@defmac define-setf-method access-fn arglist forms@dots{}
 This is the most general way to create new place forms.  When
 a @code{setf} to @var{access-fn} with arguments described by
 @var{arglist} is expanded, the @var{forms} are evaluated and
 must return a list of five items:
 list of a corresponding number of temporary variables generated
 by @code{gensym}.  Macros like @code{setf} and @code{incf} which
 use this setf-method will optimize away most temporaries that
 turn out to be unnecessary, so there is little reason for the
 setf-method itself to optimize.
-@end deffn
+@end defmac
 @defun get-setf-method place &optional env
 This function returns the setf-method for @var{place}, by
 invoking the definition previously recorded by @code{defsetf}
 or @code{define-setf-method}.  The result is a list of five
 @noindent
 The standard @code{let} form binds variables whose names are known
 at compile-time.  The @code{progv} form provides an easy way to
 bind variables whose names are computed at run-time.
-@deffn {Special Operator} progv symbols values forms@dots{}
+@defmac progv symbols values forms@dots{}
 This form establishes @code{let}-style variable bindings on a
 set of variables computed at run-time.  The expressions
 @var{symbols} and @var{values} are evaluated, and must return lists
 of symbols and values, respectively.  The symbols are bound to the
 corresponding values for the duration of the body @var{form}s.
 If @var{values} is shorter than @var{symbols}, the last few symbols
 are made unbound (as if by @code{makunbound}) inside the body.
 If @var{symbols} is shorter than @var{values}, the excess values
 are ignored.
-@end deffn
+@end defmac
 @node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings
 @subsection Lexical Bindings
 @noindent
 The @dfn{CL} package defines the following macro which
 more closely follows the Common Lisp @code{let} form:
-@deffn {Special Operator} lexical-let (bindings@dots{}) forms@dots{}
+@defmac lexical-let (bindings@dots{}) forms@dots{}
 This form is exactly like @code{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
 within the body of the @code{lexical-let} (after macro expansion)
 may refer to the bound variables.
 body of a single @code{lexical-let}, they all close over the same
 instance of the lexical variable.
 The @code{lexical-let} form is an extension to Common Lisp.  In
 true Common Lisp, all bindings are lexical unless declared otherwise.
-@end deffn
+@end defmac
-@deffn {Special Operator} lexical-let* (bindings@dots{}) forms@dots{}
+@defmac lexical-let* (bindings@dots{}) forms@dots{}
 This form is just like @code{lexical-let}, except that the bindings
 are made sequentially in the manner of @code{let*}.
-@end deffn
+@end defmac
 @node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings
 @subsection Function Bindings
 @noindent
 These forms make @code{let}-like bindings to functions instead
 of variables.
-@deffn {Special Operator} flet (bindings@dots{}) forms@dots{}
+@defmac flet (bindings@dots{}) forms@dots{}
 This form establishes @code{let}-style bindings on the function
 cells of symbols rather than on the value cells.  Each @var{binding}
 must be a list of the form @samp{(@var{name} @var{arglist}
 @var{forms}@dots{})}, which defines a function exactly as if
 it were a @code{defun*} form.  The function @var{name} is defined
 Functions defined by @code{flet} may use the full Common Lisp
 argument notation supported by @code{defun*}; also, the function
 body is enclosed in an implicit block as if by @code{defun*}.
 @xref{Program Structure}.
-@end deffn
+@end defmac
-@deffn {Special Operator} labels (bindings@dots{}) forms@dots{}
+@defmac labels (bindings@dots{}) forms@dots{}
 The @code{labels} form is a synonym for @code{flet}.  (In Common
 Lisp, @code{labels} and @code{flet} differ in ways that depend on
 their lexical scoping; these distinctions vanish in dynamically
 scoped Emacs Lisp.)
-@end deffn
+@end defmac
 @node Macro Bindings, , Function Bindings, Variable Bindings
 @subsection Macro Bindings
 @noindent
 These forms create local macros and ``symbol macros.''
-@deffn {Special Operator} macrolet (bindings@dots{}) forms@dots{}
+@defmac macrolet (bindings@dots{}) forms@dots{}
 This form is analogous to @code{flet}, but for macros instead of
 functions.  Each @var{binding} is a list of the same form as the
 arguments to @code{defmacro*} (i.e., a macro name, argument list,
 and macro-expander forms).  The macro is defined accordingly for
 use within the body of the @code{macrolet}.
 Because of the nature of macros, @code{macrolet} is lexically
 scoped even in Emacs Lisp:  The @code{macrolet} binding will
 affect only calls that appear physically within the body
 @var{forms}, possibly after expansion of other macros in the
 body.
-@end deffn
+@end defmac
-@deffn {Special Operator} symbol-macrolet (bindings@dots{}) forms@dots{}
+@defmac symbol-macrolet (bindings@dots{}) forms@dots{}
 This form creates @dfn{symbol macros}, which are macros that look
 like variable references rather than function calls.  Each
 @var{binding} is a list @samp{(@var{var} @var{expansion})};
 any reference to @var{var} within the body @var{forms} is
 replaced by @var{expansion}.
 @end example
 @xref{Loop Facility}, for a description of the @code{loop} macro.
 This package defines a nonstandard @code{in-ref} loop clause that
 works much like @code{my-dolist}.
-@end deffn
+@end defmac
 @node Conditionals, Blocks and Exits, Variable Bindings, Control Structure
 @section Conditionals
 @noindent
 These conditional forms augment Emacs Lisp's simple @code{if},
 @code{and}, @code{or}, and @code{cond} forms.
-@deffn {Special Operator} when test forms@dots{}
+@defmac when test forms@dots{}
 This is a variant of @code{if} where there are no ``else'' forms,
 and possibly several ``then'' forms.  In particular,
 @example
 (when @var{test} @var{a} @var{b} @var{c})
 is entirely equivalent to
 @example
 (if @var{test} (progn @var{a} @var{b} @var{c}) nil)
 @end example
-@end deffn
+@end defmac
-@deffn {Special Operator} unless test forms@dots{}
+@defmac unless test forms@dots{}
 This is a variant of @code{if} where there are no ``then'' forms,
 and possibly several ``else'' forms:
 @example
 (unless @var{test} @var{a} @var{b} @var{c})
 is entirely equivalent to
 @example
 (when (not @var{test}) @var{a} @var{b} @var{c})
 @end example
-@end deffn
+@end defmac
-@deffn {Special Operator} case keyform clause@dots{}
+@defmac case keyform clause@dots{}
 This macro evaluates @var{keyform}, then compares it with the key
 values listed in the various @var{clause}s.  Whichever clause matches
 the key is executed; comparison is done by @code{eql}.  If no clause
 matches, the @code{case} form returns @code{nil}.  The clauses are
 of the form
 (?a (do-a-thing))
 (?b (do-b-thing))
 ((?\r ?\n) (do-ret-thing))
 (t (do-other-thing)))
 @end example
-@end deffn
+@end defmac
-@deffn {Special Operator} ecase keyform clause@dots{}
+@defmac ecase keyform clause@dots{}
 This macro is just like @code{case}, except that if the key does
 not match any of the clauses, an error is signalled rather than
 simply returning @code{nil}.
-@end deffn
+@end defmac
-@deffn {Special Operator} typecase keyform clause@dots{}
+@defmac typecase keyform clause@dots{}
 This macro is a version of @code{case} that checks for types
 rather than values.  Each @var{clause} is of the form
 @samp{(@var{type} @var{body}...)}.  @xref{Type Predicates},
 for a description of type specifiers.  For example,
 @end example
 The type specifier @code{t} matches any type of object; the word
 @code{otherwise} is also allowed.  To make one clause match any of
 several types, use an @code{(or ...)} type specifier.
-@end deffn
+@end defmac
-@deffn {Special Operator} etypecase keyform clause@dots{}
+@defmac etypecase keyform clause@dots{}
 This macro is just like @code{typecase}, except that if the key does
 not match any of the clauses, an error is signalled rather than
 simply returning @code{nil}.
-@end deffn
+@end defmac
 @node Blocks and Exits, Iteration, Conditionals, Control Structure
 @section Blocks and Exits
 @noindent
 dynamically scoped.  This package actually implements @code{block}
 in terms of @code{catch}; however, the lexical scoping allows the
 optimizing byte-compiler to omit the costly @code{catch} step if the
 body of the block does not actually @code{return-from} the block.
-@deffn {Special Operator} block name forms@dots{}
+@defmac block name forms@dots{}
 The @var{forms} are evaluated as if by a @code{progn}.  However,
 if any of the @var{forms} execute @code{(return-from @var{name})},
 they will jump out and return directly from the @code{block} form.
 The @code{block} returns the result of the last @var{form} unless
 a @code{return-from} occurs.
 Emacs 19) will optimize away the @code{catch} if the block does
 not in fact contain any @code{return} or @code{return-from} calls
 that jump to it.  This means that @code{do} loops and @code{defun*}
 functions which don't use @code{return} don't pay the overhead to
 support it.
-@end deffn
+@end defmac
-@deffn {Special Operator} return-from name [result]
+@defmac return-from name [result]
 This macro returns from the block named @var{name}, which must be
 an (unevaluated) symbol.  If a @var{result} form is specified, it
 is evaluated to produce the result returned from the @code{block}.
 Otherwise, @code{nil} is returned.
-@end deffn
+@end defmac
-@deffn {Special Operator} return [result]
+@defmac return [result]
 This macro is exactly like @code{(return-from nil @var{result})}.
 Common Lisp loops like @code{do} and @code{dolist} implicitly enclose
 themselves in @code{nil} blocks.
-@end deffn
+@end defmac
 @node Iteration, Loop Facility, Blocks and Exits, Control Structure
 @section Iteration
 @noindent
 The macros described here provide more sophisticated, high-level
 looping constructs to complement Emacs Lisp's basic @code{while}
 loop.
-@deffn {Special Operator} loop forms@dots{}
+@defmac loop forms@dots{}
 The @dfn{CL} package supports both the simple, old-style meaning of
 @code{loop} and the extremely powerful and flexible feature known as
 the @dfn{Loop Facility} or @dfn{Loop Macro}.  This more advanced
 facility is discussed in the following section; @pxref{Loop Facility}.
 The simple form of @code{loop} is described here.
 If any of the expressions are plain symbols, the loop is instead
 interpreted as a Loop Macro specification as described later.
 (This is not a restriction in practice, since a plain symbol
 in the above notation would simply access and throw away the
 value of a variable.)
-@end deffn
+@end defmac
-@deffn {Special Operator} do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
+@defmac do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
 This macro creates a general iterative loop.  Each @var{spec} is
 of the form
 @example
 (@var{var} [@var{init} [@var{step}]])
 (y bar (cdr y))
 (z nil (cons (f (car x) (car y)) z)))
 ((or (null x) (null y))
 (nreverse z)))
 @end example
-@end deffn
+@end defmac
-@deffn {Special Operator} do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
+@defmac do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
 This is to @code{do} what @code{let*} is to @code{let}.  In
 particular, the initial values are bound as if by @code{let*}
 rather than @code{let}, and the steps are assigned as if by
 @code{setq} rather than @code{psetq}.
 z)
 ((or (null xp) (null yp))
 (nreverse z))
 (push (f x y) z))
 @end example
-@end deffn
+@end defmac
-@deffn {Special Operator} dolist (var list [result]) forms@dots{}
+@defmac dolist (var list [result]) forms@dots{}
 This is a more specialized loop which iterates across the elements
 of a list.  @var{list} should evaluate to a list; the body @var{forms}
 are executed with @var{var} bound to each element of the list in
 turn.  Finally, the @var{result} form (or @code{nil}) is evaluated
 with @var{var} bound to @code{nil} to produce the result returned by
 the loop.  The loop is surrounded by an implicit @code{nil} block.
-@end deffn
+@end defmac
-@deffn {Special Operator} dotimes (var count [result]) forms@dots{}
+@defmac dotimes (var count [result]) forms@dots{}
 This is a more specialized loop which iterates a specified number
 of times.  The body is executed with @var{var} bound to the integers
 from zero (inclusive) to @var{count} (exclusive), in turn.  Then
 the @code{result} form is evaluated with @var{var} bound to the total
 number of iterations that were done (i.e., @code{(max 0 @var{count})})
 to get the return value for the loop form.  The loop is surrounded
 by an implicit @code{nil} block.
-@end deffn
+@end defmac
-@deffn {Special Operator} do-symbols (var [obarray [result]]) forms@dots{}
+@defmac do-symbols (var [obarray [result]]) forms@dots{}
 This loop iterates over all interned symbols.  If @var{obarray}
 is specified and is not @code{nil}, it loops over all symbols in
 that obarray.  For each symbol, the body @var{forms} are evaluated
 with @var{var} bound to that symbol.  The symbols are visited in
 an unspecified order.  Afterward the @var{result} form, if any,
 is evaluated (with @var{var} bound to @code{nil}) to get the return
 value.  The loop is surrounded by an implicit @code{nil} block.
-@end deffn
+@end defmac
-@deffn {Special Operator} do-all-symbols (var [result]) forms@dots{}
+@defmac do-all-symbols (var [result]) forms@dots{}
 This is identical to @code{do-symbols} except that the @var{obarray}
 argument is omitted; it always iterates over the default obarray.
-@end deffn
+@end defmac
 @xref{Mapping over Sequences}, for some more functions for
 iterating over vectors or lists.
 @node Loop Facility, Multiple Values, Iteration, Control Structure
 Since @code{loop} is a macro, all parsing of the loop language
 takes place at byte-compile time; compiled @code{loop}s are just
 as efficient as the equivalent @code{while} loops written longhand.
-@deffn {Special Operator} loop clauses@dots{}
+@defmac loop clauses@dots{}
 A loop construct consists of a series of @var{clause}s, each
 introduced by a symbol like @code{for} or @code{do}.  Clauses
 are simply strung together in the argument list of @code{loop},
 with minimal extra parentheses.  The various types of clauses
 specify initializations, such as the binding of temporary
 @code{collect}, an end-test clause like @code{always}, or an
 explicit @code{return} clause to jump out of the implicit block.
 (Because the loop body is enclosed in an implicit block, you can
 also use regular Lisp @code{return} or @code{return-from} to
 break out of the loop.)
-@end deffn
+@end defmac
 The following sections give some examples of the Loop Macro in
 action, and describe the particular loop clauses in great detail.
 Consult the second edition of Steele's @dfn{Common Lisp, the Language},
 for additional discussion and examples of the @code{loop} macro.
 @xref{Argument Lists}.
 Destructuring is made available to the user by way of the
 following macro:
-@deffn {Special Operator} destructuring-bind arglist expr forms@dots{}
+@defmac destructuring-bind arglist expr forms@dots{}
 This macro expands to code which executes @var{forms}, with
 the variables in @var{arglist} bound to the list of values
 returned by @var{expr}.  The @var{arglist} can include all
 the features allowed for @code{defmacro} argument lists,
 including destructuring.  (The @code{&environment} keyword
 is not allowed.)  The macro expansion will signal an error
 if @var{expr} returns a list of the wrong number of arguments
 or with incorrect keyword arguments.
-@end deffn
+@end defmac
 This package also includes the Common Lisp @code{define-compiler-macro}
 facility, which allows you to define compile-time expansions and
 optimizations for your functions.
-@deffn {Special Operator} define-compiler-macro name arglist forms@dots{}
+@defmac define-compiler-macro name arglist forms@dots{}
 This form is similar to @code{defmacro}, except that it only expands
 calls to @var{name} at compile-time; calls processed by the Lisp
 interpreter are not expanded, nor are they expanded by the
 @code{macroexpand} function.
 is a non-floating-point constant; if @var{a} is anything else, or
 if there are any keyword arguments in the call, then the original
 @code{member*} call is left intact.  (The actual compiler macro
 for @code{member*} optimizes a number of other cases, including
 common @code{:test} predicates.)
-@end deffn
+@end defmac
 @defun compiler-macroexpand form
 This function is analogous to @code{macroexpand}, except that it
 expands compiler macros rather than regular macros.  It returns
 @var{form} unchanged if it is not a call to a function for which
 This function records a ``global'' declaration specified by
 @var{decl-spec}.  Since @code{proclaim} is a function, @var{decl-spec}
 is evaluated and thus should normally be quoted.
 @end defun
-@deffn {Special Operator} declaim decl-specs@dots{}
+@defmac declaim decl-specs@dots{}
 This macro is like @code{proclaim}, except that it takes any number
 of @var{decl-spec} arguments, and the arguments are unevaluated and
 unquoted.  The @code{declaim} macro also puts an @code{(eval-when
 (compile load eval) ...)} around the declarations so that they will
 be registered at compile-time as well as at run-time.  (This is vital,
 since normally the declarations are meant to influence the way the
 compiler treats the rest of the file that contains the @code{declaim}
 form.)
-@end deffn
+@end defmac
-@deffn {Special Operator} declare decl-specs@dots{}
+@defmac declare decl-specs@dots{}
 This macro is used to make declarations within functions and other
 code.  Common Lisp allows declarations in various locations, generally
 at the beginning of any of the many ``implicit @code{progn}s''
 throughout Lisp syntax, such as function bodies, @code{let} bodies,
 etc.  Currently the only declaration understood by @code{declare}
 is @code{special}.
-@end deffn
+@end defmac
-@deffn {Special Operator} locally declarations@dots{} forms@dots{}
+@defmac locally declarations@dots{} forms@dots{}
 In this package, @code{locally} is no different from @code{progn}.
-@end deffn
+@end defmac
-@deffn {Special Operator} the type form
+@defmac the type form
 Type information provided by @code{the} is ignored in this package;
 in other words, @code{(the @var{type} @var{form})} is equivalent
 to @var{form}.  Future versions of the optimizing byte-compiler may
 make use of this information.
 unless it knows whether the sequence will be a list or an array ahead
 of time.  With @code{(mapcar 'car (the vector foo))}, a future
 compiler would have enough information to expand the loop in-line.
 For now, Emacs Lisp will treat the above code as exactly equivalent
 to @code{(mapcar 'car foo)}.
-@end deffn
+@end defmac
 Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or
 @code{declare} should be a list beginning with a symbol that says
 what kind of declaration it is.  This package currently understands
 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
 When not used as a @code{setf} form, @code{getf} is just a regular
 function and its @var{place} argument can actually be any Lisp
 expression.
 @end defun
-@deffn {Special Operator} remf place property
+@defmac remf place property
 This macro removes the property-value pair for @var{property} from
 the property list stored at @var{place}, which is any @code{setf}-able
 place expression.  It returns true if the property was found.  Note
 that if @var{property} happens to be first on the list, this will
 effectively do a @code{(setf @var{place} (cddr @var{place}))},
 whereas if it occurs later, this simply uses @code{setcdr} to splice
 out the property and value cells.
-@end deffn
+@end defmac
 @iftex
 @secno=2
 @end iftex
 from all existing Lisp types.  Since the underlying Emacs Lisp
 system provides no way to create new distinct types, this package
 implements structures as vectors (or lists upon request) with a
 special ``tag'' symbol to identify them.
-@deffn {Special Operator} defstruct name slots@dots{}
+@defmac defstruct name slots@dots{}
 The @code{defstruct} form defines a new structure type called
 @var{name}, with the specified @var{slots}.  (The @var{slots}
 may begin with a string which documents the structure type.)
 In the simplest case, @var{name} and each of the @var{slots}
 are symbols.  For example,
 with @code{nil} by the constructors and ignored otherwise.  If
 the type @code{:include}s another type, then @code{:initial-offset}
 specifies a number of slots to be skipped between the last slot
 of the included type and the first new slot.
 @end table
-@end deffn
+@end defmac
 Except as noted, the @code{defstruct} facility of this package is
 entirely compatible with that of Common Lisp.
 @iftex
 If the optimization property @code{speed} has been set to 3, and
 @code{safety} is less than 3, then the byte-compiler will optimize
 away the following assertions.  Because assertions might be optimized
 away, it is a bad idea for them to include side-effects.
-@deffn {Special Operator} assert test-form [show-args string args@dots{}]
+@defmac assert test-form [show-args string args@dots{}]
 This form verifies that @var{test-form} is true (i.e., evaluates to
 a non-@code{nil} value).  If so, it returns @code{nil}.  If the test
 is not satisfied, @code{assert} signals an error.
 A default error message will be supplied which includes @var{test-form}.
 This usage of @var{show-args} is a change to Common Lisp.  In
 true Common Lisp, the second argument gives a list of @var{places}
 which can be @code{setf}'d by the user before continuing from the
 error.
-@end deffn
+@end defmac
-@deffn {Special Operator} check-type place type &optional string
+@defmac check-type place type &optional string
 This form verifies that @var{place} evaluates to a value of type
 @var{type}.  If so, it returns @code{nil}.  If not, @code{check-type}
 signals a continuable @code{wrong-type-argument} error.  The default
 error message lists the erroneous value along with @var{type} and
 @var{place} themselves.  If @var{string} is specified, it is included in
 Note that as in Common Lisp, the first argument to @code{check-type}
 should be a @var{place} suitable for use by @code{setf}, because
 @code{check-type} signals a continuable error that allows the user to
 modify @var{place}, most simply by returning a value from the debugger.
-@end deffn
+@end defmac
 The following error-related macro is also defined:
-@deffn {Special Operator} ignore-errors forms@dots{}
+@defmac ignore-errors forms@dots{}
 This executes @var{forms} exactly like a @code{progn}, except that
 errors are ignored during the @var{forms}.  More precisely, if
 an error is signalled then @code{ignore-errors} immediately
 aborts execution of the @var{forms} and returns @code{nil}.
 If the @var{forms} complete successfully, @code{ignore-errors}
 returns the result of the last @var{form}.
-@end deffn
+@end defmac
 @node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top
 @appendix Efficiency Concerns
 @appendixsec Macros

Mercurial > hg > xemacs-beta

comparison man/cl.texi @ 5547:a46c5c8d6564