@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 Free Software Foundation, Inc.
+@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 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
@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 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 returns the buffer identified by @var{buffer-or-name}.
-An error is signaled if @var{buffer-or-name} does not identify an
-existing buffer.
+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
@defspec save-current-buffer body@dots{}
@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}.
This function returns @var{buffer}'s character-change modification-count.
Changes to text properties leave this counter unchanged; however, each
time text is inserted or removed from the buffer, the counter is reset
-to the value that would be returned @code{buffer-modified-tick}.
+to the value that would be returned by @code{buffer-modified-tick}.
By comparing the values returned by two @code{buffer-chars-modified-tick}
calls, you can tell whether a character change occurred in that buffer
in between the calls. If @var{buffer} is @code{nil} (or omitted), the
@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 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
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 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.
+
+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
+
@node Buffer Gap
@section The Buffer Gap