commit: Avoid calling various macros "special operators" in the manuals.

changeset: 5547:a46c5c8d6564 tag: tip user: Aidan Kehoe <kehoea(a)parhasard.net&gt; date: Tue Aug 09 17:17:44 2011 +0100 files: man/ChangeLog man/cl.texi man/lispref/compile.texi man/lispref/eval.texi man/lispref/frames.texi man/lispref/internationalization.texi man/lispref/positions.texi man/lispref/searching.texi man/lispref/specifiers.texi man/lispref/windows.texi description: Avoid calling various macros "special operators" in the manuals. 2011-08-09 Aidan Kehoe <kehoea(a)parhasard.net&gt; * 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. diff -r d54278e74d71 -r a46c5c8d6564 man/ChangeLog --- a/man/ChangeLog Mon Aug 08 23:10:47 2011 +0900 +++ b/man/ChangeLog Tue Aug 09 17:17:44 2011 +0100 ＠＠ -1,3 +1,39 ＠＠ +2011-08-09 Aidan Kehoe <kehoea(a)parhasard.net&gt; + + * 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. + 2011-08-08 Stephen J. Turnbull <stephen(a)xemacs.org&gt; * internals/internals.texi (Mercurial Techniques): New. diff -r d54278e74d71 -r a46c5c8d6564 man/cl.texi --- a/man/cl.texi Mon Aug 08 23:10:47 2011 +0900 +++ b/man/cl.texi Tue Aug 09 17:17:44 2011 +0100 ＠＠ -381,14 +381,14 ＠＠ 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 - -＠deffn {Special Operator} defsubst* name arglist body... +＠end defmac + +＠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. ＠＠ -398,9 +398,9 ＠＠ 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 - -＠deffn {Special Operator} defmacro* name arglist body... +＠end defmac + +＠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 ＠＠ -409,13 +409,13 ＠＠ cannot be implemented with the current Emacs Lisp interpreter. The macro expander body is enclosed in an implicit block called ＠var{name}. -＠end deffn - -＠deffn {Special Operator} function* symbol-or-lambda +＠end defmac + +＠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 ＠＠ -606,7 +606,7 ＠＠ 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 ＠＠ -678,7 +678,7 ＠＠ 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 ＠＠ -690,7 +690,7 ＠＠ 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 ＠＠ -699,9 +699,9 ＠＠ or other reasons. This form is similar to the ＠samp{#.} syntax of true Common Lisp. -＠end deffn - -＠deffn {Special Operator} load-time-value form +＠end defmac + +＠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. ＠＠ -742,7 +742,7 ＠＠ ", and loaded on: " --temp--)) ＠end example -＠end deffn +＠end defmac ＠node Function Aliases, , Time of Evaluation, Program Structure ＠section Function Aliases ＠＠ -869,7 +869,7 ＠＠ 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 ＠＠ -897,7 +897,7 ＠＠ 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}, ＠＠ -989,7 +989,7 ＠＠ 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} ＠＠ -1017,7 +1017,7 ＠＠ ＠pxref{Modify Macros}.) ＠code{psetq} always returns ＠code{nil}. -＠end deffn +＠end defmac ＠node Generalized Variables, Variable Bindings, Assignment, Control Structure ＠section Generalized Variables ＠＠ -1055,7 +1055,7 ＠＠ 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 ＠＠ -1218,7 +1218,7 ＠＠ 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 ＠＠ -1228,15 +1228,15 ＠＠ 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 - -＠deffn {Special Operator} incf place &optional x +＠end defmac + +＠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 ＠＠ -1274,35 +1274,35 ＠＠ 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 - -＠deffn {Special Operator} decf place &optional x +＠end defmac + +＠defmac decf place &optional x This macro decrements the number stored in ＠var{place} by one, or by ＠var{x} if specified. -＠end deffn - -＠deffn {Special Operator} pop place +＠end defmac + +＠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 - -＠deffn {Special Operator} push x place +＠end defmac + +＠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 - -＠deffn {Special Operator} pushnew x place ＠t{&key :test :test-not :key} +＠end defmac + +＠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 - -＠deffn {Special Operator} shiftf place＠dots{} newvalue +＠end defmac + +＠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 ＠＠ -1320,9 +1320,9 ＠＠ ＠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 - -＠deffn {Special Operator} rotatef place＠dots{} +＠end defmac + +＠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 ＠＠ -1337,12 +1337,12 ＠＠ 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 ＠＠ -1392,14 +1392,14 ＠＠ 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 - -＠deffn {Special Operator} letf* (bindings＠dots{}) forms＠dots{} +＠end defmac + +＠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 - -＠deffn {Special Operator} callf ＠var{function} ＠var{place} ＠var{args}＠dots{} +＠end defmac + +＠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 ＠＠ -1416,14 +1416,14 ＠＠ ＠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 - -＠deffn {Special Operator} callf2 ＠var{function} ＠var{arg1} ＠var{place} ＠var{args}＠dots{} +＠end defmac + +＠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 ＠＠ -1439,7 +1439,7 ＠＠ ＠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 ＠＠ -1480,9 +1480,9 ＠＠ 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 - -＠deffn {Special Operator} defsetf access-fn update-fn +＠end defmac + +＠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 ＠＠ -1525,9 +1525,9 ＠＠ (defsetf symbol-value set) (defsetf buffer-name rename-buffer t) ＠end example -＠end deffn - -＠deffn {Special Operator} defsetf access-fn arglist (store-var) forms＠dots{} +＠end defmac + +＠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 ＠＠ -1556,9 +1556,9 ＠＠ (defsetf nth (n x) (store) (list 'setcar (list 'nthcdr n x) store)) ＠end example -＠end deffn - -＠deffn {Special Operator} define-setf-method access-fn arglist forms＠dots{} +＠end defmac + +＠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 ＠＠ -1603,7 +1603,7 ＠＠ 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 ＠＠ -1669,7 +1669,7 ＠＠ 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 ＠＠ -1679,7 +1679,7 ＠＠ 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 ＠＠ -1688,7 +1688,7 ＠＠ 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 ＠＠ -1788,12 +1788,12 ＠＠ The ＠code{lexical-let} form is an extension to Common Lisp. In true Common Lisp, all bindings are lexical unless declared otherwise. -＠end deffn - -＠deffn {Special Operator} lexical-let* (bindings＠dots{}) forms＠dots{} +＠end defmac + +＠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 ＠＠ -1802,7 +1802,7 ＠＠ 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} ＠＠ -1841,14 +1841,14 ＠＠ 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 - -＠deffn {Special Operator} labels (bindings＠dots{}) forms＠dots{} +＠end defmac + +＠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 ＠＠ -1856,7 +1856,7 ＠＠ ＠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, ＠＠ -1868,9 +1868,9 ＠＠ affect only calls that appear physically within the body ＠var{forms}, possibly after expansion of other macros in the body. -＠end deffn - -＠deffn {Special Operator} symbol-macrolet (bindings＠dots{}) forms＠dots{} +＠end defmac + +＠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})}; ＠＠ -1935,7 +1935,7 ＠＠ ＠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 ＠＠ -1944,7 +1944,7 ＠＠ 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, ＠＠ -1958,9 +1958,9 ＠＠ ＠example (if ＠var{test} (progn ＠var{a} ＠var{b} ＠var{c}) nil) ＠end example -＠end deffn - -＠deffn {Special Operator} unless test forms＠dots{} +＠end defmac + +＠defmac unless test forms＠dots{} This is a variant of ＠code{if} where there are no ``then'' forms, and possibly several ``else'' forms: ＠＠ -1974,9 +1974,9 ＠＠ ＠example (when (not ＠var{test}) ＠var{a} ＠var{b} ＠var{c}) ＠end example -＠end deffn - -＠deffn {Special Operator} case keyform clause＠dots{} +＠end defmac + +＠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 ＠＠ -2010,15 +2010,15 ＠＠ ((?\r ?\n) (do-ret-thing)) (t (do-other-thing))) ＠end example -＠end deffn - -＠deffn {Special Operator} ecase keyform clause＠dots{} +＠end defmac + +＠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 - -＠deffn {Special Operator} typecase keyform clause＠dots{} +＠end defmac + +＠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}, ＠＠ -2035,13 +2035,13 ＠＠ 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 - -＠deffn {Special Operator} etypecase keyform clause＠dots{} +＠end defmac + +＠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 ＠＠ -2054,7 +2054,7 ＠＠ 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. ＠＠ -2093,20 +2093,20 ＠＠ 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 - -＠deffn {Special Operator} return-from name [result] +＠end defmac + +＠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 - -＠deffn {Special Operator} return [result] +＠end defmac + +＠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 ＠＠ -2116,7 +2116,7 ＠＠ 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 ＠＠ -2144,9 +2144,9 ＠＠ (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 - -＠deffn {Special Operator} do (spec＠dots{}) (end-test [result＠dots{}]) forms＠dots{} +＠end defmac + +＠defmac do (spec＠dots{}) (end-test [result＠dots{}]) forms＠dots{} This macro creates a general iterative loop. Each ＠var{spec} is of the form ＠＠ -2192,9 +2192,9 ＠＠ ((or (null x) (null y)) (nreverse z))) ＠end example -＠end deffn - -＠deffn {Special Operator} do* (spec＠dots{}) (end-test [result＠dots{}]) forms＠dots{} +＠end defmac + +＠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 ＠＠ -2212,18 +2212,18 ＠＠ (nreverse z)) (push (f x y) z)) ＠end example -＠end deffn - -＠deffn {Special Operator} dolist (var list [result]) forms＠dots{} +＠end defmac + +＠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 - -＠deffn {Special Operator} dotimes (var count [result]) forms＠dots{} +＠end defmac + +＠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 ＠＠ -2231,9 +2231,9 ＠＠ 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 - -＠deffn {Special Operator} do-symbols (var [obarray [result]]) forms＠dots{} +＠end defmac + +＠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 ＠＠ -2241,12 +2241,12 ＠＠ 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 - -＠deffn {Special Operator} do-all-symbols (var [result]) forms＠dots{} +＠end defmac + +＠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. ＠＠ -2286,7 +2286,7 ＠＠ 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}, ＠＠ -2325,7 +2325,7 ＠＠ (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. ＠＠ -3003,7 +3003,7 ＠＠ 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 ＠＠ -3012,13 +3012,13 ＠＠ 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 ＠＠ -3052,7 +3052,7 ＠＠ ＠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 ＠＠ -3094,7 +3094,7 ＠＠ 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 ＠＠ -3103,22 +3103,22 ＠＠ 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 - -＠deffn {Special Operator} declare decl-specs＠dots{} +＠end defmac + +＠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 - -＠deffn {Special Operator} locally declarations＠dots{} forms＠dots{} +＠end defmac + +＠defmac locally declarations＠dots{} forms＠dots{} In this package, ＠code{locally} is no different from ＠code{progn}. -＠end deffn - -＠deffn {Special Operator} the type form +＠end defmac + +＠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 ＠＠ -3131,7 +3131,7 ＠＠ 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 ＠＠ -3313,7 +3313,7 ＠＠ 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 ＠＠ -3321,7 +3321,7 ＠＠ 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 ＠＠ -4677,7 +4677,7 ＠＠ 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.) ＠＠ -4984,7 +4984,7 ＠＠ 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. ＠＠ -5007,7 +5007,7 ＠＠ 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. ＠＠ -5030,9 +5030,9 ＠＠ 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 - -＠deffn {Special Operator} check-type place type &optional string +＠end defmac + +＠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 ＠＠ -5051,18 +5051,18 ＠＠ 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 diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/compile.texi --- a/man/lispref/compile.texi Mon Aug 08 23:10:47 2011 +0900 +++ b/man/lispref/compile.texi Tue Aug 09 17:17:44 2011 +0100 ＠＠ -691,7 +691,7 ＠＠ These features permit you to write code to be evaluated during compilation of a program. -＠deffn {Special Operator} eval-and-compile body +＠defmac eval-and-compile body This form marks ＠var{body} to be evaluated both when you compile the containing code and when you run it (whether compiled or not). ＠＠ -699,9 +699,9 ＠＠ and referring to that file with ＠code{require}. Using ＠code{require} is preferable if there is a substantial amount of code to be executed in this way. -＠end deffn +＠end defmac -＠deffn {Special Operator} eval-when-compile body +＠defmac eval-when-compile body This form marks ＠var{body} to be evaluated at compile time and not when the compiled program is loaded. The result of evaluation by the compiler becomes a constant which appears in the compiled program. When ＠＠ -712,7 +712,7 ＠＠ ＠code{(eval-when (compile eval) ＠dots{})}. Elsewhere, the Common Lisp ＠samp{#.} reader macro (but not when interpreting) is closer to what ＠code{eval-when-compile} does. -＠end deffn +＠end defmac ＠node Compiled-Function Objects ＠section Compiled-Function Objects diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/eval.texi --- a/man/lispref/eval.texi Mon Aug 08 23:10:47 2011 +0900 +++ b/man/lispref/eval.texi Tue Aug 09 17:17:44 2011 +0100 ＠＠ -743,21 +743,21 ＠＠ values. ＠end defun -＠deffn {Special Operator} multiple-value-bind (var＠dots{}) values-form forms＠dots{} -This special operator evaluates ＠var{values-form}, which may return +＠defmac multiple-value-bind (var＠dots{}) values-form forms＠dots{} +This macro evaluates ＠var{values-form}, which may return multiple values. It then binds the ＠var{var}s to these respective values, as if by ＠code{let}, and then executes the body ＠var{forms}. If there are more ＠var{var}s than values, the extra ＠var{var}s are bound to ＠code{nil}. If there are fewer ＠var{var}s than values, the excess values are ignored. -＠end deffn +＠end defmac -＠deffn {Special Operator} multiple-value-setq (var＠dots{}) form -This special operator evaluates ＠var{form}, which may return multiple +＠defmac multiple-value-setq (var＠dots{}) form +This macro evaluates ＠var{form}, which may return multiple values. It then sets the ＠var{var}s to these respective values, as if by ＠code{setq}. Extra ＠var{var}s or values are treated the same as in ＠code{multiple-value-bind}. -＠end deffn +＠end defmac ＠deffn {Special Operator} multiple-value-call function forms＠dots{} This special operator evaluates function, discarding any multiple ＠＠ -767,10 +767,10 ＠＠ infrastructure, treating multiple values as intercalated lists. ＠end deffn -＠deffn {Special Operator} multiple-value-list form -This special operator evaluates ＠var{form} and returns a list of the +＠defmac multiple-value-list form +This macro evaluates ＠var{form} and returns a list of the multiple values given by it. -＠end deffn +＠end defmac ＠deffn {Special Operator} multiple-value-prog1 first body＠dots{} This special operator evaluates the form ＠var{first}, then the ＠＠ -779,12 +779,12 ＠＠ ＠code{prog1} always discards multiple values. ＠end deffn -＠deffn {Special Operator} nth-value n form -This special operator evaluates ＠var{form} and returns the ＠var{n}th +＠defmac nth-value n form +This macro evaluates ＠var{form} and returns the ＠var{n}th value it gave. ＠var{n} must be an integer of value zero or more. If ＠var{form} gave insufficient multiple values, ＠code{nth-value} returns ＠code{nil}. -＠end deffn +＠end defmac ＠defvar multiple-values-limit This constant describes the exclusive upper bound on the number of diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/frames.texi --- a/man/lispref/frames.texi Mon Aug 08 23:10:47 2011 +0900 +++ b/man/lispref/frames.texi Tue Aug 09 17:17:44 2011 +0100 ＠＠ -785,18 +785,18 ＠＠ ＠code{focus-follows-mouse}. ＠end defun -＠deffn {Special Operator} save-selected-frame forms＠dots{} -This special operator records the selected frame, executes ＠var{forms} in +＠defmac save-selected-frame forms＠dots{} +This macro records the selected frame, executes ＠var{forms} in sequence, then restores the earlier selected frame. The value returned is the value of the last form. -＠end deffn +＠end defmac -＠deffn {Special Operator} with-selected-frame frame forms＠dots{} -This special operator records the selected frame, then selects ＠var{frame} +＠defmac with-selected-frame frame forms＠dots{} +This macro records the selected frame, then selects ＠var{frame} and executes ＠var{forms} in sequence. After the last form is finished, the earlier selected frame is restored. The value returned is the value of the last form. -＠end deffn +＠end defmac ＠ignore (FSF Emacs, continued from defun select-frame) XEmacs cooperates with the X server and the window managers by arranging diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/internationalization.texi --- a/man/lispref/internationalization.texi Mon Aug 08 23:10:47 2011 +0900 +++ b/man/lispref/internationalization.texi Tue Aug 09 17:17:44 2011 +0100 ＠＠ -83,8 +83,8 ＠＠ nothing. ＠end defun -＠deffn {Special Operator} domain string -This function specifies the text domain used for translating documentation +＠defmac domain string +This macro specifies the text domain used for translating documentation strings and interactive prompts of a function. For example, write: ＠example ＠＠ -94,7 +94,7 ＠＠ to specify ＠code{emacs-foo} as the text domain of the function ＠code{foo}. The ``call'' to ＠code{domain} is actually a declaration rather than a function; when actually called, ＠code{domain} just returns ＠code{nil}. -＠end deffn +＠end defmac ＠defun domain-of function This function returns the text domain of ＠var{function}; it returns diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/positions.texi --- a/man/lispref/positions.texi Mon Aug 08 23:10:47 2011 +0900 +++ b/man/lispref/positions.texi Tue Aug 09 17:17:44 2011 +0100 ＠＠ -818,21 +818,21 ＠＠ ＠code{save-current-buffer} is a primitive. ＠end deffn -＠deffn {Special Operator} with-current-buffer buffer forms＠dots{} +＠defmac with-current-buffer buffer forms＠dots{} This macro evaluates ＠var{forms} with ＠var{buffer} as the current buffer. It returns the value of the last form. -＠end deffn +＠end defmac -＠deffn {Special Operator} with-temp-file filename forms＠dots{} +＠defmac with-temp-file filename forms＠dots{} This macro creates a new buffer, evaluates ＠var{forms} there, and writes the buffer to ＠var{filename}. It returns the value of the last form evaluated. -＠end deffn +＠end defmac -＠deffn {Special Operator} save-selected-window forms＠dots{} +＠defmac save-selected-window forms＠dots{} This macro is similar to ＠code{save-excursion} but it saves and restores the selected window and nothing else. -＠end deffn +＠end defmac ＠node Narrowing ＠section Narrowing diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/searching.texi --- a/man/lispref/searching.texi Mon Aug 08 23:10:47 2011 +0900 +++ b/man/lispref/searching.texi Tue Aug 09 17:17:44 2011 +0100 ＠＠ -1458,10 +1458,10 ＠＠ You can save and restore the match data with ＠code{save-match-data}: -＠deffn {Special Operator} save-match-data body＠dots{} -This special operator executes ＠var{body}, saving and restoring the match +＠defmac save-match-data body＠dots{} +This macro executes ＠var{body}, saving and restoring the match data around it. -＠end deffn +＠end defmac Emacs automatically saves and restores the match data when it runs process filter functions (＠pxref{Filter Functions}) and process diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/specifiers.texi --- a/man/lispref/specifiers.texi Mon Aug 08 23:10:47 2011 +0900 +++ b/man/lispref/specifiers.texi Tue Aug 09 17:17:44 2011 +0100 ＠＠ -875,7 +875,7 ＠＠ ＠code{add-spec-list-to-specifier}. ＠end defun -＠deffn {Special Operator} let-specifier specifier-list &rest body +＠defmac let-specifier specifier-list &rest body This macro temporarily adds specifications to specifiers, evaluates forms in ＠var{body} and restores the specifiers to their previous states. The specifiers and their temporary specifications are ＠＠ -912,7 +912,7 ＠＠ (let-specifier ((modeline-shadow-thickness 0 (selected-window))) (sit-for 1)) ＠end example -＠end deffn +＠end defmac ＠defun set-specifier specifier value &optional locale tag-set how-to-add This function adds some specifications to ＠var{specifier}. ＠var{value} diff -r d54278e74d71 -r a46c5c8d6564 man/lispref/windows.texi --- a/man/lispref/windows.texi Mon Aug 08 23:10:47 2011 +0900 +++ b/man/lispref/windows.texi Tue Aug 09 17:17:44 2011 +0100 ＠＠ -442,12 +442,12 ＠＠ ＠end example ＠end defun -＠deffn {Special Operator} save-selected-window forms＠dots{} +＠defmac save-selected-window forms＠dots{} This macro records the selected window, executes ＠var{forms} in sequence, then restores the earlier selected window. It does not save or restore anything about the sizes, arrangement or contents of windows; therefore, if the ＠var{forms} change them, the changes are permanent. -＠end deffn +＠end defmac ＠cindex finding windows The following functions choose one of the windows on the screen, ＠＠ -1969,7 +1969,7 ＠＠ ＠end example ＠end defun -＠deffn {Special Operator} save-window-excursion forms＠dots{} +＠defmac save-window-excursion forms＠dots{} This macro records the window configuration, executes ＠var{forms} in sequence, then restores the earlier window configuration. The window configuration includes the value of point and the portion of the buffer ＠＠ -2005,7 +2005,7 ＠＠ ;; ＠r{The frame is now split again.} ＠end group ＠end example -＠end deffn +＠end defmac ＠defun window-configuration-p object This function returns ＠code{t} if ＠var{object} is a window configuration. _______________________________________________ XEmacs-Patches mailing list XEmacs-Patches(a)xemacs.org http://lists.xemacs.org/mailman/listinfo/xemacs-patches