@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/buffers
@node Buffers, Windows, Backups and Auto-Saving, Top
@cindex changing to another buffer
@cindex current buffer
- There are, in general, many buffers in an Emacs session. At any time,
-one of them is designated as the @dfn{current buffer}. This is the
-buffer in which most editing takes place, because most of the primitives
-for examining or changing text in a buffer operate implicitly on the
-current buffer (@pxref{Text}). Normally the buffer that is displayed on
-the screen in the selected window is the current buffer, but this is not
-always so: a Lisp program can temporarily designate any buffer as
-current in order to operate on its contents, without changing what is
-displayed on the screen.
-
- The way to designate a current buffer in a Lisp program is by calling
-@code{set-buffer}. The specified buffer remains current until a new one
-is designated.
-
- When an editing command returns to the editor command loop, the
-command loop designates the buffer displayed in the selected window as
-current, to prevent confusion: the buffer that the cursor is in when
-Emacs reads a command is the buffer that the command will apply to.
-(@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to
-switch visibly to a different buffer so that the user can edit it. For
-that, you must use the functions described in @ref{Displaying Buffers}.
-
- @strong{Warning:} Lisp functions that change to a different current buffer
-should not depend on the command loop to set it back afterwards.
-Editing commands written in Emacs Lisp can be called from other programs
-as well as from the command loop; it is convenient for the caller if
-the subroutine does not change which buffer is current (unless, of
-course, that is the subroutine's purpose). Therefore, you should
-normally use @code{set-buffer} within a @code{save-current-buffer} or
-@code{save-excursion} (@pxref{Excursions}) form that will restore the
-current buffer when your function is done. Here, as an example, is a
+ There are, in general, many buffers in an Emacs session. At any
+time, one of them is designated the @dfn{current buffer}---the buffer
+in which most editing takes place. Most of the primitives for
+examining or changing text operate implicitly on the current buffer
+(@pxref{Text}).
+
+ Normally, the buffer displayed in the selected window is the current
+buffer, but this is not always so: a Lisp program can temporarily
+designate any buffer as current in order to operate on its contents,
+without changing what is displayed on the screen. The most basic
+function for designating a current buffer is @code{set-buffer}.
+
+@defun current-buffer
+This function returns the current buffer.
+
+@example
+@group
+(current-buffer)
+ @result{} #<buffer buffers.texi>
+@end group
+@end example
+@end defun
+
+@defun set-buffer buffer-or-name
+This function makes @var{buffer-or-name} the current buffer.
+@var{buffer-or-name} must be an existing buffer or the name of an
+existing buffer. The return value is the buffer made current.
+
+This function does not display the buffer in any window, so the user
+cannot necessarily see the buffer. But Lisp programs will now operate
+on it.
+@end defun
+
+ When an editing command returns to the editor command loop, Emacs
+automatically calls @code{set-buffer} on the buffer shown in the
+selected window. This is to prevent confusion: it ensures that the
+buffer that the cursor is in, when Emacs reads a command, is the
+buffer to which that command applies (@pxref{Command Loop}). Thus,
+you should not use @code{set-buffer} to switch visibly to a different
+buffer; for that, use the functions described in @ref{Switching
+Buffers}.
+
+ When writing a Lisp function, do @emph{not} rely on this behavior of
+the command loop to restore the current buffer after an operation.
+Editing commands can also be called as Lisp functions by other
+programs, not just from the command loop; it is convenient for the
+caller if the subroutine does not change which buffer is current
+(unless, of course, that is the subroutine's purpose).
+
+ To operate temporarily on another buffer, put the @code{set-buffer}
+within a @code{save-current-buffer} form. Here, as an example, is a
simplified version of the command @code{append-to-buffer}:
@example
@group
(defun append-to-buffer (buffer start end)
- "Append to specified buffer the text of the region."
+ "Append the text of the region to BUFFER."
(interactive "BAppend to buffer: \nr")
(let ((oldbuf (current-buffer)))
(save-current-buffer
@end example
@noindent
-This function binds a local variable to record the current buffer, and
-then @code{save-current-buffer} arranges to make it current again.
-Next, @code{set-buffer} makes the specified buffer current. Finally,
+Here, we bind a local variable to record the current buffer, and then
+@code{save-current-buffer} arranges to make it current again later.
+Next, @code{set-buffer} makes the specified buffer current, and
@code{insert-buffer-substring} copies the string from the original
-current buffer to the specified (and now current) buffer.
-
- If the buffer appended to happens to be displayed in some window,
-the next redisplay will show how its text has changed. Otherwise, you
-will not see the change immediately on the screen. The buffer becomes
-current temporarily during the execution of the command, but this does
-not cause it to be displayed.
-
- If you make local bindings (with @code{let} or function arguments) for
-a variable that may also have buffer-local bindings, make sure that the
-same buffer is current at the beginning and at the end of the local
-binding's scope. Otherwise you might bind it in one buffer and unbind
-it in another! There are two ways to do this. In simple cases, you may
-see that nothing ever changes the current buffer within the scope of the
-binding. Otherwise, use @code{save-current-buffer} or
-@code{save-excursion} to make sure that the buffer current at the
-beginning is current again whenever the variable is unbound.
+buffer to the specified (and now current) buffer.
+
+ Alternatively, we can use the @code{with-current-buffer} macro:
+
+@example
+@group
+(defun append-to-buffer (buffer start end)
+ "Append the text of the region to BUFFER."
+ (interactive "BAppend to buffer: \nr")
+ (let ((oldbuf (current-buffer)))
+ (with-current-buffer (get-buffer-create buffer)
+ (insert-buffer-substring oldbuf start end))))
+@end group
+@end example
+
+ In either case, if the buffer appended to happens to be displayed in
+some window, the next redisplay will show how its text has changed.
+If it is not displayed in any window, you will not see the change
+immediately on the screen. The command causes the buffer to become
+current temporarily, but does not cause it to be displayed.
+
+ If you make local bindings (with @code{let} or function arguments)
+for a variable that may also have buffer-local bindings, make sure
+that the same buffer is current at the beginning and at the end of the
+local binding's scope. Otherwise you might bind it in one buffer and
+unbind it in another!
Do not rely on using @code{set-buffer} to change the current buffer
back, because that won't do the job if a quit happens while the wrong
@end example
@noindent
-Using @code{save-current-buffer}, as we did, handles quitting, errors,
-and @code{throw}, as well as ordinary evaluation.
-
-@defun current-buffer
-This function returns the current buffer.
-
-@example
-@group
-(current-buffer)
- @result{} #<buffer buffers.texi>
-@end group
-@end example
-@end defun
-
-@defun set-buffer buffer-or-name
-This function makes @var{buffer-or-name} the current buffer.
-@var{buffer-or-name} must be an existing buffer or the name of an
-existing buffer. The return value is the buffer made current.
-
-This function does not display the buffer in any window, so the user
-cannot necessarily see the buffer. But Lisp programs will now operate
-on it.
-@end defun
+Using @code{save-current-buffer} or @code{with-current-buffer}, as we
+did, correctly handles quitting, errors, and @code{throw}, as well as
+ordinary evaluation.
@defspec save-current-buffer body@dots{}
The @code{save-current-buffer} special form saves the identity of the
described below before saving the file. (@xref{File Attributes},
for how to examine a file's modification time.)
-@defun verify-visited-file-modtime buffer
-This function compares what @var{buffer} has recorded for the
-modification time of its visited file against the actual modification
-time of the file as recorded by the operating system. The two should be
-the same unless some other process has written the file since Emacs
-visited or saved it.
+@defun verify-visited-file-modtime &optional buffer
+This function compares what @var{buffer} (by default, the
+current-buffer) has recorded for the modification time of its visited
+file against the actual modification time of the file as recorded by the
+operating system. The two should be the same unless some other process
+has written the file since Emacs visited or saved it.
The function returns @code{t} if the last actual modification time and
Emacs's recorded modification time are the same, @code{nil} otherwise.
@deffn Command toggle-read-only &optional arg
This command toggles whether the current buffer is read-only. It is
-intended for interactive use; do not use it in programs. At any given
-point in a program, you should know whether you want the read-only flag
-on or off; so you can set @code{buffer-read-only} explicitly to the
-proper value, @code{t} or @code{nil}.
+intended for interactive use; do not use it in programs (it may have
+side-effects, such as enabling View mode, and does not affect
+read-only text properties). To change the read-only state of a buffer in
+a program, explicitly set @code{buffer-read-only} to the proper value.
+To temporarily ignore a read-only state, bind @code{inhibit-read-only}.
If @var{arg} is non-@code{nil}, it should be a raw prefix argument.
@code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if
@code{other-buffer}, use this ordering. A buffer list displayed for the
user also follows this order.
- Creating a buffer adds it to the end of the buffer list, and killing a
-buffer removes it from that list. A buffer moves to the front of this
-list whenever it is chosen for display in a window (@pxref{Displaying
-Buffers}) or a window displaying it is selected (@pxref{Selecting
-Windows}). A buffer moves to the end of the list when it is buried (see
-@code{bury-buffer}, below). There are no functions available to the
-Lisp programmer which directly manipulate the buffer list.
+ Creating a buffer adds it to the end of the buffer list, and killing
+a buffer removes it from that list. A buffer moves to the front of
+this list whenever it is chosen for display in a window
+(@pxref{Switching Buffers}) or a window displaying it is selected
+(@pxref{Selecting Windows}). A buffer moves to the end of the list
+when it is buried (see @code{bury-buffer}, below). There are no
+functions available to the Lisp programmer which directly manipulate
+the buffer list.
In addition to the fundamental buffer list just described, Emacs
maintains a local buffer list for each frame, in which the buffers that
@code{other-buffer} to return. The argument can be either a buffer
itself or the name of one.
-@code{bury-buffer} operates on each frame's @code{buffer-list} parameter
-as well as the fundamental buffer list; therefore, the buffer that you
-bury will come last in the value of @code{(buffer-list @var{frame})} and
-in the value of @code{(buffer-list)}.
+This functions operates on each frame's @code{buffer-list} parameter as
+well as the fundamental buffer list; therefore, the buffer that you bury
+will come last in the value of @code{(buffer-list @var{frame})} and in
+the value of @code{(buffer-list)}. In addition, it also puts the buffer
+at the end of the list of buffer of the selected window (@pxref{Window
+History}) provided it is shown in that window.
If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
-current buffer. In addition, if the buffer is displayed in the selected
-window, this switches to some other buffer (obtained using
-@code{other-buffer}) in the selected window. @xref{Displaying Buffers}.
-But if the selected window is dedicated to its buffer, it deletes that
-window if there are other windows left on its frame. Otherwise, if the
-selected window is the only window on its frame, it iconifies that
-frame. If @var{buffer-or-name} is displayed in some other window, it
-remains displayed there.
+current buffer. In addition, if the current buffer is displayed in the
+selected window, this makes sure that the window is either deleted or
+another buffer is shown in it. More precisely, if the window is
+dedicated (@pxref{Dedicated Windows}) and there are other windows on its
+frame, the window is deleted. If the window is both dedicated and the
+only window on its frame's terminal, the function specified by
+@code{frame-auto-hide-function} (@pxref{Quitting Windows}) will deal
+with the window. If the window is not dedicated to its buffer, it calls
+@code{switch-to-prev-buffer} (@pxref{Window History}) to show another
+buffer in that window. If @var{buffer-or-name} is displayed in some
+other window, it remains displayed there.
To replace a buffer in all the windows that display it, use
-@code{replace-buffer-in-windows}. @xref{Buffers and Windows}.
+@code{replace-buffer-in-windows}, @xref{Buffers and Windows}.
@end deffn
@deffn Command unbury-buffer
-This command switches to the last buffer in the local buffer list of the
-selected frame. More precisely, it calls the function
-@code{switch-to-buffer} (@pxref{Displaying Buffers}), to display the
+This command switches to the last buffer in the local buffer list of
+the selected frame. More precisely, it calls the function
+@code{switch-to-buffer} (@pxref{Switching Buffers}), to display the
buffer returned by @code{last-buffer}, see above, in the selected
window.
@end deffn
@end example
The major mode for a newly created buffer is set to Fundamental mode.
-(The variable @code{default-major-mode} is handled at a higher level;
-see @ref{Auto Major Mode}.) If the name begins with a space, the
+(The default value of the variable @code{major-mode} is handled at a higher
+level; see @ref{Auto Major Mode}.) If the name begins with a space, the
buffer initially disables undo information recording (@pxref{Undo}).
@end defun
@end group
@end example
-The major mode for the new buffer is set to Fundamental mode. The
-variable @code{default-major-mode} is handled at a higher level.
+The major mode for the new buffer is set to Fundamental mode. The default
+value of the variable @code{major-mode} is handled at a higher level.
@xref{Auto Major Mode}.
See the related function @code{generate-new-buffer-name} in @ref{Buffer
is not cleared by changing major modes.
@end defvar
-@defvar buffer-offer-save
+@defopt buffer-offer-save
This variable, if non-@code{nil} in a particular buffer, tells
@code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the
second optional argument to that function is @code{t}) to offer to
@xref{Definition of save-some-buffers}. The variable
@code{buffer-offer-save} automatically becomes buffer-local when set
for any reason. @xref{Buffer-Local Variables}.
-@end defvar
+@end defopt
@defvar buffer-save-without-query
This variable, if non-@code{nil} in a particular buffer, tells
buffer, not from @var{base-buffer}.
@end deffn
-@defun clone-indirect-buffer newname display-flag &optional norecord
+@deffn Command clone-indirect-buffer newname display-flag &optional norecord
This function creates and returns a new indirect buffer that shares
the current buffer's base buffer and copies the rest of the current
buffer's attributes. (If the current buffer is not indirect, it is
buffer by calling @code{pop-to-buffer}. If @var{norecord} is
non-@code{nil}, that means not to put the new buffer to the front of
the buffer list.
-@end defun
+@end deffn
@defun buffer-base-buffer &optional buffer
This function returns the base buffer of @var{buffer}, which defaults
the contents of all the individual buffers together.
@defun buffer-swap-text buffer
-This function swaps text between the current buffer and its argument
-@var{buffer}. It signals an error if one of the two buffers is an
-indirect buffer (@pxref{Indirect Buffers}) or is a base buffer of an
-indirect buffer.
+This function swaps the text of the current buffer and that of its
+argument @var{buffer}. It signals an error if one of the two buffers
+is an indirect buffer (@pxref{Indirect Buffers}) or is a base buffer
+of an indirect buffer.
All the buffer properties that are related to the buffer text are
swapped as well: the positions of point and mark, all the markers, the
enable-multibyte-characters}), etc.
@end defun
+ If you use @code{buffer-swap-text} on a file-visiting buffer, you
+should set up a hook to save the buffer's original text rather than
+what it was swapped with. @code{write-region-annotate-functions}
+works for this purpose. You should probably set
+@code{buffer-saved-size} to @minus{}2 in the buffer, so that changes
+in the text it is swapped with will not interfere with auto-saving.
+
@node Buffer Gap
@section The Buffer Gap
This function returns the current gap size of the current buffer.
@end defun
-@ignore
- arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c
-@end ignore