GNU Info

(emacs-lisp-intro.info)Insert let

---

Prev: Insert or Up: insert-buffer

---

Enter node , (file) or (file)node

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' 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.  The first argument of `setq' 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.