Now on revision 110699. ------------------------------------------------------------ revno: 110699 committer: Glenn Morris branch nick: trunk timestamp: Sat 2012-10-27 19:34:36 -0700 message: More cl.texi updates * doc/misc/cl.texi (Multiple Values, Common Lisp Compatibility): More namespace updates. (Obsolete Features): Copyedits. (Obsolete Lexical Macros, Obsolete Setf Customization): New subsections. * etc/NEWS: Related edits. diff: === modified file 'doc/misc/ChangeLog' --- doc/misc/ChangeLog 2012-10-28 02:05:04 +0000 +++ doc/misc/ChangeLog 2012-10-28 02:34:36 +0000 @@ -1,5 +1,11 @@ 2012-10-28 Glenn Morris + * cl.texi (Multiple Values, Common Lisp Compatibility): + More namespace updates. + (Obsolete Features): Copyedits. + (Obsolete Lexical Macros, Obsolete Setf Customization): + New subsections. + * cl.texi (Porting Common Lisp, Lexical Bindings): Add some xrefs to the Elisp manual. === modified file 'doc/misc/cl.texi' --- doc/misc/cl.texi 2012-10-28 02:05:04 +0000 +++ doc/misc/cl.texi 2012-10-28 02:34:36 +0000 @@ -806,7 +806,7 @@ constructs. @c FIXME -@c flet is not cl-flet, values is not cl-values. +@c flet is not cl-flet. @menu * Assignment:: The @code{cl-psetq} form. * Generalized Variables:: Extensions to generalized variables. @@ -815,7 +815,7 @@ * Blocks and Exits:: @code{cl-block}, @code{cl-return}, @code{cl-return-from}. * Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}. * Loop Facility:: The Common Lisp @code{cl-loop} macro. -* Multiple Values:: @code{values}, @code{cl-multiple-value-bind}, etc. +* Multiple Values:: @code{cl-values}, @code{cl-multiple-value-bind}, etc. @end menu @node Assignment @@ -2660,7 +2660,7 @@ @code{get-setf-method}). This package @emph{does} define placeholders for the Common Lisp functions that work with multiple values, but in Emacs Lisp these functions simply operate on lists instead. -The @code{values} form, for example, is a synonym for @code{list} +The @code{cl-values} form, for example, is a synonym for @code{list} in Emacs. @defmac cl-multiple-value-bind (var@dots{}) values-form forms@dots{} @@ -4701,9 +4701,9 @@ The multiple-value return facility treats lists as multiple values, since Emacs Lisp cannot support multiple return values directly. The macros will be compatible with Common Lisp if -@code{values} or @code{values-list} is always used to return to +@code{cl-values} or @code{cl-values-list} is always used to return to a @code{cl-multiple-value-bind} or other multiple-value receiver; -if @code{values} is used without @code{cl-multiple-value-@dots{}} +if @code{cl-values} is used without @code{cl-multiple-value-@dots{}} or vice-versa the effect will be different from Common Lisp. Many Common Lisp declarations are ignored, and others match @@ -4927,11 +4927,15 @@ @appendix Obsolete Features This section describes some features of the package that are obsolete -and should not be used in new code. They are only provided by the old -@file{cl.el} entry point, not by the newer @file{cl-lib.el}. +and should not be used in new code. They are either only provided by +the old @file{cl.el} entry point, not by the newer @file{cl-lib.el}; +or where versions with a @samp{cl-} prefix do exist they do not behave +in exactly the same way. @menu -* Lexical Bindings:: An approximation of lexical binding. +* Lexical Bindings:: An approximation of lexical binding. +* Obsolete Lexical Macros:: Obsolete macros using lexical-let. +* Obsolete Setf Customization:: Obsolete ways to customize setf. @end menu @node Lexical Bindings @@ -5050,6 +5054,46 @@ are made sequentially in the manner of @code{let*}. @end defmac +@node Obsolete Lexical Macros +@appendixsec Macros Defined Using Lexical-Let + +The following macros are defined using @code{lexical-let}. +They are replaced by versions with a @samp{cl-} prefix that use true +lexical binding (and hence rely on @code{lexical-binding} being set to +@code{t} in code using them). + +@defmac flet (bindings@dots{}) forms@dots{} +Replaced by @code{cl-flet} (@pxref{Function Bindings}) +or @code{cl-letf} (@pxref{Modify Macros}). +@end defmac + +@defmac labels (bindings@dots{}) forms@dots{} +Replaced by @code{cl-labels} (@pxref{Function Bindings}). +@end defmac + +@defmac letf (bindings@dots{}) forms@dots{} +Replaced by @code{cl-letf} (@pxref{Modify Macros}). +@end defmac + +@node Obsolete Setf Customization +@appendixsec Obsolete Ways to Customize Setf + +This section describes some obsolete ways to extend @code{setf}. +They are replaced by @file{gv.el} in Emacs 24.3. + +@c FIXME. +@defmac define-setf-expander name arglist &rest body +Use @file{gv.el}. +@end defmac + +@defmac defsetf access-fn update-fn +Use @file{gv.el}. +@end defmac + +@defmac define-modify-macro name arglist function [doc-string] +Use @file{gv.el}. +@end defmac + @node GNU Free Documentation License @appendix GNU Free Documentation License === modified file 'etc/NEWS' --- etc/NEWS 2012-10-27 05:03:52 +0000 +++ etc/NEWS 2012-10-28 02:34:36 +0000 @@ -323,11 +323,17 @@ to the `lexical-let' machinery used previously) to capture definitions in closures, so such closures will only work if `lexical-binding' is in use. +*** `cl-letf' is not exactly like `letf'. + +++ *** `progv' was rewritten to use the `let' machinery. A side effect is that vars without corresponding value are bound to nil rather than making them unbound. +*** The following methods of extending `setf' are obsolete. +Use gv.el instead (FIXME; details). +`define-setf-expander', `defsetf', `define-modify-macro' + ** Compilation mode +++ *** New option `compilation-always-kill'. ------------------------------------------------------------ revno: 110698 committer: Glenn Morris branch nick: trunk timestamp: Sat 2012-10-27 19:05:04 -0700 message: Add some xrefs to cl.texi * doc/misc/cl.texi (Porting Common Lisp, Lexical Bindings): Add some xrefs to the Elisp manual. diff: === modified file 'doc/misc/ChangeLog' --- doc/misc/ChangeLog 2012-10-28 01:55:40 +0000 +++ doc/misc/ChangeLog 2012-10-28 02:05:04 +0000 @@ -1,5 +1,8 @@ 2012-10-28 Glenn Morris + * cl.texi (Porting Common Lisp, Lexical Bindings): + Add some xrefs to the Elisp manual. + * cl.texi (Lexical Bindings): Move to appendix of obsolete features. (Porting Common Lisp): Emacs Lisp can do true lexical binding now. (Obsolete Features): New appendix. Move Lexical Bindings here. === modified file 'doc/misc/cl.texi' --- doc/misc/cl.texi 2012-10-28 01:55:40 +0000 +++ doc/misc/cl.texi 2012-10-28 02:05:04 +0000 @@ -4754,9 +4754,11 @@ bindings apply only to references physically within their bodies (or within macro expansions in their bodies). Traditionally, Emacs Lisp uses @dfn{dynamic scoping} wherein a binding to a variable is visible -even inside functions called from the body. Lexical binding is -available since Emacs 24.1, so be sure to set @code{lexical-binding} -to @code{t} if you need to emulate this aspect of Common Lisp. +even inside functions called from the body. +@xref{Dynamic Binding,,,elisp,GNU Emacs Lisp Reference Manual}. +Lexical binding is available since Emacs 24.1, so be sure to set +@code{lexical-binding} to @code{t} if you need to emulate this aspect +of Common Lisp. @xref{Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}. Here is an example of a Common Lisp code fragment that would fail in Emacs Lisp if @code{lexical-binding} were set to @code{nil}: @@ -4969,7 +4971,8 @@ The most important use of lexical bindings is to create @dfn{closures}. A closure is a function object that refers to an outside lexical -variable. For example: +variable (@pxref{Closures,,,elisp,GNU Emacs Lisp Reference Manual}). +For example: @example (defun make-adder (n) ------------------------------------------------------------ revno: 110697 committer: Glenn Morris branch nick: trunk timestamp: Sat 2012-10-27 18:55:40 -0700 message: Start moving some cl.texi features to an Obsolete appendix * doc/misc/cl.texi (Lexical Bindings): Move to appendix of obsolete features. (Porting Common Lisp): Emacs Lisp can do true lexical binding now. (Obsolete Features): New appendix. Move Lexical Bindings here. diff: === modified file 'doc/misc/ChangeLog' --- doc/misc/ChangeLog 2012-10-27 22:54:53 +0000 +++ doc/misc/ChangeLog 2012-10-28 01:55:40 +0000 @@ -1,3 +1,9 @@ +2012-10-28 Glenn Morris + + * cl.texi (Lexical Bindings): Move to appendix of obsolete features. + (Porting Common Lisp): Emacs Lisp can do true lexical binding now. + (Obsolete Features): New appendix. Move Lexical Bindings here. + 2012-10-27 Glenn Morris * cl.texi: Use defmac for macros rather than defspec. === modified file 'doc/misc/cl.texi' --- doc/misc/cl.texi 2012-10-27 22:54:53 +0000 +++ doc/misc/cl.texi 2012-10-28 01:55:40 +0000 @@ -70,6 +70,7 @@ * Efficiency Concerns:: Hints and techniques. * Common Lisp Compatibility:: All known differences with Steele. * Porting Common Lisp:: Hints for porting Common Lisp code. +* Obsolete Features:: Obsolete features. * GNU Free Documentation License:: The license for this documentation. * Function Index:: @@ -210,7 +211,6 @@ by @code{cl--}. Here is a complete list of functions prefixed by @code{cl-} that were not taken from Common Lisp: -@c FIXME lexical-let lexical-let* @example cl-callf cl-callf2 cl-defsubst cl-floatp-safe cl-letf cl-letf* @@ -806,12 +806,11 @@ constructs. @c FIXME -@c lexical-let is obsolete; flet is not cl-flet. -@c values is not cl-values. +@c flet is not cl-flet, values is not cl-values. @menu * Assignment:: The @code{cl-psetq} form. * Generalized Variables:: Extensions to generalized variables. -* Variable Bindings:: @code{cl-progv}, @code{lexical-let}, @code{flet}, @code{cl-macrolet}. +* Variable Bindings:: @code{cl-progv}, @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}. * Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}. @@ -1422,7 +1421,6 @@ @menu * Dynamic Bindings:: The @code{cl-progv} form. -* Lexical Bindings:: @code{lexical-let} and lexical closures. * Function Bindings:: @code{flet} and @code{labels}. * Macro Bindings:: @code{cl-macrolet} and @code{cl-symbol-macrolet}. @end menu @@ -1447,120 +1445,6 @@ are ignored. @end defmac -@node Lexical Bindings -@subsection Lexical Bindings - -@noindent -The @code{CL} package defines the following macro which -more closely follows the Common Lisp @code{let} form: - -@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. - -@example -(setq a 5) -(defun foo (b) (+ a b)) -(let ((a 2)) (foo a)) - @result{} 4 -(lexical-let ((a 2)) (foo a)) - @result{} 7 -@end example - -@noindent -In this example, a regular @code{let} binding of @code{a} actually -makes a temporary change to the global variable @code{a}, so @code{foo} -is able to see the binding of @code{a} to 2. But @code{lexical-let} -actually creates a distinct local variable @code{a} for use within its -body, without any effect on the global variable of the same name. - -The most important use of lexical bindings is to create @dfn{closures}. -A closure is a function object that refers to an outside lexical -variable. For example: - -@example -(defun make-adder (n) - (lexical-let ((n n)) - (function (lambda (m) (+ n m))))) -(setq add17 (make-adder 17)) -(funcall add17 4) - @result{} 21 -@end example - -@noindent -The call @code{(make-adder 17)} returns a function object which adds -17 to its argument. If @code{let} had been used instead of -@code{lexical-let}, the function object would have referred to the -global @code{n}, which would have been bound to 17 only during the -call to @code{make-adder} itself. - -@example -(defun make-counter () - (lexical-let ((n 0)) - (cl-function (lambda (&optional (m 1)) (cl-incf n m))))) -(setq count-1 (make-counter)) -(funcall count-1 3) - @result{} 3 -(funcall count-1 14) - @result{} 17 -(setq count-2 (make-counter)) -(funcall count-2 5) - @result{} 5 -(funcall count-1 2) - @result{} 19 -(funcall count-2) - @result{} 6 -@end example - -@noindent -Here we see that each call to @code{make-counter} creates a distinct -local variable @code{n}, which serves as a private counter for the -function object that is returned. - -Closed-over lexical variables persist until the last reference to -them goes away, just like all other Lisp objects. For example, -@code{count-2} refers to a function object which refers to an -instance of the variable @code{n}; this is the only reference -to that variable, so after @code{(setq count-2 nil)} the garbage -collector would be able to delete this instance of @code{n}. -Of course, if a @code{lexical-let} does not actually create any -closures, then the lexical variables are free as soon as the -@code{lexical-let} returns. - -Many closures are used only during the extent of the bindings they -refer to; these are known as ``downward funargs'' in Lisp parlance. -When a closure is used in this way, regular Emacs Lisp dynamic -bindings suffice and will be more efficient than @code{lexical-let} -closures: - -@example -(defun add-to-list (x list) - (mapcar (lambda (y) (+ x y))) list) -(add-to-list 7 '(1 2 5)) - @result{} (8 9 12) -@end example - -@noindent -Since this lambda is only used while @code{x} is still bound, -it is not necessary to make a true closure out of it. - -You can use @code{defun} or @code{flet} inside a @code{lexical-let} -to create a named closure. If several closures are created in the -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 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 defmac - @node Function Bindings @subsection Function Bindings @@ -1650,6 +1534,10 @@ and macro-expander forms). The macro is defined accordingly for use within the body of the @code{cl-macrolet}. +@c FIXME this should be modified to say ``even when lexical-binding +@c is code{nil}'', but is that true? The doc of cl-macrolet just +@c refers us to cl-flet, which refers to cl-labels, which says that it +@c behaves differently according to whether l-b is true or not. Because of the nature of macros, @code{cl-macrolet} is lexically scoped even in Emacs Lisp: The @code{cl-macrolet} binding will affect only calls that appear physically within the body @@ -1678,8 +1566,10 @@ Likewise, a @code{let} or @code{let*} binding a symbol macro is treated like a @code{letf} or @code{cl-letf*}. This differs from true +@c FIXME does it work like this in Emacs with lexical-binding = t? Common Lisp, where the rules of lexical scoping cause a @code{let} binding to shadow a @code{cl-symbol-macrolet} binding. In this package, +@c FIXME obsolete. only @code{lexical-let} and @code{lexical-let*} will shadow a symbol macro. @@ -4861,19 +4751,15 @@ @item Lexical scoping. In Common Lisp, function arguments and @code{let} -bindings apply only to references physically within their bodies -(or within macro expansions in their bodies). Emacs Lisp, by -contrast, uses @dfn{dynamic scoping} wherein a binding to a -variable is visible even inside functions called from the body. - -Variables in Common Lisp can be made dynamically scoped by -declaring them @code{special} or using @code{defvar}. In Emacs -Lisp it is as if all variables were declared @code{special}. - -Often you can use code that was written for lexical scoping -even in a dynamically scoped Lisp, but not always. Here is -an example of a Common Lisp code fragment that would fail in -Emacs Lisp: +bindings apply only to references physically within their bodies (or +within macro expansions in their bodies). Traditionally, Emacs Lisp +uses @dfn{dynamic scoping} wherein a binding to a variable is visible +even inside functions called from the body. Lexical binding is +available since Emacs 24.1, so be sure to set @code{lexical-binding} +to @code{t} if you need to emulate this aspect of Common Lisp. + +Here is an example of a Common Lisp code fragment that would fail in +Emacs Lisp if @code{lexical-binding} were set to @code{nil}: @example (defun map-odd-elements (func list) @@ -4886,20 +4772,16 @@ @end example @noindent -In Common Lisp, the two functions' usages of @code{x} are completely -independent. In Emacs Lisp, the binding to @code{x} made by -@code{add-odd-elements} will have been hidden by the binding -in @code{map-odd-elements} by the time the @code{(+ a x)} function -is called. - -(This package avoids such problems in its own mapping functions -by using names like @code{cl--x} instead of @code{x} internally; -as long as you don't use this prefix for your own -variables no collision can occur.) - -@xref{Lexical Bindings}, for a description of the @code{lexical-let} -form which establishes a Common Lisp-style lexical binding, and some -examples of how it differs from Emacs's regular @code{let}. +With lexical binding, the two functions' usages of @code{x} are +completely independent. With dynamic binding, the binding to @code{x} +made by @code{add-odd-elements} will have been hidden by the binding +in @code{map-odd-elements} by the time the @code{(+ a x)} function is +called. + +Internally, this package uses lexical binding so that such problems do +not occur. @xref{Lexical Bindings}, for a description of the obsolete +@code{lexical-let} form that emulates a Common Lisp-style lexical +binding when dynamic binding is in use. @item Reader macros. Common Lisp includes a second type of macro that @@ -5039,6 +4921,133 @@ recursion. @end itemize +@node Obsolete Features +@appendix Obsolete Features + +This section describes some features of the package that are obsolete +and should not be used in new code. They are only provided by the old +@file{cl.el} entry point, not by the newer @file{cl-lib.el}. + +@menu +* Lexical Bindings:: An approximation of lexical binding. +@end menu + +@node Lexical Bindings +@appendixsec Lexical Bindings + +The following macros are extensions to Common Lisp, where all bindings +are lexical unless declared otherwise. These features are likewise +obsolete since the introduction of true lexical binding in Emacs 24.1. + +@defmac lexical-let (bindings@dots{}) forms@dots{} +This form is exactly like @code{let} except that the bindings it +establishes are purely lexical. +@end defmac + +@c FIXME remove this and refer to elisp manual. +@c Maybe merge some stuff from here to there? +@noindent +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. + +@example +(setq a 5) +(defun foo (b) (+ a b)) +(let ((a 2)) (foo a)) + @result{} 4 +(lexical-let ((a 2)) (foo a)) + @result{} 7 +@end example + +@noindent +In this example, a regular @code{let} binding of @code{a} actually +makes a temporary change to the global variable @code{a}, so @code{foo} +is able to see the binding of @code{a} to 2. But @code{lexical-let} +actually creates a distinct local variable @code{a} for use within its +body, without any effect on the global variable of the same name. + +The most important use of lexical bindings is to create @dfn{closures}. +A closure is a function object that refers to an outside lexical +variable. For example: + +@example +(defun make-adder (n) + (lexical-let ((n n)) + (function (lambda (m) (+ n m))))) +(setq add17 (make-adder 17)) +(funcall add17 4) + @result{} 21 +@end example + +@noindent +The call @code{(make-adder 17)} returns a function object which adds +17 to its argument. If @code{let} had been used instead of +@code{lexical-let}, the function object would have referred to the +global @code{n}, which would have been bound to 17 only during the +call to @code{make-adder} itself. + +@example +(defun make-counter () + (lexical-let ((n 0)) + (cl-function (lambda (&optional (m 1)) (cl-incf n m))))) +(setq count-1 (make-counter)) +(funcall count-1 3) + @result{} 3 +(funcall count-1 14) + @result{} 17 +(setq count-2 (make-counter)) +(funcall count-2 5) + @result{} 5 +(funcall count-1 2) + @result{} 19 +(funcall count-2) + @result{} 6 +@end example + +@noindent +Here we see that each call to @code{make-counter} creates a distinct +local variable @code{n}, which serves as a private counter for the +function object that is returned. + +Closed-over lexical variables persist until the last reference to +them goes away, just like all other Lisp objects. For example, +@code{count-2} refers to a function object which refers to an +instance of the variable @code{n}; this is the only reference +to that variable, so after @code{(setq count-2 nil)} the garbage +collector would be able to delete this instance of @code{n}. +Of course, if a @code{lexical-let} does not actually create any +closures, then the lexical variables are free as soon as the +@code{lexical-let} returns. + +Many closures are used only during the extent of the bindings they +refer to; these are known as ``downward funargs'' in Lisp parlance. +When a closure is used in this way, regular Emacs Lisp dynamic +bindings suffice and will be more efficient than @code{lexical-let} +closures: + +@example +(defun add-to-list (x list) + (mapcar (lambda (y) (+ x y))) list) +(add-to-list 7 '(1 2 5)) + @result{} (8 9 12) +@end example + +@noindent +Since this lambda is only used while @code{x} is still bound, +it is not necessary to make a true closure out of it. + +You can use @code{defun} or @code{flet} inside a @code{lexical-let} +to create a named closure. If several closures are created in the +body of a single @code{lexical-let}, they all close over the same +instance of the lexical variable. + +@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 defmac + + @node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi ------------------------------------------------------------ revno: 110696 committer: Glenn Morris branch nick: trunk timestamp: Sat 2012-10-27 17:16:55 -0700 message: * doc/emacs/ack.texi (Acknowledgments): Mention gv.el. diff: === modified file 'doc/emacs/ChangeLog' --- doc/emacs/ChangeLog 2012-10-27 11:06:08 +0000 +++ doc/emacs/ChangeLog 2012-10-28 00:16:55 +0000 @@ -1,3 +1,7 @@ +2012-10-28 Glenn Morris + + * ack.texi (Acknowledgments): Mention gv.el. + 2012-10-27 Bastien Guerry * screen.texi (Menu Bar): Fix typo. === modified file 'doc/emacs/ack.texi' --- doc/emacs/ack.texi 2012-09-30 09:18:38 +0000 +++ doc/emacs/ack.texi 2012-10-28 00:16:55 +0000 @@ -835,8 +835,9 @@ client for the ``Music Player Daemon''; @file{smie.el}, a generic indentation engine; and @file{pcase.el}, implementing ML-style pattern matching. In Emacs 24, he integrated the lexical binding code, -and cleaned up the CL namespace (making it acceptable to use CL -functions at runtime). +cleaned up the CL namespace (making it acceptable to use CL +functions at runtime), and added generalized variables to core Emacs +Lisp. @item Morioka Tomohiko wrote several packages for MIME support in Gnus and ------------------------------------------------------------ revno: 110695 committer: Glenn Morris branch nick: trunk timestamp: Sat 2012-10-27 15:54:53 -0700 message: * doc/misc/cl.texi: Use defmac for macros rather than defspec. (Efficiency Concerns): Related copyedit. diff: === modified file 'doc/misc/ChangeLog' --- doc/misc/ChangeLog 2012-10-27 22:42:07 +0000 +++ doc/misc/ChangeLog 2012-10-27 22:54:53 +0000 @@ -1,5 +1,8 @@ 2012-10-27 Glenn Morris + * cl.texi: Use defmac for macros rather than defspec. + (Efficiency Concerns): Related copyedit. + * 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. === modified file 'doc/misc/cl.texi' --- doc/misc/cl.texi 2012-10-27 22:42:07 +0000 +++ doc/misc/cl.texi 2012-10-27 22:54:53 +0000 @@ -268,14 +268,14 @@ Instead, this package defines alternates for several Lisp forms which you must use if you need Common Lisp argument lists. -@defspec cl-defun name arglist body... +@defmac cl-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 defspec +@end defmac -@defspec cl-defsubst name arglist body... +@defmac cl-defsubst name arglist body... This is just like @code{cl-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. @@ -285,9 +285,9 @@ efficient inline expansions. In particular, @code{cl-defsubst} arranges for the processing of keyword arguments, default values, etc., to be done at compile-time whenever possible. -@end defspec +@end defmac -@defspec cl-defmacro name arglist body... +@defmac cl-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 @@ -296,13 +296,13 @@ cannot be implemented with the current Emacs Lisp interpreter. The macro expander body is enclosed in an implicit block called @var{name}. -@end defspec +@end defmac -@defspec cl-function symbol-or-lambda +@defmac cl-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 defspec +@end defmac Also, all forms (such as @code{cl-flet} and @code{cl-labels}) defined in this package that include @var{arglist}s in their syntax allow @@ -491,7 +491,7 @@ at compile-time so that later parts of the file can refer to the macros that are defined. -@defspec cl-eval-when (situations...) forms... +@defmac cl-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 @@ -563,7 +563,7 @@ certain top-level forms, like @code{defmacro} (sort-of) and @code{require}, as if they were wrapped in @code{(cl-eval-when (compile load eval) @dots{})}. -@end defspec +@end defmac Emacs includes two special forms related to @code{cl-eval-when}. One of these, @code{eval-when-compile}, is not quite equivalent to @@ -573,7 +573,7 @@ equivalent to @samp{(cl-eval-when (compile load eval) @dots{})} and so is not itself defined by this package. -@defspec 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 @@ -582,9 +582,9 @@ or other reasons. This form is similar to the @samp{#.} syntax of true Common Lisp. -@end defspec +@end defmac -@defspec cl-load-time-value form +@defmac cl-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. @@ -625,7 +625,7 @@ ", and loaded on: " --temp--)) @end example -@end defspec +@end defmac @node Predicates @chapter Predicates @@ -733,7 +733,7 @@ error. @end defun -@defspec cl-deftype name arglist forms... +@defmac cl-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 @@ -761,7 +761,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 defspec +@end defmac The @code{cl-typecase} and @code{cl-check-type} macros also use type names. @xref{Conditionals}. @xref{Assertions}. The @code{cl-map}, @@ -826,7 +826,7 @@ The @code{cl-psetq} form is just like @code{setq}, except that multiple assignments are done in parallel rather than sequentially. -@defspec cl-psetq [symbol form]@dots{} +@defmac cl-psetq [symbol form]@dots{} This special form (actually a 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} @@ -854,7 +854,7 @@ @pxref{Modify Macros}.) @code{cl-psetq} always returns @code{nil}. -@end defspec +@end defmac @node Generalized Variables @section Generalized Variables @@ -1010,15 +1010,15 @@ variables. Many are interesting and useful even when the @var{place} is just a variable name. -@defspec cl-psetf [place form]@dots{} +@defmac cl-psetf [place form]@dots{} This macro is to @code{setf} what @code{cl-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 defspec +@end defmac -@defspec cl-incf place &optional x +@defmac cl-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{(cl-incf i)} is equivalent to @code{(setq i (1+ i))}, and @@ -1057,22 +1057,22 @@ As a more Emacs-specific example of @code{cl-incf}, the expression @code{(cl-incf (point) @var{n})} is essentially equivalent to @code{(forward-char @var{n})}. -@end defspec +@end defmac -@defspec cl-decf place &optional x +@defmac cl-decf place &optional x This macro decrements the number stored in @var{place} by one, or by @var{x} if specified. -@end defspec +@end defmac -@defspec cl-pushnew x place @t{&key :test :test-not :key} +@defmac 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 existing element of the list. The optional keyword arguments are interpreted in the same way as for @code{cl-adjoin}. @xref{Lists as Sets}. -@end defspec +@end defmac -@defspec cl-shiftf place@dots{} newvalue +@defmac 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 @@ -1090,9 +1090,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 defspec +@end defmac -@defspec cl-rotatef place@dots{} +@defmac cl-rotatef place@dots{} 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 @@ -1107,12 +1107,12 @@ except for the evaluation of subforms. @code{cl-rotatef} always returns @code{nil}. Note that @code{(cl-rotatef @var{a} @var{b})} conveniently exchanges @var{a} and @var{b}. -@end defspec +@end defmac The following macros were invented for this package; they have no analogues in Common Lisp. -@defspec 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 @@ -1162,14 +1162,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 defspec +@end defmac -@defspec cl-letf* (bindings@dots{}) forms@dots{} +@defmac cl-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 defspec +@end defmac -@defspec cl-callf @var{function} @var{place} @var{args}@dots{} +@defmac cl-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 @@ -1186,14 +1186,14 @@ @xref{Customizing Setf}, for @code{define-modify-macro}, a way to create even more concise notations for modify macros. Note again that @code{cl-callf} is an extension to standard Common Lisp. -@end defspec +@end defmac -@defspec cl-callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{} +@defmac cl-callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{} This macro is like @code{cl-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{(cl-callf2 cons @var{x} @var{place})}. -@end defspec +@end defmac The @code{cl-callf} and @code{cl-callf2} macros serve as building blocks for other macros like @code{cl-incf}, @code{cl-pushnew}, and @@ -1209,7 +1209,7 @@ @code{defsetf}, and @code{define-setf-method}, that allow the user to extend generalized variables in various ways. -@defspec 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{cl-incf} and @code{cl-decf}. The macro @var{name} is defined to take a @var{place} argument followed by additional arguments @@ -1249,9 +1249,9 @@ is completely irregular. You can define these macros ``by hand'' using @code{get-setf-method}, or consult the source to see how to use the internal @code{setf} building blocks. -@end defspec +@end defmac -@defspec 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 @@ -1294,9 +1294,9 @@ (defsetf symbol-value set) (defsetf buffer-name rename-buffer t) @end example -@end defspec +@end defmac -@defspec 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 @@ -1325,9 +1325,9 @@ (defsetf nth (n x) (store) (list 'setcar (list 'nthcdr n x) store)) @end example -@end defspec +@end defmac -@defspec 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 @@ -1372,7 +1372,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 defspec +@end defmac @defun get-setf-method place &optional env This function returns the setf-method for @var{place}, by @@ -1435,7 +1435,7 @@ at compile-time. The @code{cl-progv} form provides an easy way to bind variables whose names are computed at run-time. -@defspec cl-progv symbols values forms@dots{} +@defmac cl-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 @@ -1445,7 +1445,7 @@ are bound to @code{nil}. If @var{symbols} is shorter than @var{values}, the excess values are ignored. -@end defspec +@end defmac @node Lexical Bindings @subsection Lexical Bindings @@ -1454,7 +1454,7 @@ The @code{CL} package defines the following macro which more closely follows the Common Lisp @code{let} form: -@defspec 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 @@ -1554,12 +1554,12 @@ The @code{lexical-let} form is an extension to Common Lisp. In true Common Lisp, all bindings are lexical unless declared otherwise. -@end defspec +@end defmac -@defspec 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 defspec +@end defmac @node Function Bindings @subsection Function Bindings @@ -1568,7 +1568,7 @@ These forms make @code{let}-like bindings to functions instead of variables. -@defspec 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} @@ -1612,9 +1612,9 @@ argument notation supported by @code{cl-defun}; also, the function body is enclosed in an implicit block as if by @code{cl-defun}. @xref{Program Structure}. -@end defspec +@end defmac -@defspec labels (bindings@dots{}) forms@dots{} +@defmac labels (bindings@dots{}) forms@dots{} The @code{labels} form is like @code{flet}, except that it makes lexical bindings of the function names rather than dynamic bindings. (In true Common Lisp, both @code{flet} and @@ -1635,7 +1635,7 @@ A ``reference'' to a function name is either a call to that function, or a use of its name quoted by @code{quote} or @code{function} to be passed on to, say, @code{mapcar}. -@end defspec +@end defmac @node Macro Bindings @subsection Macro Bindings @@ -1643,7 +1643,7 @@ @noindent These forms create local macros and ``symbol macros''. -@defspec cl-macrolet (bindings@dots{}) forms@dots{} +@defmac cl-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{cl-defmacro} (i.e., a macro name, argument list, @@ -1655,9 +1655,9 @@ affect only calls that appear physically within the body @var{forms}, possibly after expansion of other macros in the body. -@end defspec +@end defmac -@defspec cl-symbol-macrolet (bindings@dots{}) forms@dots{} +@defmac cl-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})}; @@ -1723,7 +1723,7 @@ @xref{Loop Facility}, for a description of the @code{cl-loop} macro. This package defines a nonstandard @code{in-ref} loop clause that works much like @code{my-dolist}. -@end defspec +@end defmac @node Conditionals @section Conditionals @@ -1732,7 +1732,7 @@ These conditional forms augment Emacs Lisp's simple @code{if}, @code{and}, @code{or}, and @code{cond} forms. -@defspec cl-case keyform clause@dots{} +@defmac cl-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 @@ -1766,15 +1766,15 @@ ((?\r ?\n) (do-ret-thing)) (t (do-other-thing))) @end example -@end defspec +@end defmac -@defspec cl-ecase keyform clause@dots{} +@defmac cl-ecase keyform clause@dots{} This macro is just like @code{cl-case}, except that if the key does not match any of the clauses, an error is signaled rather than simply returning @code{nil}. -@end defspec +@end defmac -@defspec cl-typecase keyform clause@dots{} +@defmac cl-typecase keyform clause@dots{} This macro is a version of @code{cl-case} that checks for types rather than values. Each @var{clause} is of the form @samp{(@var{type} @var{body}...)}. @xref{Type Predicates}, @@ -1791,13 +1791,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 defspec +@end defmac -@defspec cl-etypecase keyform clause@dots{} +@defmac cl-etypecase keyform clause@dots{} This macro is just like @code{cl-typecase}, except that if the key does not match any of the clauses, an error is signaled rather than simply returning @code{nil}. -@end defspec +@end defmac @node Blocks and Exits @section Blocks and Exits @@ -1810,7 +1810,7 @@ optimizing byte-compiler to omit the costly @code{catch} step if the body of the block does not actually @code{cl-return-from} the block. -@defspec cl-block name forms@dots{} +@defmac cl-block name forms@dots{} The @var{forms} are evaluated as if by a @code{progn}. However, if any of the @var{forms} execute @code{(cl-return-from @var{name})}, they will jump out and return directly from the @code{cl-block} form. @@ -1849,20 +1849,20 @@ that jump to it. This means that @code{cl-do} loops and @code{cl-defun} functions which don't use @code{cl-return} don't pay the overhead to support it. -@end defspec +@end defmac -@defspec cl-return-from name [result] +@defmac cl-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 defspec +@end defmac -@defspec cl-return [result] +@defmac cl-return [result] This macro is exactly like @code{(cl-return-from nil @var{result})}. Common Lisp loops like @code{cl-do} and @code{cl-dolist} implicitly enclose themselves in @code{nil} blocks. -@end defspec +@end defmac @node Iteration @section Iteration @@ -1872,7 +1872,7 @@ looping constructs to complement Emacs Lisp's basic @code{while} loop. -@defspec cl-loop forms@dots{} +@defmac cl-loop forms@dots{} The @code{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 @@ -1900,9 +1900,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 defspec +@end defmac -@defspec cl-do (spec@dots{}) (end-test [result@dots{}]) forms@dots{} +@defmac cl-do (spec@dots{}) (end-test [result@dots{}]) forms@dots{} This macro creates a general iterative loop. Each @var{spec} is of the form @@ -1948,9 +1948,9 @@ ((or (null x) (null y)) (nreverse z))) @end example -@end defspec +@end defmac -@defspec cl-do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{} +@defmac cl-do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{} This is to @code{cl-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 @@ -1968,9 +1968,9 @@ (nreverse z)) (push (f x y) z)) @end example -@end defspec +@end defmac -@defspec cl-dolist (var list [result]) forms@dots{} +@defmac cl-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 @@ -1978,9 +1978,9 @@ with @var{var} bound to @code{nil} to produce the result returned by the loop. Unlike with Emacs's built in @code{dolist}, the loop is surrounded by an implicit @code{nil} block. -@end defspec +@end defmac -@defspec cl-dotimes (var count [result]) forms@dots{} +@defmac cl-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 @@ -1988,9 +1988,9 @@ number of iterations that were done (i.e., @code{(max 0 @var{count})}) to get the return value for the loop form. Unlike with Emacs's built in @code{dolist}, the loop is surrounded by an implicit @code{nil} block. -@end defspec +@end defmac -@defspec cl-do-symbols (var [obarray [result]]) forms@dots{} +@defmac cl-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 @@ -1998,12 +1998,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 defspec +@end defmac -@defspec cl-do-all-symbols (var [result]) forms@dots{} +@defmac cl-do-all-symbols (var [result]) forms@dots{} This is identical to @code{cl-do-symbols} except that the @var{obarray} argument is omitted; it always iterates over the default obarray. -@end defspec +@end defmac @xref{Mapping over Sequences}, for some more functions for iterating over vectors or lists. @@ -2043,7 +2043,7 @@ takes place at byte-compile time; compiled @code{cl-loop}s are just as efficient as the equivalent @code{while} loops written longhand. -@defspec cl-loop clauses@dots{} +@defmac cl-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{cl-loop}, @@ -2082,7 +2082,7 @@ (Because the loop body is enclosed in an implicit block, you can also use regular Lisp @code{cl-return} or @code{cl-return-from} to break out of the loop.) -@end defspec +@end defmac The following sections give some examples of the Loop Macro in action, and describe the particular loop clauses in great detail. @@ -2773,21 +2773,21 @@ The @code{values} form, for example, is a synonym for @code{list} in Emacs. -@defspec cl-multiple-value-bind (var@dots{}) values-form forms@dots{} +@defmac cl-multiple-value-bind (var@dots{}) values-form forms@dots{} This form evaluates @var{values-form}, which must return a list of 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 defspec +@end defmac -@defspec cl-multiple-value-setq (var@dots{}) form +@defmac cl-multiple-value-setq (var@dots{}) form This form evaluates @var{form}, which must return a list of 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{cl-multiple-value-bind}. -@end defspec +@end defmac Since a perfect emulation is not feasible in Emacs Lisp, this package opts to keep it as simple and predictable as possible. @@ -2805,7 +2805,7 @@ Destructuring is made available to the user by way of the following macro: -@defspec cl-destructuring-bind arglist expr forms@dots{} +@defmac cl-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 @@ -2814,13 +2814,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 defspec +@end defmac This package also includes the Common Lisp @code{cl-define-compiler-macro} facility, which allows you to define compile-time expansions and optimizations for your functions. -@defspec cl-define-compiler-macro name arglist forms@dots{} +@defmac cl-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 @@ -2854,7 +2854,7 @@ @code{cl-member} call is left intact. (The actual compiler macro for @code{cl-member} optimizes a number of other cases, including common @code{:test} predicates.) -@end defspec +@end defmac @defun cl-compiler-macroexpand form This function is analogous to @code{macroexpand}, except that it @@ -2896,7 +2896,7 @@ is evaluated and thus should normally be quoted. @end defun -@defspec cl-declaim decl-specs@dots{} +@defmac cl-declaim decl-specs@dots{} This macro is like @code{cl-proclaim}, except that it takes any number of @var{decl-spec} arguments, and the arguments are unevaluated and unquoted. The @code{cl-declaim} macro also puts an @code{(cl-eval-when @@ -2905,22 +2905,22 @@ since normally the declarations are meant to influence the way the compiler treats the rest of the file that contains the @code{cl-declaim} form.) -@end defspec +@end defmac -@defspec cl-declare decl-specs@dots{} +@defmac cl-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{cl-declare} is @code{special}. -@end defspec +@end defmac -@defspec cl-locally declarations@dots{} forms@dots{} +@defmac cl-locally declarations@dots{} forms@dots{} In this package, @code{cl-locally} is no different from @code{progn}. -@end defspec +@end defmac -@defspec cl-the type form +@defmac cl-the type form Type information provided by @code{cl-the} is ignored in this package; in other words, @code{(cl-the @var{type} @var{form})} is equivalent to @var{form}. Future versions of the optimizing byte-compiler may @@ -2933,7 +2933,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 defspec +@end defmac Each @var{decl-spec} in a @code{cl-proclaim}, @code{cl-declaim}, or @code{cl-declare} should be a list beginning with a symbol that says @@ -3137,7 +3137,7 @@ expression. @end defun -@defspec cl-remf place property +@defmac cl-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 @@ -3145,7 +3145,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 defspec +@end defmac @node Creating Symbols @section Creating Symbols @@ -4259,7 +4259,7 @@ implements structures as vectors (or lists upon request) with a special ``tag'' symbol to identify them. -@defspec cl-defstruct name slots@dots{} +@defmac cl-defstruct name slots@dots{} The @code{cl-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.) @@ -4563,7 +4563,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 defspec +@end defmac Except as noted, the @code{cl-defstruct} facility of this package is entirely compatible with that of Common Lisp. @@ -4582,7 +4582,7 @@ away the following assertions. Because assertions might be optimized away, it is a bad idea for them to include side-effects. -@defspec cl-assert test-form [show-args string args@dots{}] +@defmac cl-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{cl-assert} signals an error. @@ -4606,9 +4606,9 @@ which can be @code{setf}'d by the user before continuing from the error. Since Emacs Lisp does not support continuable errors, it makes no sense to specify @var{places}. -@end defspec +@end defmac -@defspec cl-check-type form type [string] +@defmac cl-check-type form type [string] This form verifies that @var{form} evaluates to a value of type @var{type}. If so, it returns @code{nil}. If not, @code{cl-check-type} signals a @code{wrong-type-argument} error. The default error message @@ -4627,7 +4627,7 @@ must 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}. -@end defspec +@end defmac @node Efficiency Concerns @appendix Efficiency Concerns @@ -4660,12 +4660,10 @@ @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 -garbage-collect less because the macro expansion will not have -to be generated, used, and thrown away a hundred times. +A loop using @code{cl-incf} a hundred times will execute considerably +faster if compiled, and will also garbage-collect less because the +macro expansion will not have to be generated, used, and thrown away a +hundred times. You can find out how a macro expands by using the @code{cl-prettyexpand} function. ------------------------------------------------------------ revno: 110694 committer: Glenn Morris branch nick: trunk timestamp: Sat 2012-10-27 15:42:07 -0700 message: 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. diff: === modified file 'doc/lispref/ChangeLog' --- doc/lispref/ChangeLog 2012-10-27 22:07:43 +0000 +++ doc/lispref/ChangeLog 2012-10-27 22:42:07 +0000 @@ -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 === modified file 'doc/lispref/elisp.texi' --- doc/lispref/elisp.texi 2012-10-24 03:48:50 +0000 +++ doc/lispref/elisp.texi 2012-10-27 22:42:07 +0000 @@ -486,6 +486,7 @@ * 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 === modified file 'doc/lispref/lists.texi' --- doc/lispref/lists.texi 2012-10-27 22:07:43 +0000 +++ doc/lispref/lists.texi 2012-10-27 22:42:07 +0000 @@ -236,6 +236,10 @@ @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 @@ @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)) === modified file 'doc/lispref/variables.texi' --- doc/lispref/variables.texi 2012-09-18 05:14:42 +0000 +++ doc/lispref/variables.texi 2012-10-27 22:42:07 +0000 @@ -41,6 +41,7 @@ * 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 @@ (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}. === modified file 'doc/misc/ChangeLog' --- doc/misc/ChangeLog 2012-10-26 14:42:05 +0000 +++ doc/misc/ChangeLog 2012-10-27 22:42:07 +0000 @@ -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 === modified file 'doc/misc/cl.texi' --- doc/misc/cl.texi 2012-10-25 01:49:54 +0000 +++ doc/misc/cl.texi 2012-10-27 22:42:07 +0000 @@ -57,7 +57,7 @@ * 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 @@ @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 @@ @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}: - -@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. - -@item -A call to any of the following Lisp functions: - +@node Setf Extensions +@subsection Setf Extensions + +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 +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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ @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 @@ 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 @@ 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 @@ @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 @@ 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 @@ @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, ------------------------------------------------------------ revno: 110693 committer: Glenn Morris branch nick: trunk timestamp: Sat 2012-10-27 15:07:43 -0700 message: * doc/lispref/lists.texi (List Elements): Typo fix. diff: === modified file 'doc/lispref/ChangeLog' --- doc/lispref/ChangeLog 2012-10-27 05:03:52 +0000 +++ doc/lispref/ChangeLog 2012-10-27 22:07:43 +0000 @@ -1,3 +1,7 @@ +2012-10-27 Glenn Morris + + * lists.texi (List Elements): Typo fix. + 2012-10-27 Chong Yidong * minibuf.texi (High-Level Completion): Don't mention removed === modified file 'doc/lispref/lists.texi' --- doc/lispref/lists.texi 2012-10-22 02:22:27 +0000 +++ doc/lispref/lists.texi 2012-10-27 22:07:43 +0000 @@ -252,7 +252,7 @@ @end example @noindent -For the @code{pop} macro, which removes an element from a list, +For the @code{push} macro, which adds an element to a list, @xref{List Variables}. @end defmac ------------------------------------------------------------ revno: 110692 committer: Eli Zaretskii branch nick: trunk timestamp: Sat 2012-10-27 21:43:48 +0200 message: Fix compiler warnings in w32proc.c. src/w32proc.c (sys_spawnve): Avoid compiler warning about format mismatch. (timer_loop): Remove unused variable. diff: === modified file 'src/ChangeLog' --- src/ChangeLog 2012-10-27 19:32:30 +0000 +++ src/ChangeLog 2012-10-27 19:43:48 +0000 @@ -11,11 +11,13 @@ for the timer. (timer_loop): Enter critical section when accessing ULONGLONG values of the itimer_data struct, as these accesses are no longer - atomic. Call 'w32_get_timer_time' instead of 'clock'. + atomic. Call 'w32_get_timer_time' instead of 'clock'. Remove + unused variable. (init_timers): Initialize s_pfn_Get_Thread_Times. (start_timer_thread): Don't assign itimer->caller_thread here. (getitimer): Assign itimer->caller_thread here. (setitimer): Always call getitimer to get the value of ticks_now. + (sys_spawnve): Avoid compiler warning about format mismatch. 2012-10-26 Eli Zaretskii === modified file 'src/w32proc.c' --- src/w32proc.c 2012-10-27 19:32:30 +0000 +++ src/w32proc.c 2012-10-27 19:43:48 +0000 @@ -335,7 +335,6 @@ int sig = (which == ITIMER_REAL) ? SIGALRM : SIGPROF; CRITICAL_SECTION *crit = (which == ITIMER_REAL) ? &crit_real : &crit_prof; const DWORD max_sleep = MAX_SINGLE_SLEEP * 1000 / CLOCKS_PER_SEC; - int new_count = 0; HANDLE hth = (which == ITIMER_REAL) ? NULL : itimer->caller_thread; while (1) @@ -1656,7 +1655,7 @@ numenv++; } /* extra env vars... */ - sprintf (ppid_env_var_buffer, "EM_PARENT_PROCESS_ID=%d", + sprintf (ppid_env_var_buffer, "EM_PARENT_PROCESS_ID=%lu", GetCurrentProcessId ()); arglen += strlen (ppid_env_var_buffer) + 1; numenv++; ------------------------------------------------------------ revno: 110691 committer: Eli Zaretskii branch nick: trunk timestamp: Sat 2012-10-27 21:32:30 +0200 message: Use 'volatile' types for communications between timer thread and main thread. diff: === modified file 'src/ChangeLog' --- src/ChangeLog 2012-10-27 11:21:26 +0000 +++ src/ChangeLog 2012-10-27 19:32:30 +0000 @@ -4,8 +4,8 @@ possible, for ITIMER_PROF count only times the main thread actually executes. * w32proc.c : 'expire' and 'reload' are now - ULONGLONG types. Likewise for all the other data which was - previously clock_t. + 'volatile ULONGLONG' types. All the other data which was + previously clock_t is now ULONGLONG. 'terminate' is 'volatile int'. (GetThreadTimes_Proc): New typedef. (w32_get_timer_time): New function, returns a suitable time value for the timer. === modified file 'src/w32proc.c' --- src/w32proc.c 2012-10-27 19:20:02 +0000 +++ src/w32proc.c 2012-10-27 19:32:30 +0000 @@ -245,9 +245,9 @@ expires, after stopping the thread which installed the timer. */ struct itimer_data { - ULONGLONG expire; - ULONGLONG reload; - int terminate; + volatile ULONGLONG expire; + volatile ULONGLONG reload; + volatile int terminate; int type; HANDLE caller_thread; HANDLE timer_thread; ------------------------------------------------------------ revno: 110690 committer: Eli Zaretskii branch nick: trunk timestamp: Sat 2012-10-27 21:20:02 +0200 message: Fix a typo in a comment. diff: === modified file 'src/w32proc.c' --- src/w32proc.c 2012-10-27 11:21:26 +0000 +++ src/w32proc.c 2012-10-27 19:20:02 +0000 @@ -262,7 +262,7 @@ static CRITICAL_SECTION crit_real, crit_prof; -/* GetThreadTimes is not available on Windows 9X and posibly also on 2K. */ +/* GetThreadTimes is not available on Windows 9X and possibly also on 2K. */ typedef BOOL (WINAPI *GetThreadTimes_Proc) ( HANDLE hThread, LPFILETIME lpCreationTime, ------------------------------------------------------------ revno: 110689 committer: Eli Zaretskii branch nick: trunk timestamp: Sat 2012-10-27 13:21:26 +0200 message: Fix w32 implementation of itimers: overflow and ITIMER_PROF. Avoid overflow in w32 implementation of interval timers. When possible, for ITIMER_PROF count only times the main thread actually executes. src/w32proc.c : 'expire' and 'reload' are now ULONGLONG types. Likewise for all the other data which was previously clock_t. (GetThreadTimes_Proc): New typedef. (w32_get_timer_time): New function, returns a suitable time value for the timer. (timer_loop): Enter critical section when accessing ULONGLONG values of the itimer_data struct, as these accesses are no longer atomic. Call 'w32_get_timer_time' instead of 'clock'. (init_timers): Initialize s_pfn_Get_Thread_Times. (start_timer_thread): Don't assign itimer->caller_thread here. (getitimer): Assign itimer->caller_thread here. (setitimer): Always call getitimer to get the value of ticks_now. diff: === modified file 'src/ChangeLog' --- src/ChangeLog 2012-10-26 09:46:46 +0000 +++ src/ChangeLog 2012-10-27 11:21:26 +0000 @@ -1,3 +1,22 @@ +2012-10-27 Eli Zaretskii + + Avoid overflow in w32 implementation of interval timers. When + possible, for ITIMER_PROF count only times the main thread + actually executes. + * w32proc.c : 'expire' and 'reload' are now + ULONGLONG types. Likewise for all the other data which was + previously clock_t. + (GetThreadTimes_Proc): New typedef. + (w32_get_timer_time): New function, returns a suitable time value + for the timer. + (timer_loop): Enter critical section when accessing ULONGLONG + values of the itimer_data struct, as these accesses are no longer + atomic. Call 'w32_get_timer_time' instead of 'clock'. + (init_timers): Initialize s_pfn_Get_Thread_Times. + (start_timer_thread): Don't assign itimer->caller_thread here. + (getitimer): Assign itimer->caller_thread here. + (setitimer): Always call getitimer to get the value of ticks_now. + 2012-10-26 Eli Zaretskii * w32fns.c (w32_wnd_proc) : Don't enable tracking of === modified file 'src/w32proc.c' --- src/w32proc.c 2012-10-17 19:02:44 +0000 +++ src/w32proc.c 2012-10-27 11:21:26 +0000 @@ -244,28 +244,89 @@ the thread calls the appropriate signal handler when the timer expires, after stopping the thread which installed the timer. */ -/* FIXME: clock_t counts overflow after 49 days, need to handle the - wrap-around. */ struct itimer_data { - clock_t expire; - clock_t reload; + ULONGLONG expire; + ULONGLONG reload; int terminate; int type; HANDLE caller_thread; HANDLE timer_thread; }; -static clock_t ticks_now; +static ULONGLONG ticks_now; static struct itimer_data real_itimer, prof_itimer; -static clock_t clocks_min; +static ULONGLONG clocks_min; /* If non-zero, itimers are disabled. Used during shutdown, when we delete the critical sections used by the timer threads. */ static int disable_itimers; static CRITICAL_SECTION crit_real, crit_prof; +/* GetThreadTimes is not available on Windows 9X and posibly also on 2K. */ +typedef BOOL (WINAPI *GetThreadTimes_Proc) ( + HANDLE hThread, + LPFILETIME lpCreationTime, + LPFILETIME lpExitTime, + LPFILETIME lpKernelTime, + LPFILETIME lpUserTime); + +static GetThreadTimes_Proc s_pfn_Get_Thread_Times; + +/* Return a suitable time value, in 1-ms units, for THREAD, a handle + to a thread. If THREAD is NULL or an invalid handle, return the + current wall-clock time since January 1, 1601 (UTC). Otherwise, + return the sum of kernel and user times used by THREAD since it was + created, plus its creation time. */ +static ULONGLONG +w32_get_timer_time (HANDLE thread) +{ + ULONGLONG retval; + int use_system_time = 1; + + if (thread && thread != INVALID_HANDLE_VALUE + && s_pfn_Get_Thread_Times != NULL) + { + FILETIME creation_ftime, exit_ftime, kernel_ftime, user_ftime; + ULARGE_INTEGER temp_creation, temp_kernel, temp_user; + + if (s_pfn_Get_Thread_Times (thread, &creation_ftime, &exit_ftime, + &kernel_ftime, &user_ftime)) + { + use_system_time = 0; + temp_creation.LowPart = creation_ftime.dwLowDateTime; + temp_creation.HighPart = creation_ftime.dwHighDateTime; + temp_kernel.LowPart = kernel_ftime.dwLowDateTime; + temp_kernel.HighPart = kernel_ftime.dwHighDateTime; + temp_user.LowPart = user_ftime.dwLowDateTime; + temp_user.HighPart = user_ftime.dwHighDateTime; + retval = + temp_creation.QuadPart / 10000 + temp_kernel.QuadPart / 10000 + + temp_user.QuadPart / 10000; + } + else + DebPrint (("GetThreadTimes failed with error code %lu\n", + GetLastError ())); + } + + if (use_system_time) + { + FILETIME current_ftime; + ULARGE_INTEGER temp; + + GetSystemTimeAsFileTime (¤t_ftime); + + temp.LowPart = current_ftime.dwLowDateTime; + temp.HighPart = current_ftime.dwHighDateTime; + + retval = temp.QuadPart / 10000; + } + + return retval; +} + #define MAX_SINGLE_SLEEP 30 +/* Thread function for a timer thread. */ static DWORD WINAPI timer_loop (LPVOID arg) { @@ -275,12 +336,13 @@ CRITICAL_SECTION *crit = (which == ITIMER_REAL) ? &crit_real : &crit_prof; const DWORD max_sleep = MAX_SINGLE_SLEEP * 1000 / CLOCKS_PER_SEC; int new_count = 0; + HANDLE hth = (which == ITIMER_REAL) ? NULL : itimer->caller_thread; while (1) { DWORD sleep_time; signal_handler handler; - clock_t now, expire, reload; + ULONGLONG now, expire, reload; /* Load new values if requested by setitimer. */ EnterCriticalSection (crit); @@ -290,15 +352,14 @@ if (itimer->terminate) return 0; - if (itimer->expire == 0) + if (expire == 0) { /* We are idle. */ Sleep (max_sleep); continue; } - expire = itimer->expire; - if (expire > (now = clock ())) + if (expire > (now = w32_get_timer_time (hth))) sleep_time = expire - now; else sleep_time = 0; @@ -309,8 +370,11 @@ if (itimer->terminate) return 0; Sleep (max_sleep); + EnterCriticalSection (crit); expire = itimer->expire; - sleep_time = (expire > (now = clock ())) ? expire - now : 0; + LeaveCriticalSection (crit); + sleep_time = + (expire > (now = w32_get_timer_time (hth))) ? expire - now : 0; } if (itimer->terminate) return 0; @@ -320,13 +384,16 @@ /* Always sleep past the expiration time, to make sure we never call the handler _before_ the expiration time, always slightly after it. Sleep(5) makes sure we don't - hog the CPU by calling 'clock' with high frequency, and - also let other threads work. */ - while (clock () < expire) + hog the CPU by calling 'w32_get_timer_time' with high + frequency, and also let other threads work. */ + while (w32_get_timer_time (hth) < expire) Sleep (5); } - if (itimer->expire == 0) + EnterCriticalSection (crit); + expire = itimer->expire; + LeaveCriticalSection (crit); + if (expire == 0) continue; /* Time's up. */ @@ -353,19 +420,21 @@ ResumeThread (itimer->caller_thread); } - if (itimer->expire == 0) - continue; - /* Update expiration time and loop. */ EnterCriticalSection (crit); expire = itimer->expire; + if (expire == 0) + { + LeaveCriticalSection (crit); + continue; + } reload = itimer->reload; if (reload > 0) { - now = clock (); + now = w32_get_timer_time (hth); if (expire <= now) { - clock_t lag = now - expire; + ULONGLONG lag = now - expire; /* If we missed some opportunities (presumably while sleeping or while the signal handler ran), skip @@ -448,6 +517,15 @@ void init_timers (void) { + /* GetThreadTimes is not avaiulable on all versions of Windows, so + need to probe for its availability dynamically, and call it + through a pointer. */ + s_pfn_Get_Thread_Times = NULL; /* in case dumped Emacs comes with a value */ + if (os_subtype != OS_9X) + s_pfn_Get_Thread_Times = + (GetThreadTimes_Proc)GetProcAddress (GetModuleHandle ("kernel32.dll"), + "GetThreadTimes"); + /* Make sure we start with zeroed out itimer structures, since dumping may have left there traces of threads long dead. */ memset (&real_itimer, 0, sizeof real_itimer); @@ -473,14 +551,6 @@ return 0; /* Start a new thread. */ - if (!DuplicateHandle (GetCurrentProcess (), GetCurrentThread (), - GetCurrentProcess (), &itimer->caller_thread, 0, - FALSE, DUPLICATE_SAME_ACCESS)) - { - errno = ESRCH; - return -1; - } - itimer->terminate = 0; itimer->type = which; /* Request that no more than 64KB of stack be reserved for this @@ -512,17 +582,16 @@ int getitimer (int which, struct itimerval *value) { - volatile clock_t *t_expire; - volatile clock_t *t_reload; - clock_t expire, reload; + volatile ULONGLONG *t_expire; + volatile ULONGLONG *t_reload; + ULONGLONG expire, reload; __int64 usecs; CRITICAL_SECTION *crit; + struct itimer_data *itimer; if (disable_itimers) return -1; - ticks_now = clock (); - if (!value) { errno = EFAULT; @@ -535,8 +604,22 @@ return -1; } - t_expire = (which == ITIMER_REAL) ? &real_itimer.expire: &prof_itimer.expire; - t_reload = (which == ITIMER_REAL) ? &real_itimer.reload: &prof_itimer.reload; + itimer = (which == ITIMER_REAL) ? &real_itimer : &prof_itimer; + + if (!DuplicateHandle (GetCurrentProcess (), GetCurrentThread (), + GetCurrentProcess (), &itimer->caller_thread, 0, + FALSE, DUPLICATE_SAME_ACCESS)) + { + errno = ESRCH; + return -1; + } + + ticks_now = w32_get_timer_time ((which == ITIMER_REAL) + ? NULL + : itimer->caller_thread); + + t_expire = &itimer->expire; + t_reload = &itimer->reload; crit = (which == ITIMER_REAL) ? &crit_real : &crit_prof; EnterCriticalSection (crit); @@ -560,10 +643,11 @@ int setitimer(int which, struct itimerval *value, struct itimerval *ovalue) { - volatile clock_t *t_expire, *t_reload; - clock_t expire, reload, expire_old, reload_old; + volatile ULONGLONG *t_expire, *t_reload; + ULONGLONG expire, reload, expire_old, reload_old; __int64 usecs; CRITICAL_SECTION *crit; + struct itimerval tem, *ptem; if (disable_itimers) return -1; @@ -573,26 +657,21 @@ time we are called, measure the clock tick resolution. */ if (!clocks_min) { - clock_t t1, t2; + ULONGLONG t1, t2; - for (t1 = clock (); (t2 = clock ()) == t1; ) + for (t1 = w32_get_timer_time (NULL); + (t2 = w32_get_timer_time (NULL)) == t1; ) ; clocks_min = t2 - t1; } if (ovalue) - { - if (getitimer (which, ovalue)) /* also sets ticks_now */ - return -1; /* errno already set */ - } + ptem = ovalue; else - ticks_now = clock (); + ptem = &tem; - if (which != ITIMER_REAL && which != ITIMER_PROF) - { - errno = EINVAL; - return -1; - } + if (getitimer (which, ptem)) /* also sets ticks_now */ + return -1; /* errno already set */ t_expire = (which == ITIMER_REAL) ? &real_itimer.expire : &prof_itimer.expire; ------------------------------------------------------------ revno: 110688 committer: Bastien Guerry branch nick: trunk timestamp: Sat 2012-10-27 13:06:08 +0200 message: Fix typo in screen.texi. diff: === modified file 'doc/emacs/ChangeLog' --- doc/emacs/ChangeLog 2012-10-27 05:03:52 +0000 +++ doc/emacs/ChangeLog 2012-10-27 11:06:08 +0000 @@ -1,3 +1,7 @@ +2012-10-27 Bastien Guerry + + * screen.texi (Menu Bar): Fix typo. + 2012-10-27 Chong Yidong * frames.texi (Mouse Avoidance): Mention new variable === modified file 'doc/emacs/screen.texi' --- doc/emacs/screen.texi 2012-05-27 01:25:06 +0000 +++ doc/emacs/screen.texi 2012-10-27 11:06:08 +0000 @@ -314,5 +314,5 @@ the menu to different items, and then you can type @key{RET} to select the item. Each menu item is also designated by a letter or digit (usually the initial of some word in the item's name). This letter or -digit is separated from the item name by @samp{=>}. You can type the +digit is separated from the item name by @samp{==>}. You can type the item's letter or digit to select the item. ------------------------------------------------------------ revno: 110687 committer: Eli Zaretskii branch nick: trunk timestamp: Sat 2012-10-27 11:54:04 +0200 message: Fix help-echo text in profiler-report-make-entry-part. lisp/profiler.el (profiler-report-make-entry-part): Fix help-echo text to match the real keybindings. diff: === modified file 'lisp/ChangeLog' --- lisp/ChangeLog 2012-10-27 09:17:14 +0000 +++ lisp/ChangeLog 2012-10-27 09:54:04 +0000 @@ -1,3 +1,8 @@ +2012-10-27 Eli Zaretskii + + * profiler.el (profiler-report-make-entry-part): Fix help-echo + text to match the real keybindings. + 2012-10-27 Juri Linkov * wdired.el (wdired-keep-marker-rename): New defcustom. === modified file 'lisp/profiler.el' --- lisp/profiler.el 2012-10-06 20:30:26 +0000 +++ lisp/profiler.el 2012-10-27 09:54:04 +0000 @@ -353,7 +353,9 @@ (propertize (symbol-name entry) 'face 'link 'mouse-face 'highlight - 'help-echo "mouse-2 or RET jumps to definition")) + 'help-echo "\ +mouse-2: jump to definition\n\ +RET: expand or collapse")) (t (profiler-format-entry entry))))) (propertize string 'profiler-entry entry))) ------------------------------------------------------------ revno: 110686 fixes bug: http://debbugs.gnu.org/11795 committer: Juri Linkov branch nick: trunk timestamp: Sat 2012-10-27 12:17:14 +0300 message: * lisp/wdired.el (wdired-keep-marker-rename): New defcustom. (wdired-do-renames): Use it instead of `dired-keep-marker-rename'. * lisp/dired.el (dired-keep-marker-rename): Add reference to `wdired-keep-marker-rename' in the docstring. Add default character value ?R to display initially in Customization UI instead of ?@. diff: === modified file 'lisp/ChangeLog' --- lisp/ChangeLog 2012-10-27 08:58:30 +0000 +++ lisp/ChangeLog 2012-10-27 09:17:14 +0000 @@ -1,3 +1,14 @@ +2012-10-27 Juri Linkov + + * wdired.el (wdired-keep-marker-rename): New defcustom. + (wdired-do-renames): Use it instead of `dired-keep-marker-rename'. + (Bug#11795) + + * dired.el (dired-keep-marker-rename): Add reference to + `wdired-keep-marker-rename' in the docstring. + Add default character value ?R to display initially in + Customization UI instead of ?@. + 2012-10-27 Martin Rudalics * window.el (display-buffer): In doc-string describe === modified file 'lisp/dired.el' --- lisp/dired.el 2012-10-25 13:00:52 +0000 +++ lisp/dired.el 2012-10-27 09:17:14 +0000 @@ -137,9 +137,12 @@ "Controls marking of renamed files. If t, files keep their previous marks when they are renamed. If a character, renamed files (whether previously marked or not) -are afterward marked with that character." +are afterward marked with that character. +This option affects only files renamed by `dired-do-rename' and +`dired-do-rename-regexp'. See `wdired-keep-marker-rename' +if you want to do the same for files renamed in WDired mode." :type '(choice (const :tag "Keep" t) - (character :tag "Mark")) + (character :tag "Mark" :value ?R)) :group 'dired-mark) (defcustom dired-keep-marker-copy ?C === modified file 'lisp/wdired.el' --- lisp/wdired.el 2012-10-17 09:11:49 +0000 +++ lisp/wdired.el 2012-10-27 09:17:14 +0000 @@ -140,6 +140,20 @@ (other :tag "Bits freely editable" advanced)) :group 'wdired) +(defcustom wdired-keep-marker-rename t + ;; Use t as default so that renamed files "take their markers with them". + "Controls marking of files renamed in WDired. +If t, files keep their previous marks when they are renamed. +If a character, renamed files (whether previously marked or not) +are afterward marked with that character. +This option affects only files renamed by `wdired-finish-edit'. +See `dired-keep-marker-rename' if you want to do the same for files +renamed by `dired-do-rename' and `dired-do-rename-regexp'." + :type '(choice (const :tag "Keep" t) + (character :tag "Mark" :value ?R)) + :version "24.3" + :group 'wdired) + (defvar wdired-mode-map (let ((map (make-sparse-keymap))) (define-key map "\C-x\C-s" 'wdired-finish-edit) @@ -416,6 +430,8 @@ (set-buffer-modified-p nil) (setq buffer-undo-list nil)) +(declare-function dired-add-entry "dired-aux" (filename &optional marker-char relative)) + (defun wdired-do-renames (renames) "Perform RENAMES in parallel." (let ((residue ()) @@ -471,9 +487,12 @@ (dired-rename-file file-ori file-new overwrite) (dired-remove-file file-ori) - (dired-add-file file-new (if (integerp dired-keep-marker-rename) - dired-keep-marker-rename - old-mark))) + (dired-add-file + file-new + (cond ((integerp wdired-keep-marker-rename) + wdired-keep-marker-rename) + (wdired-keep-marker-rename old-mark) + (t nil)))) (error (setq errors (1+ errors)) (dired-log (concat "Rename `" file-ori "' to `" ------------------------------------------------------------ revno: 110685 committer: martin rudalics branch nick: trunk timestamp: Sat 2012-10-27 10:58:30 +0200 message: In display-time-world restore fit-window-to-buffer behavior. * window.el (display-buffer): In doc-string describe window-height and window-width alist entries. * time.el (display-time-world): Restore fit-window-to-buffer behavior. diff: === modified file 'lisp/ChangeLog' --- lisp/ChangeLog 2012-10-27 05:03:52 +0000 +++ lisp/ChangeLog 2012-10-27 08:58:30 +0000 @@ -1,3 +1,11 @@ +2012-10-27 Martin Rudalics + + * window.el (display-buffer): In doc-string describe + window-height and window-width alist entries. + + * time.el (display-time-world): Restore fit-window-to-buffer + behavior. + 2012-10-27 Chong Yidong * subr.el (insert-buffer-substring-as-yank): Doc fix. @@ -253,7 +261,7 @@ Recover input meta mode when the new coding system doesn not use 8-bit. Supply TERMINAL arg to set-input-meta-mode. -2012-10-17 Michael Heerdegen (tiny change) +2012-10-17 Michael Heerdegen * wdired.el (wdired-old-marks): New variable. (wdired-change-to-wdired-mode): Locally set wdired-old-marks. === modified file 'lisp/time.el' --- lisp/time.el 2012-10-24 18:26:22 +0000 +++ lisp/time.el 2012-10-27 08:58:30 +0000 @@ -557,7 +557,8 @@ (run-at-time t display-time-world-timer-second 'display-time-world-timer)) (with-current-buffer (get-buffer-create display-time-world-buffer-name) (display-time-world-display display-time-world-list) - (display-buffer display-time-world-buffer-name) + (display-buffer display-time-world-buffer-name + (cons nil '((window-height . fit-window-to-buffer)))) (display-time-world-mode))) (defun display-time-world-timer () === modified file 'lisp/window.el' --- lisp/window.el 2012-10-21 07:23:34 +0000 +++ lisp/window.el 2012-10-27 08:58:30 +0000 @@ -5414,6 +5414,22 @@ parameters to give a new frame, if one is created. + `window-height' -- Value specifies either an integer (the number + of lines of a new window), a floating point number (the + fraction of a new window with respect to the height of the + frame's root window) or a function to be called with one + argument - a new window. The function is supposed to adjust + the height of the window; its return value is ignored. + Suitable functions are `shrink-window-if-larger-than-buffer' + and `fit-window-to-buffer'. + + `window-width' -- Value specifies either an integer (the number + of columns of a new window), a floating point number (the + fraction of a new window with respect to the width of the + frame's root window) or a function to be called with one + argument - a new window. The function is supposed to adjust + the width of the window; its return value is ignored. + The ACTION argument to `display-buffer' can also have a non-nil and non-list value. This means to display the buffer in a window other than the selected one, even if it is already displayed in ------------------------------------------------------------ revno: 110684 committer: Chong Yidong branch nick: trunk timestamp: Sat 2012-10-27 13:03:52 +0800 message: More Emacs 24.3 documentation updates. * doc/emacs/building.texi (Compilation): Document compilation-always-kill. * doc/emacs/files.texi (Misc File Ops): Symbolic links on Windows only work on Vista and later. * doc/emacs/frames.texi (Mouse Avoidance): Mention new variable mouse-avoidance-banish-position. * doc/emacs/mule.texi (Recognize Coding): Remove an unreferenced vindex. * doc/emacs/package.texi (Package Menu): Document the "new" status. * doc/emacs/programs.texi (Which Function): Which Function mode now works in all major modes by default. * doc/emacs/search.texi (Symbol Search): New node. * doc/emacs/windows.texi (Window Choice): Don't refer to the obsolete special-display feature. * commands.texi (Event Input Misc): Remove last-input-char. (Command Loop Info): Remove last-command-char. * display.texi (Fringe Bitmaps): Add exclamation-mark bitmap. * frames.texi (Initial Parameters): Don't mention the obsolete special-display feature. * hooks.texi (Standard Hooks): Remove obsolete hooks. * markers.texi (Information from Markers): Remove obsolete function buffer-has-markers-at. * minibuf.texi (High-Level Completion): Don't mention removed function iswitchb-read-buffer. * text.texi (Yanking): Document yank-handled-properties. * windows.texi (Choosing Window): Don't mention the obsolete special display feature. (Choosing Window Options): Remove obsolete special-display variables, and the functions special-display-p and special-display-popup-frame. * subr.el (insert-buffer-substring-as-yank): Doc fix. diff: === modified file 'doc/emacs/ChangeLog' --- doc/emacs/ChangeLog 2012-10-24 14:38:49 +0000 +++ doc/emacs/ChangeLog 2012-10-27 05:03:52 +0000 @@ -1,3 +1,25 @@ +2012-10-27 Chong Yidong + + * frames.texi (Mouse Avoidance): Mention new variable + mouse-avoidance-banish-position. + + * programs.texi (Which Function): Which Function mode now works in + all major modes by default. + + * mule.texi (Recognize Coding): Remove an unreferenced vindex. + + * files.texi (Misc File Ops): Symbolic links on Windows only work + on Vista and later. + + * building.texi (Compilation): Document compilation-always-kill. + + * search.texi (Symbol Search): New node. + + * package.texi (Package Menu): Document the "new" status. + + * windows.texi (Window Choice): Don't refer to the obsolete + special-display feature. + 2012-10-24 Chong Yidong * mule.texi (Text Coding): set-buffer-file-coding-system can now === modified file 'doc/emacs/building.texi' --- doc/emacs/building.texi 2012-09-30 09:18:38 +0000 +++ doc/emacs/building.texi 2012-10-27 05:03:52 +0000 @@ -108,11 +108,14 @@ was started. @findex kill-compilation +@vindex compilation-always-kill Starting a new compilation also kills any compilation already running in @file{*compilation*}, as the buffer can only handle one compilation at any time. However, @kbd{M-x compile} asks for -confirmation before actually killing a compilation that is running. -You can also kill the compilation process with @kbd{M-x +confirmation before actually killing a compilation that is running; to +always automatically kill the compilation without asking, change the +variable @code{compilation-always-kill} to @code{t}. You can also +kill a compilation process with the command @kbd{M-x kill-compilation}. To run two compilations at once, start the first one, then rename === modified file 'doc/emacs/emacs.texi' --- doc/emacs/emacs.texi 2012-09-30 09:18:38 +0000 +++ doc/emacs/emacs.texi 2012-10-27 05:03:52 +0000 @@ -373,6 +373,7 @@ * Incremental Search:: Search happens as you type the string. * Nonincremental Search:: Specify entire string and then search. * Word Search:: Search for sequence of words. +* Symbol Search:: Search for a source code symbol. * Regexp Search:: Search for match for a regexp. * Regexps:: Syntax of regular expressions. * Regexp Backslash:: Regular expression constructs starting with `\'. === modified file 'doc/emacs/files.texi' --- doc/emacs/files.texi 2012-10-13 01:18:52 +0000 +++ doc/emacs/files.texi 2012-10-27 05:03:52 +0000 @@ -1564,9 +1564,8 @@ @var{target} at the time the opening is done, or will get an error if the name @var{target} is nonexistent at that time. This command does not expand the argument @var{target}, so that it allows you to specify -a relative name as the target of the link. Not all systems support -symbolic links; on systems that don't support them, this command is -not defined. +a relative name as the target of the link. On MS-Windows, this +command works only on MS Windows Vista and later. @kindex C-x i @findex insert-file === modified file 'doc/emacs/frames.texi' --- doc/emacs/frames.texi 2012-07-28 15:12:12 +0000 +++ doc/emacs/frames.texi 2012-10-27 05:03:52 +0000 @@ -1092,17 +1092,19 @@ @table @code @item banish -Move the mouse to the upper-right corner on any key-press; +Move the pointer to a corner of the frame on any key-press. You can +customize the variable @code{mouse-avoidance-banish-position} to +specify where the pointer goes when it is banished. @item exile -Move the mouse to the corner only if the cursor gets too close, -and allow it to return once the cursor is out of the way; +Banish the pointer only if the cursor gets too close, and allow it to +return once the cursor is out of the way. @item jump -If the cursor gets too close to the mouse, displace the mouse -a random distance & direction; +If the cursor gets too close to the pointer, displace the pointer by a +random distance and direction. @item animate -As @code{jump}, but shows steps along the way for illusion of motion; +As @code{jump}, but shows steps along the way for illusion of motion. @item cat-and-mouse -The same as @code{animate}; +The same as @code{animate}. @item proteus As @code{animate}, but changes the shape of the mouse pointer too. @end table === modified file 'doc/emacs/mule.texi' --- doc/emacs/mule.texi 2012-10-24 14:38:49 +0000 +++ doc/emacs/mule.texi 2012-10-27 05:03:52 +0000 @@ -920,7 +920,6 @@ @samp{-*-coding:-*-} tag. @c FIXME? This seems somewhat out of place. Move to the Rmail section? -@vindex rmail-decode-mime-charset @vindex rmail-file-coding-system When you get new mail in Rmail, each message is translated automatically from the coding system it is written in, as if it were a === modified file 'doc/emacs/package.texi' --- doc/emacs/package.texi 2012-04-10 06:54:43 +0000 +++ doc/emacs/package.texi 2012-10-27 05:03:52 +0000 @@ -62,8 +62,12 @@ downloaded from the package archive), @samp{installed}, or @samp{built-in} (included in Emacs by default). -In some instances, the status can be @samp{held}, @samp{disabled}, or -@samp{obsolete}. @xref{Package Installation}. +The status can also be @samp{new}. This is equivalent to +@samp{available}, except that it means the package became newly +available on the package archive after your last invocation of +@kbd{M-x list-packages}. In other instances, a package may have the +status @samp{held}, @samp{disabled}, or @samp{obsolete}. +@xref{Package Installation}. @item A short description of the package. === modified file 'doc/emacs/programs.texi' --- doc/emacs/programs.texi 2012-06-17 05:13:40 +0000 +++ doc/emacs/programs.texi 2012-10-27 05:03:52 +0000 @@ -326,12 +326,13 @@ @findex which-function-mode @vindex which-func-modes To either enable or disable Which Function mode, use the command -@kbd{M-x which-function-mode}. Although Which Function mode is a -global minor mode, it takes effect only in certain major modes: those -listed in the variable @code{which-func-modes}. If the value of -@code{which-func-modes} is @code{t} rather than a list of modes, then -Which Function mode applies to all major modes that know how to -support it---in other words, all the major modes that support Imenu. +@kbd{M-x which-function-mode}. Which Function mode is a global minor +mode. By default, it takes effect in all major modes major modes that +know how to support it (i.e.@: all the major modes that support +Imenu). You can restrict it to a specific list of major modes by +changing the value of the variable @code{which-func-modes} from +@code{t} (which means to support all available major modes) to a list +of major mode names. @node Program Indent @section Indentation for Programs === modified file 'doc/emacs/search.texi' --- doc/emacs/search.texi 2012-10-16 23:27:40 +0000 +++ doc/emacs/search.texi 2012-10-27 05:03:52 +0000 @@ -21,6 +21,7 @@ * Incremental Search:: Search happens as you type the string. * Nonincremental Search:: Specify entire string and then search. * Word Search:: Search for sequence of words. +* Symbol Search:: Search for a source code symbol. * Regexp Search:: Search for match for a regexp. * Regexps:: Syntax of regular expressions. * Regexp Backslash:: Regular expression constructs starting with `\'. @@ -467,6 +468,47 @@ proceeds incrementally as you type. This additional laxity does not apply to the lazy highlight, which always matches whole words. +@node Symbol Search +@section Symbol Search +@cindex symbol search + + A @dfn{symbol search} is much like an ordinary search, except that +the boundaries of the search must match the boundaries of a symbol. +The meaning of @dfn{symbol} in this context depends on the major mode, +and usually refers to a source code token, such as a Lisp symbol in +Emacs Lisp mode. For instance, if you perform an incremental symbol +search for the Lisp symbol @code{forward-word}, it would not match +@code{isearch-forward-word}. This feature is thus mainly useful for +searching source code. + +@table @kbd +@item M-s _ +If incremental search is active, toggle symbol search mode +(@code{isearch-toggle-symbol}); otherwise, begin an incremental +forward symbol search (@code{isearch-forward-symbol}). +@item M-s _ @key{RET} @var{symbol} @key{RET} +Search forward for @var{symbol}, nonincrementally. +@item M-s _ C-r @key{RET} @var{symbol} @key{RET} +Search backward for @var{symbol}, nonincrementally. +@end table + +@kindex M-s _ +@findex isearch-forward-symbol + To begin a forward incremental symbol search, type @kbd{M-s _}. If +incremental search is not already active, this runs the command +@code{isearch-forward-symbol}. If incremental search is already +active, @kbd{M-s _} switches to a symbol search, preserving the +direction of the search and the current search string; you can disable +symbol search by typing @kbd{M-s _} again. In incremental symbol +search, only the beginning of the search string is required to match +the beginning of a symbol. + + To begin a nonincremental symbol search, type @kbd{M-s _ @key{RET}} +for a forward search, or @kbd{M-s _ C-r @key{RET}} or a backward +search. In nonincremental symbol searches, the beginning and end of +the search string are required to match the beginning and end of a +symbol, respectively. + @node Regexp Search @section Regular Expression Search @cindex regexp search === modified file 'doc/emacs/windows.texi' --- doc/emacs/windows.texi 2012-09-07 10:27:11 +0000 +++ doc/emacs/windows.texi 2012-10-27 05:03:52 +0000 @@ -384,12 +384,6 @@ are considered, but windows on other frames are also reusable if you change @code{pop-up-frames} (see below) to @code{t}. -@item -Otherwise, if you specified that the buffer should be displayed in a -special frame by customizing @code{special-display-buffer-names} or -@code{special-display-regexps}, do so. @xref{Choosing Window -Options,,, elisp, The Emacs Lisp Reference Manual}. - @vindex pop-up-frames @item Otherwise, optionally create a new frame and display the buffer there. === modified file 'doc/lispref/ChangeLog' --- doc/lispref/ChangeLog 2012-10-24 14:38:49 +0000 +++ doc/lispref/ChangeLog 2012-10-27 05:03:52 +0000 @@ -1,3 +1,29 @@ +2012-10-27 Chong Yidong + + * minibuf.texi (High-Level Completion): Don't mention removed + function iswitchb-read-buffer. + + * commands.texi (Event Input Misc): Remove last-input-char. + (Command Loop Info): Remove last-command-char. + + * frames.texi (Initial Parameters): Don't mention the obsolete + special-display feature. + + * windows.texi (Choosing Window): Don't mention the obsolete + special display feature. + (Choosing Window Options): Remove obsolete special-display + variables, and the functions special-display-p and + special-display-popup-frame. + + * display.texi (Fringe Bitmaps): Add exclamation-mark bitmap. + + * hooks.texi (Standard Hooks): Remove obsolete hooks. + + * markers.texi (Information from Markers): Remove obsolete + function buffer-has-markers-at. + + * text.texi (Yanking): Document yank-handled-properties. + 2012-10-24 Paul Eggert Update manual for new time stamp format (Bug#12706). === modified file 'doc/lispref/anti.texi' --- doc/lispref/anti.texi 2012-05-27 01:34:14 +0000 +++ doc/lispref/anti.texi 2012-10-27 05:03:52 +0000 @@ -71,9 +71,8 @@ related variables, as well as the @var{action} argument to @code{display-buffer} and other functions. The way to programmatically control how Emacs chooses a window to display a -buffer is to bind the right combination of -@code{special-display-regexps}, @code{pop-up-frames}, and other -variables. +buffer is to bind the right combination of @code{pop-up-frames} and +other variables. @item The standard completion interface has been simplified, eliminating the === modified file 'doc/lispref/commands.texi' --- doc/lispref/commands.texi 2012-10-05 05:57:24 +0000 +++ doc/lispref/commands.texi 2012-10-27 05:03:52 +0000 @@ -186,7 +186,6 @@ the name of an existing buffer, which becomes the second and final argument. -@c Emacs 19 feature The prompt string can use @samp{%} to include previous argument values (starting with the first argument) in the prompt. This is done using @code{format} (@pxref{Formatting Strings}). For example, here is how @@ -205,7 +204,6 @@ signaled if the buffer is read-only. @cindex @samp{@@} in @code{interactive} -@c Emacs 19 feature If @samp{@@} appears at the beginning of the string, and if the key sequence used to invoke the command includes any mouse events, then the window associated with the first of those events is selected @@ -910,7 +908,6 @@ @end defvar @defvar last-command-event -@defvarx last-command-char This variable is set to the last input event that was read by the command loop as part of a command. The principal use of this variable is in @code{self-insert-command}, which uses it to decide which @@ -926,11 +923,8 @@ @noindent The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}. - -The alias @code{last-command-char} is obsolete. @end defvar -@c Emacs 19 feature @defvar last-event-frame This variable records which frame the last input event was directed to. Usually this is the frame that was selected when the event was @@ -2386,7 +2380,6 @@ @end example @defvar num-input-keys -@c Emacs 19 feature This variable's value is the number of key sequences processed so far in this Emacs session. This includes key sequences read from the terminal and key sequences read from keyboard macros being executed. @@ -2539,7 +2532,6 @@ @code{keyboard-translate-table} (if applicable), before returning it from @code{read-event}. -@c Emacs 19 feature @defvar extra-keyboard-modifiers This variable lets Lisp programs ``press'' the modifier keys on the keyboard. The value is a character. Only the modifiers of the @@ -2755,7 +2747,6 @@ @end defun @defvar last-input-event -@defvarx last-input-char This variable records the last terminal input event read, whether as part of a command or explicitly by a Lisp program. @@ -2774,8 +2765,6 @@ @result{} 49 @end group @end example - -The alias @code{last-input-char} is obsolete. @end defvar @defmac while-no-input body@dots{} === modified file 'doc/lispref/display.texi' --- doc/lispref/display.texi 2012-10-23 02:39:13 +0000 +++ doc/lispref/display.texi 2012-10-27 05:03:52 +0000 @@ -3550,8 +3550,8 @@ @itemx @code{vertical-bar}, @code{horizontal-bar} Used for different types of fringe cursors. -@item @code{empty-line}, @code{question-mark}, @code{exclamation-mark} -Unused. +@item @code{empty-line}, @code{exclamation-mark}, @code{question-mark}, @code{exclamation-mark} +Not used by core Emacs features. @end table @noindent === modified file 'doc/lispref/frames.texi' --- doc/lispref/frames.texi 2012-09-30 09:18:38 +0000 +++ doc/lispref/frames.texi 2012-10-27 05:03:52 +0000 @@ -437,13 +437,11 @@ Window System, you can get the same results by means of X resources in many cases. -Setting this variable does not affect existing frames. +Setting this variable does not affect existing frames. Furthermore, +functions that display a buffer in a separate frame may override the +default parameters by supplying their own parameters. @end defopt -Functions that display a buffer in a separate frame can override the -default parameters by supplying their own parameters. @xref{Definition -of special-display-frame-alist}. - If you invoke Emacs with command-line options that specify frame appearance, those options take effect by adding elements to either @code{initial-frame-alist} or @code{default-frame-alist}. Options === modified file 'doc/lispref/hooks.texi' --- doc/lispref/hooks.texi 2012-10-23 15:06:07 +0000 +++ doc/lispref/hooks.texi 2012-10-27 05:03:52 +0000 @@ -120,14 +120,7 @@ @item delete-terminal-functions @xref{Multiple Terminals}. -@ignore -@item disabled-command-function -@xref{Disabling Commands}. -@end ignore - -@item display-buffer-function @itemx pop-up-frame-function -@itemx special-display-function @itemx split-window-preferred-function @xref{Choosing Window Options}. @@ -272,7 +265,6 @@ input-method-function load-read-function load-source-file-function -macro-declaration-function read-buffer-function ring-bell-function select-safe-coding-system-function === modified file 'doc/lispref/markers.texi' --- doc/lispref/markers.texi 2012-09-07 04:51:26 +0000 +++ doc/lispref/markers.texi 2012-10-27 05:03:52 +0000 @@ -307,11 +307,6 @@ @end example @end defun -@defun buffer-has-markers-at position -This function returns @code{t} if one or more markers -point at position @var{position} in the current buffer. -@end defun - @node Marker Insertion Types @section Marker Insertion Types === modified file 'doc/lispref/minibuf.texi' --- doc/lispref/minibuf.texi 2012-10-24 14:38:49 +0000 +++ doc/lispref/minibuf.texi 2012-10-27 05:03:52 +0000 @@ -1218,11 +1218,9 @@ @end defun @defopt read-buffer-function -This variable specifies how to read buffer names. The function is -called with the arguments passed to @code{read-buffer}. For example, -if you set this variable to @code{iswitchb-read-buffer}, all Emacs -commands that call @code{read-buffer} to read a buffer name will -actually use the @code{iswitchb} package to read it. +This variable, if non-@code{nil}, specifies a function for reading +buffer names. @code{read-buffer} calls this function instead of doing +its usual work, with the same arguments passed to @code{read-buffer}. @end defopt @defopt read-buffer-completion-ignore-case === modified file 'doc/lispref/text.texi' --- doc/lispref/text.texi 2012-10-23 07:57:42 +0000 +++ doc/lispref/text.texi 2012-10-27 05:03:52 +0000 @@ -899,31 +899,34 @@ @node Yanking @subsection Yanking - Yanking means inserting text from the kill ring, but it does -not insert the text blindly. Yank commands and some other commands -use @code{insert-for-yank} to perform special processing on the -text that they copy into the buffer. + Yanking means inserting text from the kill ring, but it does not +insert the text blindly. The @code{yank} command, and related +commands, use @code{insert-for-yank} to perform special processing on +the text before it is inserted. @defun insert-for-yank string -This function normally works like @code{insert} except that it doesn't -insert the text properties (@pxref{Text Properties}) in the list -variable @code{yank-excluded-properties}. However, if any part of -@var{string} has a non-@code{nil} @code{yank-handler} text property, -that property can do various special processing on that part of the -text being inserted. +This function works like @code{insert}, except that it processes the +text in @var{string} according to the @code{yank-handler} text +property, as well as the variables @code{yank-handled-properties} and +@code{yank-excluded-properties} (see below), before inserting the +result into the current buffer. @end defun @defun insert-buffer-substring-as-yank buf &optional start end -This function resembles @code{insert-buffer-substring} except that it -doesn't insert the text properties in the -@code{yank-excluded-properties} list. +This function resembles @code{insert-buffer-substring}, except that it +processes the text according to @code{yank-handled-properties} and +@code{yank-excluded-properties}. (It does not handle the +@code{yank-handler} property, which does not normally occur in buffer +text anyway.) @end defun - You can put a @code{yank-handler} text property on all or part of -the text to control how it will be inserted if it is yanked. The -@code{insert-for-yank} function looks for that property. The property -value must be a list of one to four elements, with the following -format (where elements after the first may be omitted): + If you put a @code{yank-handler} text property on all or part of a +string, that alters how @code{insert-for-yank} inserts the string. If +different parts of the string have different @code{yank-handler} +values (comparison being done with @code{eq}), each substring is +handled separately. The property value must be a list of one to four +elements, with the following format (where elements after the first +may be omitted): @example (@var{function} @var{param} @var{noexclude} @var{undo}) @@ -933,22 +936,21 @@ @table @var @item function -When @var{function} is present and non-@code{nil}, it is called instead of -@code{insert} to insert the string. @var{function} takes one -argument---the string to insert. +When @var{function} is non-@code{nil}, it is called instead of +@code{insert} to insert the string, with one argument---the string to +insert. @item param If @var{param} is present and non-@code{nil}, it replaces @var{string} -(or the part of @var{string} being processed) as the object passed to -@var{function} (or @code{insert}); for example, if @var{function} is -@code{yank-rectangle}, @var{param} should be a list of strings to -insert as a rectangle. +(or the substring of @var{string} being processed) as the object +passed to @var{function} (or @code{insert}). For example, if +@var{function} is @code{yank-rectangle}, @var{param} should be a list +of strings to insert as a rectangle. @item noexclude -If @var{noexclude} is present and non-@code{nil}, the normal removal of the -yank-excluded-properties is not performed; instead @var{function} is -responsible for removing those properties. This may be necessary -if @var{function} adjusts point before or after inserting the object. +If @var{noexclude} is present and non-@code{nil}, that disables the +normal action of @code{yank-handled-properties} and +@code{yank-excluded-properties} on the inserted string. @item undo If @var{undo} is present and non-@code{nil}, it is a function that will be @@ -959,14 +961,29 @@ @end table @cindex yanking and text properties +@defopt yank-handled-properties +This variable specifies special text property handling conditions for +yanked text. It takes effect after the text has been inserted (either +normally, or via the @code{yank-handler} property), and prior to +@code{yank-excluded-properties} taking effect. + +The value should be an alist of elements @code{(@var{prop} +. @var{fun})}. Each alist element is handled in order. The inserted +text is scanned for stretches of text having text properties @code{eq} +to @var{prop}; for each such stretch, @var{fun} is called with three +arguments: the value of the property, and the start and end positions +of the text. +@end defopt + @defopt yank-excluded-properties -Yanking discards certain text properties from the yanked text, as -described above. The value of this variable is the list of properties -to discard. Its default value contains properties that might lead to -annoying results, such as causing the text to respond to the mouse or -specifying key bindings. +The value of this variable is the list of properties to remove from +inserted text. Its default value contains properties that might lead +to annoying results, such as causing the text to respond to the mouse +or specifying key bindings. It takes effect after +@code{yank-handled-properties}. @end defopt + @node Yank Commands @subsection Functions for Yanking === modified file 'doc/lispref/windows.texi' --- doc/lispref/windows.texi 2012-09-07 13:53:21 +0000 +++ doc/lispref/windows.texi 2012-10-27 05:03:52 +0000 @@ -1632,11 +1632,6 @@ The user option @code{display-buffer-alist}. @item -A special action for handling @code{special-display-buffer-names} and -@code{special-display-regexps}, if either of those variables is -non-@code{nil}. @xref{Choosing Window Options}. - -@item The @var{action} argument. @item @@ -1864,91 +1859,6 @@ @code{nil}. @end defopt -@defopt special-display-buffer-names -A list of buffer names identifying buffers that should be displayed -specially. If the name of @var{buffer-or-name} is in this list, -@code{display-buffer} handles the buffer specially. By default, special -display means to give the buffer a dedicated frame. - -If an element is a list, instead of a string, then the @sc{car} of that -list is the buffer name, and the rest of that list says how to create -the frame. There are two possibilities for the rest of that list (its -@sc{cdr}): It can be an alist, specifying frame parameters, or it can -contain a function and arguments to give to it. (The function's first -argument is always the buffer to be displayed; the arguments from the -list come after that.) - -For example: - -@example -(("myfile" (minibuffer) (menu-bar-lines . 0))) -@end example - -@noindent -specifies to display a buffer named @samp{myfile} in a dedicated frame -with specified @code{minibuffer} and @code{menu-bar-lines} parameters. - -The list of frame parameters can also use the phony frame parameters -@code{same-frame} and @code{same-window}. If the specified frame -parameters include @code{(same-window . @var{value})} and @var{value} -is non-@code{nil}, that means to display the buffer in the current -selected window. Otherwise, if they include @code{(same-frame . -@var{value})} and @var{value} is non-@code{nil}, that means to display -the buffer in a new window in the currently selected frame. -@end defopt - -@defopt special-display-regexps -A list of regular expressions specifying buffers that should be -displayed specially. If the buffer's name matches any of the regular -expressions in this list, @code{display-buffer} handles the buffer -specially. By default, special display means to give the buffer a -dedicated frame. - -If an element is a list, instead of a string, then the @sc{car} of the -list is the regular expression, and the rest of the list says how to -create the frame. See @code{special-display-buffer-names} above. -@end defopt - -@defun special-display-p buffer-name -This function returns non-@code{nil} if displaying a buffer -named @var{buffer-name} with @code{display-buffer} would -create a special frame. The value is @code{t} if it would -use the default frame parameters, or else the specified list -of frame parameters. -@end defun - -@defopt special-display-function -This variable holds the function to call to display a buffer specially. -It receives the buffer as an argument, and should return the window in -which it is displayed. The default value of this variable is -@code{special-display-popup-frame}, see below. -@end defopt - -@defun special-display-popup-frame buffer &optional args -This function tries to make @var{buffer} visible in a frame of its own. -If @var{buffer} is already displayed in some window, it makes that -window's frame visible and raises it. Otherwise, it creates a frame -that is dedicated to @var{buffer}. The return value is the window used -to display @var{buffer}. - -If @var{args} is an alist, it specifies frame parameters for the new -frame. If @var{args} is a list whose @sc{car} is a symbol, then -@code{(car @var{args})} is a function to actually create and -set up the frame; it is called with @var{buffer} as first argument, and -@code{(cdr @var{args})} as additional arguments. - -This function always uses an existing window displaying @var{buffer}, -whether or not it is in a frame of its own; but if you set up the above -variables in your init file, before @var{buffer} was created, then -presumably the window was previously made by this function. -@end defun - -@defopt special-display-frame-alist -@anchor{Definition of special-display-frame-alist} -This variable holds frame parameters for -@code{special-display-popup-frame} to use when it creates a frame. -@end defopt - @defopt same-window-buffer-names A list of buffer names for buffers that should be displayed in the selected window. If a buffer's name is in this list, @@ -1969,19 +1879,6 @@ put it in the selected window. @end defun -@c Emacs 19 feature -@defopt display-buffer-function -This variable is the most flexible way to customize the behavior of -@code{display-buffer}. If it is non-@code{nil}, it should be a function -that @code{display-buffer} calls to do the work. The function should -accept two arguments, the first two arguments that @code{display-buffer} -received. It should choose or create a window, display the specified -buffer in it, and then return the window. - -This variable takes precedence over all the other options described -above. -@end defopt - @node Window History @section Window History @cindex window history === modified file 'etc/NEWS' --- etc/NEWS 2012-10-25 01:24:21 +0000 +++ etc/NEWS 2012-10-27 05:03:52 +0000 @@ -157,6 +157,7 @@ --- *** New option `server-auth-key' specifies a shared server key. ++++ ** In the Package Menu, newly-available packages are listed as "new", and sorted above the other "available" packages by default. @@ -229,7 +230,7 @@ *** New option `replace-lax-whitespace'. If non-nil, `query-replace' uses flexible whitespace matching too. The default is nil. - ++++ *** Global `M-s _' starts a symbol (identifier) incremental search, and `M-s _' in Isearch toggles symbol search mode. `M-s c' in Isearch toggles search case-sensitivity. @@ -263,6 +264,7 @@ ** New command `C-x r M-w' (copy-rectangle-as-kill). It copies the region-rectangle as the last rectangle kill. ++++ ** New option `yank-handled-properties' allows processing of text properties on yanked text, in more ways that are more general than just removing them, as done by `yank-excluded-properties'. @@ -327,7 +329,7 @@ rather than making them unbound. ** Compilation mode - ++++ *** New option `compilation-always-kill'. ** Customize @@ -441,9 +443,9 @@ The old binding for `/ M' (filter by used-mode) is now bound to `/ m'. ** Mouse Avoidance mode - -The new variable `mouse-avoidance-banish-position' can now be used to -customize Mouse Avoidance mode further. ++++ +*** New variable `mouse-avoidance-banish-position' specifies where the +`banish' mouse avoidance setting moves the mouse. +++ ** notifications.el supports now version 1.2 of the Notifications API. @@ -595,6 +597,7 @@ The `url-retrieve' function now uses this to encode its URL argument, in case that is not properly encoded. +--- ** VHDL mode *** The free software compiler GHDL is supported (and now the default). @@ -605,7 +608,10 @@ *** Accepts \r and \f as whitespace. -** which-function-mode now applies to all applicable major modes by default. +** Which Function mode ++++ +*** `which-func-modes' now defaults to t, so Which Function mode, when +enabled, applies to all applicable major modes. --- ** winner-mode-hook now runs when the mode is disabled, as well as when it is @@ -708,6 +714,7 @@ Some Lisp symbols have been renamed to avoid problems with spelling that is incorrect or inconsistent with how Emacs normally spells a word. +--- *** Renamed functions **** hangul-input-method-inactivate -> hangul-input-method-deactivate @@ -719,22 +726,22 @@ viper-deactivate-input-method-action **** ucs-input-inactivate -> ucs-input-deactivate +--- *** Renamed hooks The old hooks are still supported for backward compatibility, but they are deprecated and will be removed eventually. - **** input-method-inactivate-hook -> input-method-deactivate-hook **** robin-inactivate-hook -> robin-deactivate-hook **** quail-inactivate-hook -> quail-deactivate-hook +--- *** Renamed Lisp variables - **** follow-deactive-menu -> follow-inactive-menu **** inactivate-current-input-method-function -> deactivate-current-input-method-function ++++ ** Some obsolete functions, variables, and faces were removed: - *** `facemenu-unlisted-faces' *** `rmail-decode-mime-charset' *** `last-input-char', `last-command-char', `unread-command-char'. @@ -835,11 +842,17 @@ in Emacs 24.1: +++ **** `display-buffer-reuse-frames' ++++ **** `special-display-regexps' ++++ **** `special-display-frame-alist' ++++ **** `special-display-buffer-names' ++++ **** `special-display-function' ++++ **** `display-buffer-function' +--- **** `dired-shrink-to-fit' ** Time @@ -897,19 +910,26 @@ ** New macros `setq-local' and `defvar-local'. ++++ ** New fringe bitmap `exclamation-mark'. ** Face underlining can now use a wave. See the "Face Attributes" section of the Elisp manual. ** The following functions and variables are obsolete: - +--- *** `automount-dir-prefix' ++++ *** `buffer-has-markers-at' +--- *** `macro-declaration-function' (use `macro-declarations-alist') +--- *** `window-system-version' +--- *** `dired-pop-to-buffer' (use `dired-mark-pop-up') +--- *** `query-replace-interactive' +--- *** `font-list-limit' (has had no effect since Emacs < 23) @@ -928,6 +948,7 @@ Emacs now supports mouse highlight, help-echo (in the echo area), and `mouse-autoselect-window'. ++++ ** On MS Windows Vista and later Emacs now supports symbolic links. +++ === modified file 'lisp/ChangeLog' --- lisp/ChangeLog 2012-10-26 20:44:38 +0000 +++ lisp/ChangeLog 2012-10-27 05:03:52 +0000 @@ -1,3 +1,7 @@ +2012-10-27 Chong Yidong + + * subr.el (insert-buffer-substring-as-yank): Doc fix. + 2012-10-26 Jambunathan K * minibuffer.el (completion-category-overrides): New completion === modified file 'lisp/subr.el' --- lisp/subr.el 2012-10-23 15:06:07 +0000 +++ lisp/subr.el 2012-10-27 05:03:52 +0000 @@ -2949,8 +2949,8 @@ BUFFER may be a buffer or a buffer name. Arguments START and END are character positions specifying the substring. They default to the values of (point-min) and (point-max) in BUFFER. -Strip text properties from the inserted text according to -`yank-excluded-properties'." +Before insertion, process text properties according to +`yank-handled-properties' and `yank-excluded-properties'." ;; Since the buffer text should not normally have yank-handler properties, ;; there is no need to handle them here. (let ((opoint (point)))