Info Catalog eintr: Insert or eintr: insert-buffer eintr: New insert-buffer

eintr: Insert let

 
 5.2.5 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.  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 is
 relocated to its original place.
 
    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
 position of which was saved by the first ‘save-excursion’.
 
    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.
 

Info Catalog eintr: Insert or eintr: insert-buffer eintr: New insert-buffer