diff options
Diffstat (limited to 'lispref/buffers.texi')
| -rw-r--r-- | lispref/buffers.texi | 828 |
1 files changed, 0 insertions, 828 deletions
diff --git a/lispref/buffers.texi b/lispref/buffers.texi deleted file mode 100644 index 6f777d7480c..00000000000 --- a/lispref/buffers.texi +++ /dev/null @@ -1,828 +0,0 @@ -@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 |