Info Catalog eintr: More Complex eintr: insert-buffer

eintr: copy-to-buffer

 
 5.1 The Definition of ‘copy-to-buffer’
 ======================================
 
 After understanding how ‘append-to-buffer’ works, it is easy to
 understand ‘copy-to-buffer’.  This function copies text into a buffer,
 but instead of adding to the second buffer, it replaces all the previous
 text in the second buffer.
 
    The body of ‘copy-to-buffer’ looks like this,
 
      ...
      (interactive "BCopy to buffer: \nr")
      (let ((oldbuf (current-buffer)))
        (with-current-buffer (get-buffer-create buffer)
          (barf-if-buffer-read-only)
          (erase-buffer)
          (save-excursion
            (insert-buffer-substring oldbuf start end)))))
 
    The ‘copy-to-buffer’ function has a simpler ‘interactive’ expression
 than ‘append-to-buffer’.
 
    The definition then says
 
      (with-current-buffer (get-buffer-create buffer) ...
 
    First, look at the earliest inner expression; that is evaluated
 first.  That expression starts with ‘get-buffer-create buffer’.  The
 function tells the computer to use the buffer with the name specified as
 the one to which you are copying, or if such a buffer does not exist, to
 create it.  Then, the ‘with-current-buffer’ function evaluates its body
 with that buffer temporarily current.
 
    (This demonstrates another way to shift the computer’s attention but
 not the user’s.  The ‘append-to-buffer’ function showed how to do the
 same with ‘save-excursion’ and ‘set-buffer’.  ‘with-current-buffer’ is a
 newer, and arguably easier, mechanism.)
 
    The ‘barf-if-buffer-read-only’ function sends you an error message
 saying the buffer is read-only if you cannot modify it.
 
    The next line has the ‘erase-buffer’ function as its sole contents.
 That function erases the buffer.
 
    Finally, the last two lines contain the ‘save-excursion’ expression
 with ‘insert-buffer-substring’ as its body.  The
 ‘insert-buffer-substring’ expression copies the text from the buffer you
 are in (and you have not seen the computer shift its attention, so you
 don’t know that that buffer is now called ‘oldbuf’).
 
    Incidentally, this is what is meant by “replacement”.  To replace
 text, Emacs erases the previous text and then inserts new text.
 
    In outline, the body of ‘copy-to-buffer’ looks like this:
 
      (let (BIND-oldbuf-TO-VALUE-OF-current-buffer)
          (WITH-THE-BUFFER-YOU-ARE-COPYING-TO
            (BUT-DO-NOT-ERASE-OR-COPY-TO-A-READ-ONLY-BUFFER)
            (erase-buffer)
            (save-excursion
              INSERT-SUBSTRING-FROM-oldbuf-INTO-BUFFER)))
 

Info Catalog eintr: More Complex eintr: insert-buffer