37.2 The Current Buffer

There are, in general, many buffers in a SXEmacs 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 (see Text).

If you span your SXEmacs session on multiple displays it may happen that you appear to have more than one current buffer, but it remains one current buffer per display. Spanning SXEmacs in this sense also spans a scope where some (probably many) buffers are non-current and one among them is current in this scope.

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 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. (See Command Loop.) Therefore, 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 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 SXEmacs 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-excursion that will restore the current buffer when your function is done (see Excursions). 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-excursion
      (set-buffer (get-buffer-create buffer))
      (insert-buffer-substring oldbuf start end))))

This function binds a local variable to the current buffer, and then save-excursion records the values of point, the mark, and the original buffer. Next, set-buffer makes another buffer current. Finally, 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 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-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 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:

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

Using save-excursion, as shown below, handles quitting, errors, and throw, as well as ordinary evaluation.

(let (buffer-read-only)
  (save-excursion
    (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. 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.

buffer-or-name must be a buffer or the name of an existing buffer–else an error is signaled. This function returns the buffer identified by buffer-or-name.