diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index e7467c20d25..6dfc203f638 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,16 @@ +2010-01-04 Stefan Monnier + + Avoid dubious uses of save-excursions. + * positions.texi (Excursions): Recommend the use of + save-current-buffer if applicable. + * text.texi (Clickable Text): Fix the example code which used + save-excursion in a naive way which sometimes preserves point and + sometimes not. + * variables.texi (Creating Buffer-Local): + * os.texi (Session Management): + * display.texi (GIF Images): + * control.texi (Cleanups): Use (save|with)-current-buffer. + 2010-01-02 Eli Zaretskii * modes.texi (Example Major Modes): Fix indentation. (Bug#5195) @@ -8375,7 +8388,7 @@ ;; End: Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, - 2007, 2008, 2009 Free Software Foundation, Inc. + 2007, 2008, 2009, 2010 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 41f844b4e21..6d7c01d354b 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1255,9 +1255,8 @@ make sure to kill it before finishing: @smallexample @group -(save-excursion - (let ((buffer (get-buffer-create " *temp*"))) - (set-buffer buffer) +(let ((buffer (get-buffer-create " *temp*"))) + (with-current-buffer buffer (unwind-protect @var{body-form} (kill-buffer buffer)))) @@ -1269,7 +1268,7 @@ You might think that we could just as well write @code{(kill-buffer (current-buffer))} and dispense with the variable @code{buffer}. However, the way shown above is safer, if @var{body-form} happens to get an error after switching to a different buffer! (Alternatively, -you could write another @code{save-excursion} around @var{body-form}, +you could write a @code{save-current-buffer} around @var{body-form}, to ensure that the temporary buffer becomes current again in time to kill it.) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 8feb8ea8c81..512d7d53019 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -4394,8 +4394,7 @@ every 0.1 seconds. (when (= idx max) (setq idx 0)) (let ((img (create-image file nil :image idx))) - (save-excursion - (set-buffer buffer) + (with-current-buffer buffer (goto-char (point-min)) (unless first-time (delete-char 1)) (insert-image img)) diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index ded70f4927b..8d62ab87499 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -2182,7 +2182,7 @@ Emacs is restarted by the session manager. @group (defun save-yourself-test () - (insert "(save-excursion + (insert "(save-current-buffer (switch-to-buffer \"*scratch*\") (insert \"I am restored\"))") nil) diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index deded596f81..3897efc6f2b 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -806,7 +806,9 @@ after the completion of the excursion. The forms for saving and restoring the configuration of windows are described elsewhere (see @ref{Window Configurations}, and @pxref{Frame -Configurations}). +Configurations}). When only the identity of the current buffer needs +to be saved and restored, it is preferable to use +@code{save-current-buffer} instead. @defspec save-excursion body@dots{} @cindex mark excursion @@ -817,10 +819,10 @@ buffer and the values of point and the mark in it, evaluates point and the mark. All three saved values are restored even in case of an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). -The @code{save-excursion} special form is the standard way to switch -buffers or move point within one part of a program and avoid affecting -the rest of the program. It is used more than 4000 times in the Lisp -sources of Emacs. +The @code{save-excursion} special form is the standard way to move +point within one part of a program and avoid affecting the rest of the +program. It is used more than 4000 times in the Lisp sources +of Emacs. @code{save-excursion} does not save the values of point and the mark for other buffers, so changes in other buffers remain in effect after diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 91b65017754..7c3f91c3fa8 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -3524,13 +3524,12 @@ following command: (defun dired-mouse-find-file-other-window (event) "In Dired, visit the file or directory name you click on." (interactive "e") - (let (window pos file) - (save-excursion - (setq window (posn-window (event-end event)) - pos (posn-point (event-end event))) - (if (not (windowp window)) - (error "No file chosen")) - (set-buffer (window-buffer window)) + (let ((window (posn-window (event-end event))) + (pos (posn-point (event-end event))) + file) + (if (not (windowp window)) + (error "No file chosen")) + (with-current-buffer (window-buffer window) (goto-char pos) (setq file (dired-get-file-for-visit))) (if (file-directory-p file) diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 4f9f9c17369..d8ab347eebf 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1240,8 +1240,7 @@ foo @group ;; @r{In buffer @samp{b2}, the value hasn't changed.} -(save-excursion - (set-buffer "b2") +(with-current-buffer "b2" foo) @result{} 5 @end group diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 27c376f764c..cabec8f7fb1 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,8 @@ +2010-01-04 Stefan Monnier + + * gnus.texi (Posting Styles): Use with-current-buffer. + * calc.texi (Defining Simple Commands): Prefer save-current-buffer. + 2010-01-02 Kevin Ryde * eieio.texi (Naming Conventions): Correction to xref on elisp @@ -6512,7 +6517,7 @@ ;; End: Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, - 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. + 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index c88bb3e9ab8..e7c03197704 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -31968,7 +31968,7 @@ the function with code that looks roughly like this: @smallexample (let ((calc-command-flags nil)) (unwind-protect - (save-excursion + (save-current-buffer (calc-select-buffer) @emph{body of function} @emph{renumber stack} diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index e90789d2494..a33a91ba6f1 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -10,7 +10,7 @@ @copying Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. +2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -13449,8 +13449,7 @@ So here's a new example: (body "You are fired.\n\nSincerely, your boss.") (organization "Important Work, Inc")) ("nnml:.*" - (From (save-excursion - (set-buffer gnus-article-buffer) + (From (with-current-buffer gnus-article-buffer (message-fetch-field "to")))) ("^nn.+:" (signature-file "~/.mail-signature"))))