Function: with-output-to-temp-buffer

with-output-to-temp-buffer is a macro defined in subr.el.gz.

Signature

(with-output-to-temp-buffer BUFNAME &rest BODY)

Documentation

Bind standard-output to buffer BUFNAME, eval BODY, then show that buffer.

This construct makes buffer BUFNAME empty before running BODY. It does not make the buffer current for BODY. Instead it binds standard-output to that buffer, so that output generated with prin1 and similar functions in BODY goes into the buffer.

At the end of BODY, this marks buffer BUFNAME unmodified and displays it in a window, but does not select it. The normal way to do this is by calling display-buffer, then running temp-buffer-show-hook. However, if temp-buffer-show-function is non-nil, it calls that function instead (and does not run temp-buffer-show-hook). The function gets one argument, the buffer to display.

The return value of with-output-to-temp-buffer is the value of the last form in BODY. If BODY does not finish normally, the buffer BUFNAME is not displayed.

This runs the hook temp-buffer-setup-hook before BODY, with the buffer BUFNAME temporarily current. It runs the hook temp-buffer-show-hook after displaying buffer BUFNAME, with that buffer temporarily current, and the window that was used to display it temporarily selected. But it doesn't run temp-buffer-show-hook if it uses temp-buffer-show-function.

By default, the setup hook puts the buffer into Help mode before running BODY. If BODY does not change the major mode, the show hook makes the buffer read-only, and scans it for function and variable names to make them into clickable cross-references.

See the related form with-temp-buffer-window.

Probably introduced at or before Emacs version 18.

Source Code

;; Defined in /usr/src/emacs/lisp/subr.el.gz
;; Doc is very similar to with-temp-buffer-window.
(defmacro with-output-to-temp-buffer (bufname &rest body)
  "Bind `standard-output' to buffer BUFNAME, eval BODY, then show that buffer.

This construct makes buffer BUFNAME empty before running BODY.
It does not make the buffer current for BODY.
Instead it binds `standard-output' to that buffer, so that output
generated with `prin1' and similar functions in BODY goes into
the buffer.

At the end of BODY, this marks buffer BUFNAME unmodified and displays
it in a window, but does not select it.  The normal way to do this is
by calling `display-buffer', then running `temp-buffer-show-hook'.
However, if `temp-buffer-show-function' is non-nil, it calls that
function instead (and does not run `temp-buffer-show-hook').  The
function gets one argument, the buffer to display.

The return value of `with-output-to-temp-buffer' is the value of the
last form in BODY.  If BODY does not finish normally, the buffer
BUFNAME is not displayed.

This runs the hook `temp-buffer-setup-hook' before BODY,
with the buffer BUFNAME temporarily current.  It runs the hook
`temp-buffer-show-hook' after displaying buffer BUFNAME, with that
buffer temporarily current, and the window that was used to display it
temporarily selected.  But it doesn't run `temp-buffer-show-hook'
if it uses `temp-buffer-show-function'.

By default, the setup hook puts the buffer into Help mode before running BODY.
If BODY does not change the major mode, the show hook makes the buffer
read-only, and scans it for function and variable names to make them into
clickable cross-references.

See the related form `with-temp-buffer-window'."
  (declare (debug t))
  (let ((old-dir (make-symbol "old-dir"))
        (buf (make-symbol "buf")))
    `(let* ((,old-dir default-directory)
            (,buf
             (with-current-buffer (get-buffer-create ,bufname)
               (prog1 (current-buffer)
                 (kill-all-local-variables)
                 ;; FIXME: delete_all_overlays
                 (setq default-directory ,old-dir)
                 (setq buffer-read-only nil)
                 (setq buffer-file-name nil)
                 (setq buffer-undo-list t)
                 (let ((inhibit-read-only t)
                       (inhibit-modification-hooks t))
                   (erase-buffer)
                   (run-hooks 'temp-buffer-setup-hook)))))
            (standard-output ,buf))
       (prog1 (progn ,@body)
         (internal-temp-output-buffer-show ,buf)))))