Elisp: Buffer Functions

By Xah Lee. Date: . Last updated: .

What is a Buffer

A buffer in emacs is an area that displays text, for reading or modification. e.g. content of file, messages, program output, dir listing, chat mode, shell, prompt, etc.

For emacs lisp programers, a buffer is a special emacs lisp data structure that holds text, and allows you to search or edit it in a efficient way, programatically. You can think of it as a enhanced string data structure for storing large text for modification.

Importance of Buffer in Emacs

Buffer is critically important in emacs.

In most programing languages, you read a file to a string. In emacs, it's done by creating a buffer, and put file content in it. Everything you do with file, is done via buffer.

Basic Buffer Concepts

Create Buffer

with-temp-buffer
(with-temp-buffer &rest BODY)

Create a temporary buffer, and evaluate BODY, return the last expression. (then delete the temp buffer)

💡 TIP: when you have a big text and you want to do a lot modification on it, best is to create a temp buffer and edit. Use buffer-substring to turn back into a string. Also useful is insert-file-contents .

;; use a temp buffer to manipulate string

(setq xx "big text")

(with-temp-buffer
  (insert xx)

  ;; manipulate the string here

  ;; return buffer content as string
  (buffer-string))
generate-new-buffer
(generate-new-buffer NAME)
  • Create a new buffer, with a name based on NAME. Buffer name is created by generate-new-buffer-name (it basically return a new buffer name with number appended if the name already exists).
  • If buffer name start with a space, undo is disabled, and the buffer is not listed.
  • Return the buffer (does not make it current).
;; create a new buffer, save it to a var, so later you can switch to it or kill it
(setq newBuf (generate-new-buffer " xyz"))
get-buffer-create
(get-buffer-create BUFFER-OR-NAME)
  • Create or just return a existing buffer. If the buffer exists, it's returned, Else, new is created.
  • Does not make it current.
  • BUFFER-OR-NAME can be a string or buffer.
  • If BUFFER-OR-NAME is a string and start with a space, undo is disabled.
;; create new buffer, without undo info. make sure the string passed is unique and has space in front
(setq newBuf (get-buffer-create " xyz"))

Get (Visiting) Buffer's File Path

buffer-file-name
(buffer-file-name &optional BUFFER)

Return the full path of the file, or nil if not a file.

buffer-file-name

A Buffer Local Variable. Value is the buffer's file path. If the buffer is not associated with a file, value is nil.

💡 TIP: use this variable if you want the file path of current buffer. If you have another buffer in mind, use the function buffer-file-name .

Get Buffer Name, or Buffer Object

Each buffer is identified by the buffer object itself, or by a name (string).

current-buffer
(current-buffer)

return the current buffer object.

buffer-name
(buffer-name &optional BUFFER)

Return the name of buffer. The name of current buffer by default.

get-buffer

(get-buffer BUFFER-OR-NAME)

Return the buffer object.

Make Buffer Current

set-buffer
(set-buffer BUFFER-OR-NAME)

Make a buffer current. (but does not make it visible.) Return that buffer object.

with-current-buffer
(with-current-buffer BUFFER-OR-NAME &rest BODY)

Temporarily make a buffer current.

💡 TIP: Most of the time, you want to use this. Because it takes care of switching back to the original buffer when the function is done.

;; make xbuf current temporarily
(with-current-buffer xbuf
  ;; code to edit text here
)
save-current-buffer
(save-current-buffer &rest BODY)

Execute BODY, then restore the current buffer that is before this function call.

💡 TIP: this function is used when you want to switch buffer in your code and restore the user's current buffer. Do not manually record current buffer and switch back to it at end of code. Because that wont restore when there are error conditions.

Switch to Buffer

switch-to-buffer
(switch-to-buffer BUFFER-OR-NAME &optional NORECORD FORCE-SAME-WINDOW)

Make a buffer visible to user, and make it the current buffer. The buffer fills the current emacs frame.

💡 TIP: use this when you want the user to see the buffer, as if the user switched to it.

Show Buffer

There are few important concepts when showing a buffer.

pop-to-buffer
(pop-to-buffer BUFFER-OR-NAME &optional ACTION NORECORD)

Make a buffer visible to user, and make it the current buffer. (typically, this is shown in a new split pane.)

display-buffer
(display-buffer BUFFER-OR-NAME &optional ACTION FRAME)

Make a buffer visible to user, but does not make it current. (typically, this is shown in a new split pane.)

Save Buffer to File

use save-buffer, but better is write-region

Kill (Delete) Buffer

kill-buffer
(kill-buffer &optional BUFFER-OR-NAME)

Delete a buffer. Default to the current buffer.

🛑 WARNING: if the buffer is not a saved file buffer, all text in the buffer are gone. If you want to keep the text, use buffer-substring to extract the string first, or write-region to save to a file. 〔see Elisp: Write File〕

List of Other Buffer Functions

These are not documented above.

Reference

Emacs Lisp, File, Buffer

Emacs Lisp, Print, Output