diff options
Diffstat (limited to 'lispref/buffers.texi')
| -rw-r--r-- | lispref/buffers.texi | 828 |
1 files changed, 828 insertions, 0 deletions
diff --git a/lispref/buffers.texi b/lispref/buffers.texi new file mode 100644 index 00000000000..6f777d7480c --- /dev/null +++ b/lispref/buffers.texi @@ -0,0 +1,828 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/buffers +@node Buffers, Windows, Backups and Auto-Saving, Top +@chapter Buffers +@cindex buffer + + A @dfn{buffer} is a Lisp object containing text to be edited. Buffers +are used to hold the contents of files that are being visited; there may +also be buffers which are not visiting files. While several buffers may +exist at one time, exactly one buffer is designated the @dfn{current +buffer} at any time. Most editing commands act on the contents of the +current buffer. Each buffer, including the current buffer, may or may +not be displayed in any windows. + +@menu +* Buffer Basics:: What is a buffer? +* Buffer Names:: Accessing and changing buffer names. +* Buffer File Name:: The buffer file name indicates which file is visited. +* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. +* Modification Time:: Determining whether the visited file was changed + ``behind Emacs's back''. +* Read Only Buffers:: Modifying text is not allowed in a read-only buffer. +* The Buffer List:: How to look at all the existing buffers. +* Creating Buffers:: Functions that create buffers. +* Killing Buffers:: Buffers exist until explicitly killed. +* Current Buffer:: Designating a buffer as current + so primitives will access its contents. +@end menu + +@node Buffer Basics +@comment node-name, next, previous, up +@section Buffer Basics + +@ifinfo + A @dfn{buffer} is a Lisp object containing text to be edited. Buffers +are used to hold the contents of files that are being visited; there may +also be buffers which are not visiting files. While several buffers may +exist at one time, exactly one buffer is designated the @dfn{current +buffer} at any time. Most editing commands act on the contents of the +current buffer. Each buffer, including the current buffer, may or may +not be displayed in any windows. +@end ifinfo + + Buffers in Emacs editing are objects which have distinct names and +hold text that can be edited. Buffers appear to Lisp programs as a +special data type. The contents of a buffer may be viewed as an +extendable string; insertions and deletions may occur in any part of the +buffer. @xref{Text}. + + A Lisp buffer object contains numerous pieces of information. Some of +this information is directly accessible to the programmer through +variables, while other information is only accessible through +special-purpose functions. For example, the visited file name is +directly accessible through a variable, while the value of point is +accessible only through a primitive function. + + Buffer-specific information that is directly accessible is stored in +@dfn{buffer-local} variable bindings, which are variable values that are +effective only in a particular buffer. This feature allows each buffer +to override the values of certain variables. Most major modes override +variables such as @code{fill-column} or @code{comment-column} in this +way. For more information about buffer-local variables and functions +related to them, see @ref{Buffer-Local Variables}. + + For functions and variables related to visiting files in buffers, see +@ref{Visiting Files} and @ref{Saving Buffers}. For functions and +variables related to the display of buffers in windows, see +@ref{Buffers and Windows}. + +@defun bufferp object +This function returns @code{t} if @var{object} is a buffer, +@code{nil} otherwise. +@end defun + +@node Buffer Names +@section Buffer Names +@cindex buffer names + + Each buffer has a unique name, which is a string. Many of the +functions that work on buffers accept either a buffer or a buffer name +as an argument. Any argument called @var{buffer-or-name} is of this +sort, and an error is signaled if it is neither a string nor a buffer. +Any argument called @var{buffer} must be an actual buffer +object, not a name. + + Buffers that are ephemeral and generally uninteresting to the user +have names starting with a space, so that the @code{list-buffers} or +@code{buffer-menu} commands don't mention them. A name starting with +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. + +If @code{buffer-name} returns @code{nil}, it means that @var{buffer} +has been killed. @xref{Killing Buffers}. + +@example +@group +(buffer-name) + @result{} "buffers.texi" +@end group + +@group +(setq foo (get-buffer "temp")) + @result{} #<buffer temp> +@end group +@group +(kill-buffer foo) + @result{} nil +@end group +@group +(buffer-name foo) + @result{} nil +@end group +@group +foo + @result{} #<killed buffer> +@end group +@end example +@end defun + +@deffn Command rename-buffer newname &optional unique +This function renames the current buffer to @var{newname}. An error +is signaled if @var{newname} is not a string, or if there is already a +buffer with that name. The function returns @code{nil}. + +@c Emacs 19 feature +Ordinarily, @code{rename-buffer} signals an error if @var{newname} is +already in use. However, if @var{unique} is non-@code{nil}, it modifies +@var{newname} to make a name that is not in use. Interactively, you can +make @var{unique} non-@code{nil} with a numeric prefix argument. + +One application of this command is to rename the @samp{*shell*} buffer +to some other name, thus making it possible to create a second shell +buffer under the name @samp{*shell*}. +@end deffn + +@defun get-buffer buffer-or-name +This function returns the buffer specified by @var{buffer-or-name}. +If @var{buffer-or-name} is a string and there is no buffer with that +name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it +is returned as given. (That is not very useful, so the argument is usually +a name.) For example: + +@example +@group +(setq b (get-buffer "lewis")) + @result{} #<buffer lewis> +@end group +@group +(get-buffer b) + @result{} #<buffer lewis> +@end group +@group +(get-buffer "Frazzle-nots") + @result{} nil +@end group +@end example + +See also the function @code{get-buffer-create} in @ref{Creating Buffers}. +@end defun + +@c Emacs 19 feature +@defun generate-new-buffer-name starting-name +This function returns a name that would be unique for a new buffer---but +does not create the buffer. It starts with @var{starting-name}, and +produces a name not currently in use for any buffer by appending a +number inside of @samp{<@dots{}>}. + +See the related function @code{generate-new-buffer} in @ref{Creating +Buffers}. +@end defun + +@node Buffer File Name +@section Buffer File Name +@cindex visited file +@cindex buffer file name +@cindex file name of buffer + + The @dfn{buffer file name} is the name of the file that is visited in +that buffer. When a buffer is not visiting a file, its buffer file name +is @code{nil}. Most of the time, the buffer name is the same as the +nondirectory part of the buffer file name, but the buffer file name and +the buffer name are distinct and can be set independently. +@xref{Visiting Files}. + +@defun buffer-file-name &optional buffer +This function returns the absolute file name of the file that +@var{buffer} is visiting. If @var{buffer} is not visiting any file, +@code{buffer-file-name} returns @code{nil}. If @var{buffer} is not +supplied, it defaults to the current buffer. + +@example +@group +(buffer-file-name (other-buffer)) + @result{} "/usr/user/lewis/manual/files.texi" +@end group +@end example +@end defun + +@defvar buffer-file-name +This buffer-local variable contains the name of the file being visited +in the current buffer, or @code{nil} if it is not visiting a file. It +is a permanent local, unaffected by @code{kill-local-variables}. + +@example +@group +buffer-file-name + @result{} "/usr/user/lewis/manual/buffers.texi" +@end group +@end example + +It is risky to change this variable's value without doing various other +things. See the definition of @code{set-visited-file-name} in +@file{files.el}; some of the things done there, such as changing the +buffer name, are not strictly necessary, but others are essential to +avoid confusing Emacs. +@end defvar + +@defvar buffer-file-truename +This buffer-local variable holds the truename of the file visited in the +current buffer, or @code{nil} if no file is visited. It is a permanent +local, unaffected by @code{kill-local-variables}. @xref{Truenames}. +@end defvar + +@defvar buffer-file-number +This buffer-local variable holds the file number and directory device +number of the file visited in the current buffer, or @code{nil} if no +file or a nonexistent file is visited. It is a permanent local, +unaffected by @code{kill-local-variables}. @xref{Truenames}. + +The value is normally a list of the form @code{(@var{filenum} +@var{devnum})}. This pair of numbers uniquely identifies the file among +all files accessible on the system. See the function +@code{file-attributes}, in @ref{File Attributes}, for more information +about them. +@end defvar + +@defun get-file-buffer filename +This function returns the buffer visiting file @var{filename}. If +there is no such buffer, it returns @code{nil}. The argument +@var{filename}, which must be a string, is expanded (@pxref{File Name +Expansion}), then compared against the visited file names of all live +buffers. + +@example +@group +(get-file-buffer "buffers.texi") + @result{} #<buffer buffers.texi> +@end group +@end example + +In unusual circumstances, there can be more than one buffer visiting +the same file name. In such cases, this function returns the first +such buffer in the buffer list. +@end defun + +@deffn Command set-visited-file-name filename +If @var{filename} is a non-empty string, this function changes the +name of the file visited in current buffer to @var{filename}. (If the +buffer had no visited file, this gives it one.) The @emph{next time} +the buffer is saved it will go in the newly-specified file. This +command marks the buffer as modified, since it does not (as far as Emacs +knows) match the contents of @var{filename}, even if it matched the +former visited file. + +If @var{filename} is @code{nil} or the empty string, that stands for +``no visited file''. In this case, @code{set-visited-file-name} marks +the buffer as having no visited file. + +@c Wordy to avoid overfull hbox. --rjc 16mar92 +When the function @code{set-visited-file-name} is called interactively, it +prompts for @var{filename} in the minibuffer. + +See also @code{clear-visited-file-modtime} and +@code{verify-visited-file-modtime} in @ref{Buffer Modification}. +@end deffn + +@defvar list-buffers-directory +This buffer-local variable records a string to display in a buffer +listing in place of the visited file name, for buffers that don't have a +visited file name. Dired buffers use this variable. +@end defvar + +@node Buffer Modification +@section Buffer Modification +@cindex buffer modification +@cindex modification flag (of buffer) + + Emacs keeps a flag called the @dfn{modified flag} for each buffer, to +record whether you have changed the text of the buffer. This flag is +set to @code{t} whenever you alter the contents of the buffer, and +cleared to @code{nil} when you save it. Thus, the flag shows whether +there are unsaved changes. The flag value is normally shown in the mode +line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving +Buffers}) and auto-saving (@pxref{Auto-Saving}). + + Some Lisp programs set the flag explicitly. For example, the function +@code{set-visited-file-name} sets the flag to @code{t}, because the text +does not match the newly-visited file, even if it is unchanged from the +file formerly visited. + + The functions that modify the contents of buffers are described in +@ref{Text}. + +@defun buffer-modified-p &optional buffer +This function returns @code{t} if the buffer @var{buffer} has been modified +since it was last read in from a file or saved, or @code{nil} +otherwise. If @var{buffer} is not supplied, the current buffer +is tested. +@end defun + +@defun set-buffer-modified-p flag +This function marks the current buffer as modified if @var{flag} is +non-@code{nil}, or as unmodified if the flag is @code{nil}. + +Another effect of calling this function is to cause unconditional +redisplay of the mode line for the current buffer. In fact, the +function @code{force-mode-line-update} works by doing this: + +@example +@group +(set-buffer-modified-p (buffer-modified-p)) +@end group +@end example +@end defun + +@deffn Command not-modified +This command marks the current buffer as unmodified, and not needing +to be saved. Don't use this function in programs, since it prints a +message in the echo area; use @code{set-buffer-modified-p} (above) instead. +@end deffn + +@c Emacs 19 feature +@defun buffer-modified-tick &optional buffer +This function returns @var{buffer}`s modification-count. This is a +counter that increments every time the buffer is modified. If +@var{buffer} is @code{nil} (or omitted), the current buffer is used. +@end defun + +@node Modification Time +@comment node-name, next, previous, up +@section Comparison of Modification Time +@cindex comparison of modification time +@cindex modification time, comparison of + + Suppose that you visit a file and make changes in its buffer, and +meanwhile the file itself is changed on disk. At this point, saving the +buffer would overwrite the changes in the file. Occasionally this may +be what you want, but usually it would lose valuable information. Emacs +therefore checks the file's modification time using the functions +described below before saving the file. + +@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. + +The function returns @code{t} if the last actual modification time and +Emacs's recorded modification time are the same, @code{nil} otherwise. +@end defun + +@defun clear-visited-file-modtime +This function clears out the record of the last modification time of +the file being visited by the current buffer. As a result, the next +attempt to save this buffer will not complain of a discrepancy in +file modification times. + +This function is called in @code{set-visited-file-name} and other +exceptional places where the usual test to avoid overwriting a changed +file should not be done. +@end defun + +@c Emacs 19 feature +@defun visited-file-modtime +This function returns the buffer's recorded last file modification time, +as a list of the form @code{(@var{high} . @var{low})}. (This is the +same format that @code{file-attributes} uses to return time values; see +@ref{File Attributes}.) +@end defun + +@c Emacs 19 feature +@defun set-visited-file-modtime &optional time +This function updates the buffer's record of the last modification time +of the visited file, to the value specified by @var{time} if @var{time} +is not @code{nil}, and otherwise to the last modification time of the +visited file. + +If @var{time} is not @code{nil}, it should have the form +@code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in +either case containing two integers, each of which holds 16 bits of the +time. + +This function is useful if the buffer was not read from the file +normally, or if the file itself has been changed for some known benign +reason. +@end defun + +@defun ask-user-about-supersession-threat fn +@cindex obsolete buffer +This function is used to ask a user how to proceed after an attempt to +modify an obsolete buffer. An @dfn{obsolete buffer} is an unmodified +buffer for which the associated file on disk is newer than the last +save-time of the buffer. This means some other program has probably +altered the file. + +This function is called automatically by Emacs on the proper +occasions. It exists so you can customize Emacs by redefining it. +See the file @file{userlock.el} for the standard definition. + +@kindex file-supersession +Depending on the user's answer, the function may return normally, in +which case the modification of the buffer proceeds, or it may signal a +@code{file-supersession} error with data @code{(@var{fn})}, in which +case the proposed buffer modification is not allowed. + +See also the file locking mechanism in @ref{File Locks}. +@end defun + +@node Read Only Buffers +@section Read-Only Buffers +@cindex read-only buffer +@cindex buffer, read-only + + If a buffer is @dfn{read-only}, then you cannot change its contents, +although you may change your view of the contents by scrolling and +narrowing. + + Read-only buffers are used in two kinds of situations: + +@itemize @bullet +@item +A buffer visiting a write-protected file is normally read-only. + +Here, the purpose is to show the user that editing the buffer with the +aim of saving it in the file may be futile or undesirable. The user who +wants to change the buffer text despite this can do so after clearing +the read-only flag with @kbd{C-M-q}. + +@item +Modes such as Dired and Rmail make buffers read-only when altering the +contents with the usual editing commands is probably a mistake. + +The special commands of these modes bind @code{buffer-read-only} to +@code{nil} (with @code{let}) or bind @code{inhibit-read-only} to +@code{t} around the places where they change the text. +@end itemize + +@defvar buffer-read-only +This buffer-local variable specifies whether the buffer is read-only. +The buffer is read-only if this variable is non-@code{nil}. +@end defvar + +@defvar inhibit-read-only +If this variable is non-@code{nil}, then read-only buffers and read-only +characters may be modified. The value of @code{buffer-read-only} does +not matter when @code{inhibit-read-only} is non-@code{nil}. + +If @code{inhibit-read-only} is @code{t}, all @code{read-only} text +properties have no effect (@pxref{Special Properties}). If +@code{inhibit-read-only} is a list, then @code{read-only} text +properties are ignored if they are members of the list (comparison is +done with @code{eq}). +@end defvar + +@deffn Command toggle-read-only +This command changes whether the current buffer is read-only. It is +intended for interactive use; don't 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}. +@end deffn + +@defun barf-if-buffer-read-only +This function signals a @code{buffer-read-only} error if the current +buffer is read-only. @xref{Interactive Call}, for another way to +signal an error if the current buffer is read-only. +@end defun + +@node The Buffer List +@section The Buffer List +@cindex buffer list + + The @dfn{buffer list} is a list of all live buffers. Creating a +buffer adds it to this list, and killing a buffer deletes it. The order +of the buffers in the list is based primarily on how recently each +buffer has been displayed in the selected window. Buffers move to the +front of the list when they are selected and to the end when they are +buried. Several functions, notably @code{other-buffer}, use this +ordering. A buffer list displayed for the user also follows this order. + +@defun buffer-list +This function returns a list of all buffers, including those whose names +begin with a space. The elements are actual buffers, not their names. + +@example +@group +(buffer-list) + @result{} (#<buffer buffers.texi> + #<buffer *Minibuf-1*> #<buffer buffer.c> + #<buffer *Help*> #<buffer TAGS>) +@end group + +@group +;; @r{Note that the name of the minibuffer} +;; @r{begins with a space!} +(mapcar (function buffer-name) (buffer-list)) + @result{} ("buffers.texi" " *Minibuf-1*" + "buffer.c" "*Help*" "TAGS") +@end group +@end example + +This list is a copy of a list used inside Emacs; modifying it has no +effect on the ordering of buffers. +@end defun + +@defun other-buffer &optional buffer-or-name visible-ok +This function returns the first buffer in the buffer list other than +@var{buffer-or-name}. Usually this is the buffer most recently shown in +the selected window, aside from @var{buffer-or-name}. Buffers whose +names start with a space are not considered. + +If @var{buffer-or-name} is not supplied (or if it is not a buffer), +then @code{other-buffer} returns the first buffer on the buffer list +that is not visible in any window in a visible frame. + +@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 +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 + +@deffn Command bury-buffer &optional buffer-or-name +This function 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. + +If @var{buffer-or-name} is @code{nil} or omitted, this means to bury +the current buffer. In addition, this switches to some other buffer +(obtained using @code{other-buffer}) in the selected window. If the +buffer is displayed in a window other than the selected one, it remains +there. + +If you wish to replace a buffer in all the windows that display it, use +@code{replace-buffer-in-windows}. @xref{Buffers and Windows}. +@end deffn + +@node Creating Buffers +@section Creating Buffers +@cindex creating buffers +@cindex buffers, creating + + This section describes the two primitives for creating buffers. +@code{get-buffer-create} creates a buffer if it finds no existing +buffer; @code{generate-new-buffer} always creates a new buffer, and +gives it a unique name. + + Other functions you can use to create buffers include +@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and +@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 an existing +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. + +An error is signaled if @var{name} is not a string. + +@example +@group +(get-buffer-create "foo") + @result{} #<buffer foo> +@end group +@end example + +The major mode for the new buffer is set according to the variable +@code{default-major-mode}. @xref{Auto Major Mode}. +@end defun + +@defun generate-new-buffer name +This function returns a newly created, empty buffer, but does not make +it current. If there is no buffer named @var{name}, then that is the +name of the new buffer. If that name is in use, this function adds +suffixes of the form @samp{<@var{n}>} are added to @var{name}, where +@var{n} is an integer. It tries successive integers starting with 2 +until it finds an available name. + +An error is signaled if @var{name} is not a string. + +@example +@group +(generate-new-buffer "bar") + @result{} #<buffer bar> +@end group +@group +(generate-new-buffer "bar") + @result{} #<buffer bar<2>> +@end group +@group +(generate-new-buffer "bar") + @result{} #<buffer bar<3>> +@end group +@end example + +The major mode for the new buffer is set by the value of +@code{default-major-mode}. @xref{Auto Major Mode}. + +See the related function @code{generate-new-buffer-name} in @ref{Buffer +Names}. +@end defun + +@node Killing Buffers +@section Killing Buffers +@cindex killing buffers +@cindex buffers, killing + + @dfn{Killing a buffer} makes its name unknown to Emacs and makes its +space available for other use. + + The buffer object for the buffer which has been killed remains in +existence as long as anything refers to it, but it is specially marked +so that you cannot make it current or display it. Killed buffers retain +their identity, however; two distinct buffers, when killed, remain +distinct according to @code{eq}. + + If you kill a buffer that is current or displayed in a window, Emacs +automatically selects or displays some other buffer instead. This means +that killing a buffer can in general change the current buffer. +Therefore, when you kill a buffer, you should also take the precautions +associated with changing the current buffer (unless you happen to know +that the buffer being killed isn't current). @xref{Current Buffer}. + + The @code{buffer-name} of a killed buffer is @code{nil}. You can use +this feature to test whether a buffer has been killed: + +@example +@group +(defun buffer-killed-p (buffer) + "Return t if BUFFER is killed." + (not (buffer-name buffer))) +@end group +@end example + +@deffn Command kill-buffer buffer-or-name +This function kills the buffer @var{buffer-or-name}, freeing all its +memory for use as space for other buffers. (Emacs version 18 and older +was unable to return the memory to the operating system.) It returns +@code{nil}. + +Any processes that have this buffer as the @code{process-buffer} are +sent the @code{SIGHUP} signal, which normally causes them to terminate. +(The basic meaning of @code{SIGHUP} is that a dialup line has been +disconnected.) @xref{Deleting Processes}. + +If the buffer is visiting a file and contains unsaved changes, +@code{kill-buffer} asks the user to confirm before the buffer is killed. +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}. + +@vindex kill-buffer-query-functions +You can program additional requests for confirmation. After confirming +unsaved changes, @code{kill-buffer} calls the functions in the list +@code{kill-buffer-query-functions}, in order of appearance, with no +arguments. The buffer being killed is the current buffer when they are +called. The idea is that these functions ask for confirmation from the +user for various nonstandard reasons. If any of them returns +non-@code{nil}, the buffer is not killed. + +@c Emacs 19 feature +@vindex kill-buffer-hook +Just before actually killing the buffer, after asking all questions, +@code{kill-buffer} runs the normal hook @code{kill-buffer-hook}. The +buffer to be killed is current when the hook functions run. +@xref{Hooks}. + +Killing a buffer that is already dead has no effect. + +@smallexample +(kill-buffer "foo.unchanged") + @result{} nil +(kill-buffer "foo.changed") + +---------- Buffer: Minibuffer ---------- +Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} +---------- Buffer: Minibuffer ---------- + + @result{} nil +@end smallexample +@end deffn + +@node Current Buffer +@section The Current Buffer +@cindex selecting 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 designate any buffer as current +temporarily 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 one to which the command will apply. +(@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 +this, you must use the functions described in @ref{Displaying Buffers}. + + However, 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-excursion} that will +restore the current buffer when your function is done +(@pxref{Excursions}). Here is an example, the code for the command +@code{append-to-buffer} (with the documentation string abridged): + +@example +@group +(defun append-to-buffer (buffer start end) + "Append to specified buffer the text of the region. +@dots{}" + (interactive "BAppend to buffer: \nr") + (let ((oldbuf (current-buffer))) + (save-excursion + (set-buffer (get-buffer-create buffer)) + (insert-buffer-substring oldbuf start end)))) +@end group +@end example + +@noindent +This function binds a local variable to the current buffer, and then +@code{save-excursion} records the values of point, the mark, and the +original buffer. Next, @code{set-buffer} makes another buffer current. +Finally, @code{insert-buffer-substring} copies the string from the +original current buffer to the new 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-excursion} to make sure that the +buffer current at the beginning is current again whenever the variable +is unbound. + + It is not reliable to change the current buffer back with +@code{set-buffer}, because that won't do the job if a quit happens while +the wrong buffer is current. Here is what not to do: + +@example +@group +(let (buffer-read-only + (obuf (current-buffer))) + (set-buffer @dots{}) + @dots{} + (set-buffer obuf)) +@end group +@end example + +@noindent +Using @code{save-excursion}, as shown below, handles quitting, errors +and @code{throw} as well as ordinary evaluation. + +@example +@group +(let (buffer-read-only) + (save-excursion + (set-buffer @dots{}) + @dots{})) +@end group +@end example + +@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. It does +not display the buffer in the currently selected window or in any other +window, so the user cannot necessarily see the buffer. But Lisp +programs can in any case work 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 |