X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/b35f288d478ef137a4d9e8e5a6a5f368a86b01f5..762f8d96719ba3e8a0e79d8bb99fe8e119fafb3a:/doc/lispref/buffers.texi diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 56e952a44a..0f9de74c94 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, 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 @@ -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 @@ -84,45 +85,63 @@ This function returns @code{t} if @var{object} is a buffer, @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{} # +@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 @@ -132,75 +151,55 @@ string abridged): @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{} # + (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 @@ -218,13 +217,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 +267,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}. @@ -605,12 +603,12 @@ therefore checks the file's modification time using the functions 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. @@ -771,36 +769,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 +819,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 +835,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 +859,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 +926,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 @@ -922,8 +945,8 @@ nor a buffer. @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 @@ -952,8 +975,8 @@ An error is signaled if @var{name} is not a string. @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 @@ -995,10 +1018,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 +1035,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 @@ -1047,7 +1074,7 @@ The buffer to be killed is current when the hook functions run. 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 @@ -1055,7 +1082,7 @@ save that buffer, just as they offer to save file-visiting buffers. @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 @@ -1117,7 +1144,7 @@ non-@code{nil}, the initial state is copied from the actual base 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 @@ -1127,7 +1154,7 @@ If @var{display-flag} is non-@code{nil}, that means to display the new 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 @@ -1136,6 +1163,51 @@ 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 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 @@ -1160,6 +1232,3 @@ This function returns the current gap position in the current buffer. This function returns the current gap size of the current buffer. @end defun -@ignore - arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c -@end ignore