X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/47854a55680b5809811caf72f66ecbe8289c2855..0f631634b23efe1d96d9686241d3a85852d07c7a:/doc/lispref/buffers.texi diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 2d7faccf24..d55ffe43b6 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -1,7 +1,7 @@ @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 @@ -30,6 +30,7 @@ not be displayed in any windows. * 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 @@ -193,13 +194,13 @@ This function returns the current buffer. @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{} @@ -218,13 +219,12 @@ remains current. @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{} @@ -269,8 +269,8 @@ space also initially disables recording undo information; see @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}. @@ -584,7 +584,7 @@ The counter can wrap around occasionally. 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 @@ -771,36 +771,37 @@ signal an error if the current buffer is read-only. @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 @@ -820,11 +821,10 @@ which frames they were selected in. @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) @@ -837,20 +837,21 @@ is an easy way: 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 @@ -860,35 +861,58 @@ is @code{nil}, that buffer is ignored. @xref{Buffer Parameters}. @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 @@ -904,15 +928,16 @@ buffer and gives it a unique name. @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 @@ -995,10 +1020,11 @@ this feature to test whether a buffer has been killed: @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. @@ -1011,6 +1037,9 @@ It does this even if not called interactively. To prevent the request 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 @@ -1136,6 +1165,44 @@ to the current buffer. If @var{buffer} is not indirect, the value is 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