Go to the previous, next section.

The  let Expression in  insert-buffer

After ensuring that the variable  buffer refers to a buffer itself and not just to the name of a buffer, the  insert-buffer function continues with a  let expression. This specifies three local variables,  start ,  end , and  newmark and binds them to the initial value  nil . These variables are used inside the remainder of the  let and temporarily hide any other occurrence of variables of the same name in Emacs until the end of the  let .

The body of the  let contains two  save-excursion expressions. First, we will look at the inner  save-excursion expression in detail. The expression looks like this:

(save-excursion
  (set-buffer buffer)
  (setq start (point-min) end (point-max)))

The expression  (set-buffer buffer) changes Emacs's attention from the current buffer to the one from which the text will copied. In that buffer, the variables  start and  end are set to the beginning and end of the buffer, using the commands  point-min and  point-max . Note that we have here an illustration of how  setq is able to set two variables in the same expression.  setq 's first argument is set to the value of its second and its third argument is set to the value of its fourth.

After the body of the inner  save-excursion is evaluated, the  save-excursion restores the original buffer, but  start and  end remain set to the values of the beginning and end of the buffer from which the text will be copied.

The outer  save-excursion expression looks like this:

(save-excursion
  (inner- save-excursion -expression
     (go-to-new-buffer-and-set- start -and- end )
  (insert-buffer-substring buffer start end)
  (setq newmark (point)))

The  insert-buffer-substring function copies the text into the current buffer from the region indicated by  start and  end in  buffer . Since the whole of the second buffer lies between  start and  end , the whole of the second buffer is copied into the buffer you are editing. Next, the value of point, which will be at the end of the inserted text, is recorded in the variable  newmark .

After the body of the outer  save-excursion is evaluated, point and mark are relocated to their original places.

However, it is convenient to locate a mark at the end of the newly inserted text and locate point at its beginning. The  newmark variable records the end of the inserted text. In the last line of the  let expression, the  (push-mark newmark) expression function sets a mark to this location. (The previous location of the mark is still accessible; it is recorded on the mark ring and you can go back to it with C-u C-SPC.) Meanwhile, point is located at the beginning of the inserted text, which is where it was before you called the insert function.

The whole  let expression looks like this:

(let (start end newmark)
  (save-excursion
    (save-excursion
      (set-buffer buffer)
      (setq start (point-min) end (point-max)))
    (insert-buffer-substring buffer start end)
    (setq newmark (point)))
  (push-mark newmark))

Like the  append-to-buffer function, the  insert-buffer function uses  let ,  save-excursion , and  set-buffer . In addition, the function illustrates one way to use  or . All these functions are building blocks that we will find and use again and again.

Go to the previous, next section.