@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 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
+@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
* Creating Buffers:: Functions that create buffers.
* Killing Buffers:: Buffers exist until explicitly killed.
* Indirect Buffers:: An indirect buffer shares text with some other buffer.
+* Swapping Text:: Swapping text between two buffers.
* Buffer Gap:: The gap in the buffer.
@end menu
@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 is an example, the
-code for the command @code{append-to-buffer} (with the documentation
-string abridged):
+ 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{Displaying
+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.
-@dots{}"
+ "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.
- 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
-buffer is current. Here is what @emph{not} to do:
+ Alternatively, we can use the @code{with-current-buffer} macro:
@example
@group
-(let (buffer-read-only
- (obuf (current-buffer)))
- (set-buffer @dots{})
- @dots{}
- (set-buffer obuf))
+(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
-@noindent
-Using @code{save-current-buffer}, as shown here, handles quitting,
-errors, and @code{throw}, as well as ordinary evaluation.
+ 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.
-@example
-@group
-(let (buffer-read-only)
- (save-current-buffer
- (set-buffer @dots{})
- @dots{}))
-@end group
-@end example
+ 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!
-@defun current-buffer
-This function returns the current buffer.
+ 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
+buffer is current. For instance, in the previous example, it would
+have been wrong to do this:
@example
@group
-(current-buffer)
- @result{} #<buffer buffers.texi>
+ (let ((oldbuf (current-buffer)))
+ (set-buffer (get-buffer-create buffer))
+ (insert-buffer-substring oldbuf start end)
+ (set-buffer oldbuf))
@end group
@end example
-@end defun
-
-@defun set-buffer buffer-or-name
-This function makes @var{buffer-or-name} the current buffer. This does
-not display the buffer in any window, so the user cannot necessarily see
-the buffer. But Lisp programs will now operate on it.
-This function returns the buffer identified by @var{buffer-or-name}.
-An error is signaled if @var{buffer-or-name} does not identify an
-existing buffer.
-@end defun
+@noindent
+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
@defmac with-current-buffer buffer-or-name body@dots{}
The @code{with-current-buffer} macro saves the identity of the current
buffer, makes @var{buffer-or-name} current, evaluates the @var{body}
-forms, and finally restores the buffer. The return value is the value
-of the last form in @var{body}. The current buffer is restored even
-in case of an abnormal exit via @code{throw} or error (@pxref{Nonlocal
-Exits}).
+forms, and finally restores the current buffer. @var{buffer-or-name}
+must specify an existing buffer or the name of an existing buffer.
-An error is signaled if @var{buffer-or-name} does not identify an
-existing buffer.
+The return value is the value of the last form in @var{body}. The
+current buffer is restored even in case of an abnormal exit via
+@code{throw} or error (@pxref{Nonlocal Exits}).
@end defmac
@defmac with-temp-buffer body@dots{}
@ref{Undo}.
@defun buffer-name &optional buffer
-This function returns the name of @var{buffer} as a string. If
-@var{buffer} is not supplied, it defaults to the current buffer.
+This function returns the name of @var{buffer} as a string.
+@var{buffer} defaults to the current buffer.
If @code{buffer-name} returns @code{nil}, it means that @var{buffer}
has been killed. @xref{Killing Buffers}.
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.
@section The Buffer List
@cindex buffer list
- The @dfn{buffer list} is a list of all live buffers. The order of
-the buffers in the list is based primarily on how recently each buffer
-has been displayed in a window. Several functions, notably
-@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. Buffers move to the front of the list when they
-are selected for display in a window (@pxref{Displaying Buffers}), and
-to the end when they are 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 Emacs buffer list, each frame has its
-own version of the buffer list, in which the buffers that have been
-selected in that frame come first, starting with the buffers most
-recently selected @emph{in that frame}. (This order is recorded in
-@var{frame}'s @code{buffer-list} frame parameter; see @ref{Buffer
-Parameters}.) The buffers that were never selected in @var{frame} come
-afterward, ordered according to the fundamental Emacs buffer list.
+ The @dfn{buffer list} is a list of all live buffers. The order of the
+buffers in this list is based primarily on how recently each buffer has
+been displayed in a window. Several functions, notably
+@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.
+
+ In addition to the fundamental buffer list just described, Emacs
+maintains a local buffer list for each frame, in which the buffers that
+have been displayed (or had their windows selected) in that frame come
+first. (This order is recorded in the frame's @code{buffer-list} frame
+parameter; see @ref{Buffer Parameters}.) Buffers never displayed in
+that frame come afterward, ordered according to the fundamental buffer
+list.
@defun buffer-list &optional frame
This function returns the buffer list, including all buffers, even those
whose names begin with a space. The elements are actual buffers, not
their names.
-If @var{frame} is a frame, this returns @var{frame}'s buffer list. If
-@var{frame} is @code{nil}, the fundamental Emacs buffer list is used:
-all the buffers appear in order of most recent selection, regardless of
-which frames they were selected in.
+If @var{frame} is a frame, this returns @var{frame}'s local buffer list.
+If @var{frame} is @code{nil} or omitted, the fundamental buffer list is
+used: the buffers appear in order of most recent display or selection,
+regardless of which frames they were displayed on.
@example
@group
@end example
@end defun
- The list that @code{buffer-list} returns is constructed specifically
-by @code{buffer-list}; it is not an internal Emacs data structure, and
-modifying it has no effect on the order of buffers. If you want to
-change the order of buffers in the frame-independent buffer list, here
-is an easy way:
+ The list returned by @code{buffer-list} is constructed specifically;
+it is not an internal Emacs data structure, and modifying it has no
+effect on the order of buffers. If you want to change the order of
+buffers in the fundamental buffer list, here is an easy way:
@example
(defun reorder-buffer-list (new-list)
no danger of losing a buffer or adding something that is not a valid
live buffer.
- To change the order or value of a frame's buffer list, set the frame's
-@code{buffer-list} frame parameter with @code{modify-frame-parameters}
-(@pxref{Parameter Access}).
+ To change the order or value of a specific frame's buffer list, set
+that frame's @code{buffer-list} parameter with
+@code{modify-frame-parameters} (@pxref{Parameter Access}).
@defun other-buffer &optional buffer visible-ok frame
This function returns the first buffer in the buffer list other than
-@var{buffer}. Usually this is the buffer selected most recently (in
-frame @var{frame} or else the currently selected frame, @pxref{Input
-Focus}), aside from @var{buffer}. Buffers whose names start with a
-space are not considered at all.
+@var{buffer}. Usually, this is the buffer appearing in the most
+recently selected window (in frame @var{frame} or else the selected
+frame, @pxref{Input Focus}), aside from @var{buffer}. Buffers whose
+names start with a space are not considered at all.
-If @var{buffer} is not supplied (or if it is not a buffer), then
+If @var{buffer} is not supplied (or if it is not a live buffer), then
@code{other-buffer} returns the first buffer in the selected frame's
-buffer list that is not now visible in any window in a visible frame.
+local buffer list. (If @var{frame} is non-@code{nil}, it returns the
+first buffer in @var{frame}'s local buffer list instead.)
If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter,
then @code{other-buffer} uses that predicate to decide which buffers to
@c Emacs 19 feature
If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning
a buffer visible in any window on any visible frame, except as a last
-resort. If @var{visible-ok} is non-@code{nil}, then it does not matter
+resort. If @var{visible-ok} is non-@code{nil}, then it does not matter
whether a buffer is displayed somewhere or not.
If no suitable buffer exists, the buffer @samp{*scratch*} is returned
(and created, if necessary).
@end defun
+@defun last-buffer &optional buffer visible-ok frame
+This function returns the last buffer in @var{frame}'s buffer list other
+than @var{BUFFER}. If @var{frame} is omitted or @code{nil}, it uses the
+selected frame's buffer list.
+
+The argument @var{visible-ok} is handled as with @code{other-buffer},
+see above. If no suitable buffer can be found, the buffer
+@samp{*scratch*} is returned.
+@end defun
+
@deffn Command bury-buffer &optional buffer-or-name
-This function puts @var{buffer-or-name} at the end of the buffer list,
+This command puts @var{buffer-or-name} at the end of the buffer list,
without changing the order of any of the other buffers on the list.
This buffer therefore becomes the least desirable candidate for
@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 frame-independent Emacs 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 nil)}.
+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)}.
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. But if the buffer is
-displayed in some other window, it remains displayed there.
+@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.
To replace a buffer in all the windows that display it, use
@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
+buffer returned by @code{last-buffer}, see above, in the selected
+window.
+@end deffn
+
+
@node Creating Buffers
@section Creating Buffers
@cindex creating buffers
@code{create-file-buffer} (@pxref{Visiting Files}). Starting a
subprocess can also create a buffer (@pxref{Processes}).
-@defun get-buffer-create name
-This function returns a buffer named @var{name}. It returns a live
-buffer with that name, if one exists; otherwise, it creates a new
-buffer. The buffer does not become the current buffer---this function
-does not change which buffer is current.
+@defun get-buffer-create buffer-or-name
+This function returns a buffer named @var{buffer-or-name}. The buffer
+returned does not become the current buffer---this function does not
+change which buffer is current.
-If @var{name} is a buffer instead of a string, it is returned, even if
-it is dead. An error is signaled if @var{name} is neither a string
-nor a buffer.
+@var{buffer-or-name} must be either a string or an existing buffer. If
+it is a string and a live buffer with that name already exists,
+@code{get-buffer-create} returns that buffer. If no such buffer exists,
+it creates a new buffer. If @var{buffer-or-name} is a buffer instead of
+a string, it is returned as given, even if it is dead.
@example
@group
@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
@end group
@end example
-@deffn Command kill-buffer buffer-or-name
+@deffn Command kill-buffer &optional buffer-or-name
This function kills the buffer @var{buffer-or-name}, freeing all its
memory for other uses or to be returned to the operating system. If
-@var{buffer-or-name} is @code{nil}, it kills the current buffer.
+@var{buffer-or-name} is @code{nil} or omitted, it kills the current
+buffer.
Any processes that have this buffer as the @code{process-buffer} are
sent the @code{SIGHUP} signal, which normally causes them to terminate.
for confirmation, clear the modified flag before calling
@code{kill-buffer}. @xref{Buffer Modification}.
+This function calls @code{replace-buffer-in-windows} for cleaning up
+all windows currently displaying the buffer to be killed.
+
Killing a buffer that is already dead has no effect.
This function returns @code{t} if it actually killed the buffer. It
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
indirect buffer.
@end defun
+@node Swapping Text
+@section Swapping Text Between Two Buffers
+@cindex swap text between buffers
+@cindex virtual buffers
+
+ Specialized modes sometimes need to let the user access from the
+same buffer several vastly different types of text. For example, you
+may need to display a summary of the buffer text, in addition to
+letting the user access the text itself.
+
+ This could be implemented with multiple buffers (kept in sync when
+the user edits the text), or with narrowing (@pxref{Narrowing}). But
+these alternatives might sometimes become tedious or prohibitively
+expensive, especially if each type of text requires expensive
+buffer-global operations in order to provide correct display and
+editing commands.
+
+ Emacs provides another facility for such modes: you can quickly swap
+buffer text between two buffers with @code{buffer-swap-text}. This
+function is very fast because it doesn't move any text, it only
+changes the internal data structures of the buffer object to point to
+a different chunk of text. Using it, you can pretend that a group of
+two or more buffers are actually a single virtual buffer that holds
+the contents of all the individual buffers together.
+
+@defun buffer-swap-text 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
+overlays, the text properties, the undo list, the value of the
+@code{enable-multibyte-characters} flag (@pxref{Text Representations,
+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