From 5887564d5b5c90a1bc2ff7c0a3412cb6f765d03e Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Sat, 27 Oct 2012 15:42:07 -0700 Subject: [PATCH] Move generalized variable documentation from misc/cl.texi to lispref * doc/lispref/variables.texi (Generalized Variables): New section, adapted from misc/cl.texi. * doc/lispref/elisp.texi (Top): Add Generalized Variables to menu. * doc/lispref/lists.texi (List Elements, List Variables): Mention generalized variables. * doc/misc/cl.texi (Control Structure): Update for setf now being in core. (Setf Extensions): Rename from Basic Setf. Move much of the former content to lispref/variables.texi. (Modify Macros): Move pop, push details to lispref/variables.texi. (Customizing Setf): Copyedits for setf etc being in core. (Modify Macros, Efficiency Concerns, Porting Common Lisp): Further namespaces updates. --- doc/lispref/ChangeLog | 6 + doc/lispref/elisp.texi | 1 + doc/lispref/lists.texi | 8 ++ doc/lispref/variables.texi | 103 ++++++++++++++++ doc/misc/ChangeLog | 10 ++ doc/misc/cl.texi | 235 +++++++++++++------------------------ 6 files changed, 209 insertions(+), 154 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 03922f2c02f..aea26248452 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,5 +1,11 @@ 2012-10-27 Glenn Morris + * variables.texi (Generalized Variables): New section, + adapted from misc/cl.texi. + * elisp.texi (Top): Add Generalized Variables to menu. + * lists.texi (List Elements, List Variables): + Mention generalized variables. + * lists.texi (List Elements): Typo fix. 2012-10-27 Chong Yidong diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 1d1dab8faac..06a2ebfcaf8 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -486,6 +486,7 @@ Variables * Variable Aliases:: Variables that are aliases for other variables. * Variables with Restricted Values:: Non-constant variables whose value can @emph{not} be an arbitrary Lisp object. +* Generalized Variables:: Extending the concept of variables. Scoping Rules for Variable Bindings diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index eaef8cc1f8a..09948caaa13 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -236,6 +236,10 @@ This is in contrast to @code{cdr}, which signals an error if @defmac pop listname This macro is a way of examining the @sc{car} of a list, and taking it off the list, all at once. +@c FIXME I don't think is a particularly good way to do it, +@c but generalized variables have not been introduced yet. +(In fact, this macro can act on generalized variables, not just lists. +@xref{Generalized Variables}.) It operates on the list which is stored in the symbol @var{listname}. It removes this element from the list by setting @var{listname} @@ -682,6 +686,10 @@ to modify a list which is stored in a variable. @defmac push newelt listname This macro provides an alternative way to write @code{(setq @var{listname} (cons @var{newelt} @var{listname}))}. +@c FIXME I don't think is a particularly good way to do it, +@c but generalized variables have not been introduced yet. +(In fact, this macro can act on generalized variables, not just lists. +@xref{Generalized Variables}.) @example (setq l '(a b)) diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 1c0abcb8e66..1ffb1f7ffcb 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -41,6 +41,7 @@ representing the variable. * Variable Aliases:: Variables that are aliases for other variables. * Variables with Restricted Values:: Non-constant variables whose value can @emph{not} be an arbitrary Lisp object. +* Generalized Variables:: Extending the concept of variables. @end menu @node Global Variables @@ -1946,3 +1947,105 @@ Attempting to assign them any other value will result in an error: (setq undo-limit 1000.0) @error{} Wrong type argument: integerp, 1000.0 @end example + +@c FIXME? Not sure this is the right place for this section. +@node Generalized Variables +@section Generalized Variables + +A @dfn{generalized variable} or @dfn{place form} is one of the many places +in Lisp memory where values can be stored. The simplest place form is +a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists, elements +of arrays, properties of symbols, and many other locations are also +places where Lisp values are stored. + +@c FIXME? Not sure this is a useful analogy... +Generalized variables are analogous to ``lvalues'' in the C +language, where @samp{x = a[i]} gets an element from an array +and @samp{a[i] = x} stores an element using the same notation. +Just as certain forms like @code{a[i]} can be lvalues in C, there +is a set of forms that can be generalized variables in Lisp. + +The @code{setf} macro is the most basic way to operate on generalized +variables. The @code{setf} form is like @code{setq}, except that it +accepts arbitrary place forms on the left side rather than just +symbols. For example, @code{(setf (car a) b)} sets the car of +@code{a} to @code{b}, doing the same operation as @code{(setcar a b)}, +but without having to remember two separate functions for setting and +accessing every type of place. + +@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}. +@end defmac + +The following Lisp forms will work as generalized variables, and +so may appear in the @var{place} argument of @code{setf}: + +@itemize +@item +A symbol naming a variable. In other words, @code{(setf x y)} is +exactly equivalent to @code{(setq x y)}, and @code{setq} itself is +strictly speaking redundant given that @code{setf} exists. Many +programmers continue to prefer @code{setq} for setting simple +variables, though, purely for stylistic or historical reasons. +The macro @code{(setf x y)} actually expands to @code{(setq x y)}, +so there is no performance penalty for using it in compiled code. + +@item +A call to any of the following standard Lisp functions: + +@smallexample +car cdr nth nthcdr +caar cadr cdar cddr +aref elt get gethash +symbol-function symbol-value symbol-plist +@end smallexample + +@item +The following Emacs-specific functions are also @code{setf}-able: + +@smallexample +default-value process-get +frame-parameter process-sentinel +terminal-parameter window-buffer +keymap-parent window-display-table +match-data window-dedicated-p +overlay-get window-hscroll +overlay-start window-parameter +overlay-end window-point +process-buffer window-start +process-filter +@end smallexample +@end itemize + +@noindent +Using any forms other than these in the @var{place} argument to +@code{setf} will signal an error. + +Note that for @code{nthcdr} and @code{getf}, the list argument +of the function must itself be a valid @var{place} form. For +example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself +to 7. +@c The use of @code{nthcdr} as a @var{place} form is an extension +@c to standard Common Lisp. + +@c FIXME I don't think is a particularly good way to do it, +@c but these macros are introduced before gvs are. +The macros @code{push} (@pxref{List Variables}) and @code{pop} +(@pxref{List Elements}) can manipulate generalized variables, +not just lists. @code{(pop @var{place})} 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. +@code{(push @var{x} @var{place})} 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. Note that @code{push} and @code{pop} on an @code{nthcdr} +place can be used to insert or delete at any position in a list. + +The @file{cl-lib} library defines various extensions for generalized +variables, including additional @code{setf} places. +@xref{Generalized Variables,,, cl, Common Lisp Extensions}. diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index a0cfd675f0a..d447b0ca1ff 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,13 @@ +2012-10-27 Glenn Morris + + * cl.texi (Control Structure): Update for setf now being in core. + (Setf Extensions): Rename from Basic Setf. Move much of the + former content to lispref/variables.texi. + (Modify Macros): Move pop, push details to lispref/variables.texi. + (Customizing Setf): Copyedits for setf etc being in core. + (Modify Macros, Efficiency Concerns, Porting Common Lisp): + Further namespaces updates. + 2012-10-26 Bastien Guerry * org.texi (Installation): Update the link to Org's ELPA. Also diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 9200958a1b5..aba3f244012 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -57,7 +57,7 @@ developing GNU and promoting software freedom.'' * Overview:: Basics, usage, etc. * Program Structure:: Arglists, @code{cl-eval-when}, @code{defalias}. * Predicates:: @code{cl-typep} and @code{cl-equalp}. -* Control Structure:: @code{setf}, @code{cl-do}, @code{cl-loop}, etc. +* Control Structure:: @code{cl-do}, @code{cl-loop}, etc. * Macros:: Destructuring, @code{cl-define-compiler-macro}. * Declarations:: @code{cl-proclaim}, @code{cl-declare}, etc. * Symbols:: Property lists, @code{cl-gensym}. @@ -801,17 +801,16 @@ In Emacs, use @code{memq} (or @code{cl-member}) and @code{assq} (or @noindent The features described in the following sections implement -various advanced control structures, including the powerful -@c FIXME setf is now in gv.el, not cl. -@code{setf} facility and a number of looping and conditional +various advanced control structures, including extensions to the +standard @code{setf} facility, and a number of looping and conditional constructs. -@c FIXME setf, push are standard now. +@c FIXME @c lexical-let is obsolete; flet is not cl-flet. @c values is not cl-values. @menu * Assignment:: The @code{cl-psetq} form. -* Generalized Variables:: @code{setf}, @code{cl-incf}, @code{push}, etc. +* Generalized Variables:: Extensions to generalized variables. * Variable Bindings:: @code{cl-progv}, @code{lexical-let}, @code{flet}, @code{cl-macrolet}. * Conditionals:: @code{cl-case}, @code{cl-typecase}. * Blocks and Exits:: @code{cl-block}, @code{cl-return}, @code{cl-return-from}. @@ -857,130 +856,74 @@ provides an even more convenient way to swap two variables; @code{cl-psetq} always returns @code{nil}. @end defspec -@c FIXME now in gv.el. @node Generalized Variables @section Generalized Variables -@noindent -A ``generalized variable'' or ``place form'' is one of the many places -in Lisp memory where values can be stored. The simplest place form is -a regular Lisp variable. But the cars and cdrs of lists, elements -of arrays, properties of symbols, and many other locations are also -places where Lisp values are stored. - -The @code{setf} form is like @code{setq}, except that it accepts -arbitrary place forms on the left side rather than just -symbols. For example, @code{(setf (car a) b)} sets the car of -@code{a} to @code{b}, doing the same operation as @code{(setcar a b)} -but without having to remember two separate functions for setting -and accessing every type of place. - -Generalized variables are analogous to ``lvalues'' in the C -language, where @samp{x = a[i]} gets an element from an array -and @samp{a[i] = x} stores an element using the same notation. -Just as certain forms like @code{a[i]} can be lvalues in C, there -is a set of forms that can be generalized variables in Lisp. +A @dfn{generalized variable} or @dfn{place form} is one of the many +places in Lisp memory where values can be stored. The simplest place +form is a regular Lisp variable. But the cars and cdrs of lists, +elements of arrays, properties of symbols, and many other locations +are also places where Lisp values are stored. For basic information, +@pxref{Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}. +This package provides several additional features related to +generalized variables. @menu -* Basic Setf:: @code{setf} and place forms. -* Modify Macros:: @code{cl-incf}, @code{push}, @code{cl-rotatef}, @code{letf}, @code{cl-callf}, etc. +* Setf Extensions:: Additional @code{setf} places. +* Modify Macros:: @code{cl-incf}, @code{cl-rotatef}, @code{letf}, @code{cl-callf}, etc. * Customizing Setf:: @code{define-modify-macro}, @code{defsetf}, @code{define-setf-method}. @end menu -@node Basic Setf -@subsection Basic Setf - -@noindent -The @code{setf} macro is the most basic way to operate on generalized -variables. - -@defspec 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}. - -The following Lisp forms will work as generalized variables, and -so may appear in the @var{place} argument of @code{setf}: +@node Setf Extensions +@subsection Setf Extensions -@itemize @bullet -@item -A symbol naming a variable. In other words, @code{(setf x y)} is -exactly equivalent to @code{(setq x y)}, and @code{setq} itself is -strictly speaking redundant now that @code{setf} exists. Many -programmers continue to prefer @code{setq} for setting simple -variables, though, purely for stylistic or historical reasons. -The macro @code{(setf x y)} actually expands to @code{(setq x y)}, -so there is no performance penalty for using it in compiled code. +Several standard (e.g. @code{car}) and Emacs-specific +(e.g. @code{window-point}) Lisp functions are @code{setf}-able by default. +This package defines @code{setf} handlers for several additional functions: +@itemize @item -A call to any of the following Lisp functions: - +Functions from @code{CL} itself: @smallexample -car cdr caar .. cddddr -nth rest first .. tenth -aref elt nthcdr -symbol-function symbol-value symbol-plist -get get* getf -gethash subseq +cl-caaar .. cl-cddddr cl-first .. cl-tenth +cl-rest cl-get cl-getf cl-subseq @end smallexample -@noindent -Note that for @code{nthcdr} and @code{getf}, the list argument -of the function must itself be a valid @var{place} form. For -example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself -to 7. Note that @code{push} and @code{pop} on an @code{nthcdr} -place can be used to insert or delete at any position in a list. -The use of @code{nthcdr} as a @var{place} form is an extension -to standard Common Lisp. - @item -The following Emacs-specific functions are also @code{setf}-able. - +General Emacs Lisp functions: @smallexample -buffer-file-name marker-position -buffer-modified-p match-data -buffer-name mouse-position -buffer-string overlay-end -buffer-substring overlay-get -current-buffer overlay-start -current-case-table point -current-column point-marker -current-global-map point-max -current-input-mode point-min -current-local-map process-buffer -current-window-configuration process-filter -default-file-modes process-sentinel -default-value read-mouse-position -documentation-property screen-height -extent-data screen-menubar -extent-end-position screen-width -extent-start-position selected-window -face-background selected-screen -face-background-pixmap selected-frame -face-font standard-case-table -face-foreground syntax-table -face-underline-p window-buffer -file-modes window-dedicated-p -frame-height window-display-table -frame-parameters window-height -frame-visible-p window-hscroll -frame-width window-point -get-register window-start -getenv window-width -global-key-binding x-get-secondary-selection -keymap-parent x-get-selection -local-key-binding -mark -mark-marker +buffer-file-name getenv +buffer-modified-p global-key-binding +buffer-name local-key-binding +buffer-string mark +buffer-substring mark-marker +current-buffer marker-position +current-case-table mouse-position +current-column point +current-global-map point-marker +current-input-mode point-max +current-local-map point-min +current-window-configuration read-mouse-position +default-file-modes screen-height +documentation-property screen-width +face-background selected-window +face-background-pixmap selected-screen +face-font selected-frame +face-foreground standard-case-table +face-underline-p syntax-table +file-modes visited-file-modtime +frame-height window-height +frame-parameters window-width +frame-visible-p x-get-secondary-selection +frame-width x-get-selection +get-register @end smallexample Most of these have directly corresponding ``set'' functions, like @code{use-local-map} for @code{current-local-map}, or @code{goto-char} for @code{point}. A few, like @code{point-min}, expand to longer -sequences of code when they are @code{setf}'d (@code{(narrow-to-region -x (point-max))} in this case). +sequences of code when they are used with @code{setf} +(@code{(narrow-to-region x (point-max))} in this case). @item A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])}, @@ -1007,6 +950,8 @@ a The generalized variable @code{buffer-substring}, listed above, also works in this way by replacing a portion of the current buffer. +@c FIXME? Also `eq'? (see cl-lib.el) + @item A call of the form @code{(apply '@var{func} @dots{})} or @code{(apply (function @var{func}) @dots{})}, where @var{func} @@ -1025,9 +970,9 @@ Any form for which a @code{defsetf} or @code{define-setf-method} has been made. @end itemize -Using any forms other than these in the @var{place} argument to -@code{setf} will signal an error. - +@c FIXME should this be in lispref? It seems self-evident. +@c Contrast with the cl-incf example later on. +@c Here it really only serves as a constrast to wrong-order. The @code{setf} macro takes care to evaluate all subforms in the proper left-to-right order; for example, @@ -1056,15 +1001,14 @@ will be preserved. Adapting an example from Steele, given 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 defspec @node Modify Macros @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. +This package defines a number of macros that operate on generalized +variables. Many are interesting and useful even when the @var{place} +is just a variable name. @defspec cl-psetf [place form]@dots{} This macro is to @code{setf} what @code{cl-psetq} is to @code{setq}: @@ -1080,8 +1024,8 @@ by @var{x} if specified. The incremented value is returned. For example, @code{(cl-incf i)} is equivalent to @code{(setq i (1+ i))}, and @code{(cl-incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}. -Once again, care is taken to preserve the ``apparent'' order of -evaluation. For example, +As with @code{setf}, care is taken to preserve the ``apparent'' order +of evaluation. For example, @example (cl-incf (aref vec (cl-incf i))) @@ -1120,21 +1064,6 @@ This macro decrements the number stored in @var{place} by one, or by @var{x} if specified. @end defspec -@c FIXME move to lispref, add generalized variables. -@defspec 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 defspec - -@c FIXME move to lispref, add generalized variables. -@defspec 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 defspec - @defspec cl-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 @@ -1143,19 +1072,19 @@ are interpreted in the same way as for @code{cl-adjoin}. @xref{Lists as Sets}. @end defspec -@defspec shiftf place@dots{} newvalue +@defspec cl-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} +the first @var{place}. Thus, @code{(cl-shiftf @var{a} @var{b} @var{c} @var{d})} is equivalent to @example (prog1 @var{a} - (psetf @var{a} @var{b} - @var{b} @var{c} - @var{c} @var{d})) + (cl-psetf @var{a} @var{b} + @var{b} @var{c} + @var{c} @var{d})) @end example @noindent @@ -1168,10 +1097,10 @@ This macro rotates the @var{place}s left by one in circular fashion. Thus, @code{(cl-rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to @example -(psetf @var{a} @var{b} - @var{b} @var{c} - @var{c} @var{d} - @var{d} @var{a}) +(cl-psetf @var{a} @var{b} + @var{b} @var{c} + @var{c} @var{d} + @var{d} @var{a}) @end example @noindent @@ -1318,9 +1247,8 @@ Most of the modify macros defined by Common Lisp do not exactly follow the pattern of @code{define-modify-macro}. For example, @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. +using @code{get-setf-method}, or consult the source +to see how to use the internal @code{setf} building blocks. @end defspec @defspec defsetf access-fn update-fn @@ -4708,32 +4636,31 @@ user to modify @var{place}. @noindent Many of the advanced features of this package, such as @code{cl-defun}, -@code{cl-loop}, and @code{setf}, are implemented as Lisp macros. In +@code{cl-loop}, etc., are implemented as Lisp macros. In byte-compiled code, these complex notations will be expanded into equivalent Lisp code which is simple and efficient. For example, -the forms +the form @example (cl-incf i n) -(push x (car p)) @end example @noindent -are expanded at compile-time to the Lisp forms +is expanded at compile-time to the Lisp form @example (setq i (+ i n)) -(setcar p (cons x (car p))) @end example @noindent -which are the most efficient ways of doing these respective operations +which is the most efficient ways of doing this operation in Lisp. Thus, there is no performance penalty for using the more -readable @code{cl-incf} and @code{push} forms in your compiled code. +readable @code{cl-incf} form in your compiled code. @emph{Interpreted} code, on the other hand, must expand these macros every time they are executed. For this reason it is strongly recommended that code making heavy use of macros be compiled. +@c FIXME why are they not labelled as macros? (The features labeled ``Special Form'' instead of ``Function'' in this manual are macros.) A loop using @code{cl-incf} a hundred times will execute considerably faster if compiled, and will also @@ -4751,7 +4678,7 @@ all Lisp macros which appear in the form. The easiest way to use this function is to go to the @file{*scratch*} buffer and type, say, @example -(cl-prettyexpand '(loop for x below 10 collect x)) +(cl-prettyexpand '(cl-loop for x below 10 collect x)) @end example @noindent @@ -5104,7 +5031,7 @@ these forms: @example (let ((total 0)) (dolist (x my-list) (cl-incf total x)) total) -(loop for x in my-list sum x) +(cl-loop for x in my-list sum x) @end example While this would be mainly a stylistic choice in most Common Lisps, -- 2.39.5