Go to the previous, next section.

 save-excursion in  append-to-buffer

The body of the  let expression in  append-to-buffer consists of a  save-excursion expression.

The  save-excursion function saves the locations of point and mark, and restores them to those positions after the expressions in the body of the  save-excursion complete execution. In addition,  save-excursion keeps track of the original buffer, and restores it. This is how  save-excursion is used in  append-to-buffer .

Incidentally, it is worth noting here that a Lisp function is normally formatted so that everything that is enclosed in a multi-line spread is indented more to the right than the first symbol. In this function definition, the  let is indented more than the  defun , and the  save-excursion is indented more than the  let , like this:

(defun @dots{}
  @dots{}
  @dots{}
  (let@dots{}
    (save-excursion
      @dots{}

This formatting convention makes it easy to see that the two lines in the body of the  save-excursion are enclosed by the parentheses associated with  save-excursion , just as the  save-excursion itself is enclosed by the parentheses associated with the  let :

(let ((oldbuf (current-buffer)))
  (save-excursion
    (set-buffer (get-buffer-create buffer))
    (insert-buffer-substring oldbuf start end))))

The use of the  save-excursion function can be viewed as a process of filling in the slots of a template:

(save-excursion
  first-expression-in-body
  second-expression-in-body
   @dots{}
  last-expression-in-body)

In this function, the body of the  save-excursion contains only two expressions. The body looks like this:

(set-buffer (get-buffer-create buffer))
(insert-buffer-substring oldbuf start end)

When the  append-to-buffer function is evaluated, the two expressions in the body of the  save-excursion are evaluated in sequence. The value of the last expression is returned as the value of the  save-excursion function; the other expression is evaluated only for its side effects.

The first line in the body of the  save-excursion uses the  set-buffer function to change the current buffer to the one specified in the first argument to  append-to-buffer . (Changing the buffer is the side effect; as we have said before, in Lisp, a side effect is often the primary thing we want.) The second line does the primary work of the function.

The  set-buffer function changes Emacs' attention to the buffer to which the text will be copied and from which  save-excursion will return. The line looks like this:

(set-buffer (get-buffer-create buffer))

The innermost expression of this list is  (get-buffer-create buffer) . This expression uses the  get-buffer-create function, which either gets the named buffer, or if it does not exist, creates one with the given name. This means you can use  append-to-buffer to put text into a buffer that did not previously exist.

 get-buffer-create also keeps  set-buffer from getting an unnecessary error:  set-buffer needs a buffer to go to; if you were to specify a buffer that does not exist, Emacs would baulk. Since  get-buffer-create will create a buffer if none exists,  set-buffer is always provided with a buffer.

The last line of  append-to-buffer does the work of appending the text:

(insert-buffer-substring oldbuf start end)

The  insert-buffer-substring function copies a string from the buffer specified as its first argument and inserts the string into the present buffer. In this case, the argument to  insert-buffer-substring is the value of the variable created and bound by the  let , namely the value of  oldbuf , which was the current buffer when you gave the  append-to-buffer command.

After  insert-buffer-substring has done its work,  save-excursion will restore the action to the original buffer and  append-to-buffer will have done its job.

Written in skeletal form, the workings of the body look like this:

(let (bind- oldbuf -to-value-of- current-buffer )
  (save-excursion                       ; Keep track of buffer.
    change-buffer
    insert-substring-from- oldbuf -into-buffer)

  change-back-to-original-buffer-when-finished
let-the-local-meaning-of- oldbuf -disappear-when-finished

In summary,  append-to-buffer works as follows: it saves the value of the current buffer in the variable called  oldbuf . It gets the new buffer, creating one if need be, and switches Emacs to it. Using the value of  oldbuf , it inserts the region of text from the old buffer into the new buffer; and then using  save-excursion , it brings you back to your original buffer.

In looking at  append-to-buffer , you have explored a fairly complex function. It shows how to use  let and  save-excursion , and how to change to and come back from another buffer. Many functions definitions use  let ,  save-excursion , and  set-buffer this way.

Go to the previous, next section.