GNU Info

(elisp)Current Buffer

---

Next: Buffer Names Prev: Buffer Basics Up: Buffers

---

Enter node , (file) or (file)node

The Current Buffer
==================

   There are, in general, many buffers in an Emacs session.  At any
time, one of them is designated as the "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 (Note: 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
`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.
(Note: Command Loop.)  Therefore, `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 Note: Displaying
Buffers.

   *Note:* 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 `set-buffer' within a `save-current-buffer' or
`save-excursion' (Note: Excursions) form that will restore the
current buffer when your function is done.  Here is an example, the
code for the command `append-to-buffer' (with the documentation string
abridged):

     (defun append-to-buffer (buffer start end)
       "Append to specified buffer the text of the region.
     ..."
       (interactive "BAppend to buffer: \nr")
       (let ((oldbuf (current-buffer)))
         (save-current-buffer
           (set-buffer (get-buffer-create buffer))
           (insert-buffer-substring oldbuf start end))))

This function binds a local variable to record the current buffer, and
then `save-current-buffer' arranges to make it current again.  Next,
`set-buffer' makes the specified buffer current.  Finally,
`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 `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 `save-current-buffer' or `save-excursion' to
make sure that the buffer current at the beginning is current again
whenever the variable is unbound.

   Do not rely on using `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 _not_ to do:

     (let (buffer-read-only
           (obuf (current-buffer)))
       (set-buffer ...)
       ...
       (set-buffer obuf))

Using `save-current-buffer', as shown here, handles quitting, errors,
and `throw', as well as ordinary evaluation.

     (let (buffer-read-only)
       (save-current-buffer
         (set-buffer ...)
         ...))

 - Function: current-buffer
     This function returns the current buffer.

          (current-buffer)
               => #<buffer buffers.texi>

 - Function: set-buffer buffer-or-name
     This function makes 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 BUFFER-OR-NAME.  An
     error is signaled if BUFFER-OR-NAME does not identify an existing
     buffer.

 - Special Form: save-current-buffer body...
     The `save-current-buffer' macro saves the identity of the current
     buffer, evaluates the BODY forms, and finally restores that buffer
     as current.  The return value is the value of the last form in
     BODY.  The current buffer is restored even in case of an abnormal
     exit via `throw' or error (Note: Nonlocal Exits).

     If the buffer that used to be current has been killed by the time
     of exit from `save-current-buffer', then it is not made current
     again, of course.  Instead, whichever buffer was current just
     before exit remains current.

 - Macro: with-current-buffer buffer body...
     The `with-current-buffer' macro saves the identity of the current
     buffer, makes BUFFER current, evaluates the BODY forms, and
     finally restores the buffer.  The return value is the value of the
     last form in BODY.  The current buffer is restored even in case of
     an abnormal exit via `throw' or error (Note: Nonlocal Exits).

 - Macro: with-temp-buffer body...
     The `with-temp-buffer' macro evaluates the BODY forms with a
     temporary buffer as the current buffer.  It saves the identity of
     the current buffer, creates a temporary buffer and makes it
     current, evaluates the BODY forms, and finally restores the
     previous current buffer while killing the temporary buffer.

     The return value is the value of the last form in BODY.  You can
     return the contents of the temporary buffer by using
     `(buffer-string)' as the last form.

     The current buffer is restored even in case of an abnormal exit via
     `throw' or error (Note: Nonlocal Exits).

   See also `with-temp-file' in Note: Writing to Files.