Emacs Lisp: Buffer Functions

Here's the most useful functions for buffer.

Get Buffer Name

buffer-name

(buffer-name &optional BUFFER)

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

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 .

current-buffer

(current-buffer)

return the current buffer object.

Switch Buffer

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 myBuf current temporarily
(with-current-buffer myBuf
  ;; code to edit text here
)

set-buffer

(set-buffer BUFFER-OR-NAME)

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

💡 TIP: for temp switching buffer in elisp, better to use with-current-buffer. To switch buffer for user, use switch-to-buffer or pop-to-buffer.

(save-current-buffer

  ;; switch to myBuf
  (set-buffer myBuf)

  ;; do stuff, such as insert/delete text
  )

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.

Create Buffer

with-temp-buffer

(with-temp-buffer &rest BODY)

Create a temporary buffer, and evaluate BODY, return the last expression.

💡 TIP: when you have a string and you want to do more than few text manipulation to it, best is to create a temp buffer with this function and call lots text processing functions on it, instead of calling many string manipulation functions with string. because in emacs, there are a lot powerful functions on buffer text, but modifying string is expensive. Use buffer-substring to turn back into a string.

Also, for creating a temp buffer, this is the best function. Because it saves code of create, switch, close, and restore the buffer.

Also useful together 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 buffer with a name based on NAME. Buffer name is created by calling generate-new-buffer-name.
• 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)

• Returns the buffer (does not make it current).
• BUFFER-OR-NAME can be a string or buffer.
• If the buffer exists, it's just returned. If not exist, new is created.
• 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"))

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 Emacs Lisp: Write File]

Reference

• Buffers (ELISP Manual)