Emacs Lisp: Buffer Functions
What is a Buffer
A buffer in emacs is an area the displays text, for reading or modification. Content of file is represented in a buffer, so is any prompt, shell, dir listing, chat mode, 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.
Important Buffer Concepts
- Buffer is a datatype in elisp. A buffer is a lisp object. It holds text.
- Buffer Name. Each buffer has a name (a string). Buffer names are unique. Many functions accept a buffer argument that can be a buffer name or buffer object.
- Current Buffer. There is always one buffer designated as the current buffer. Most functions that work on text surch as insert/delete work on the current buffer.
- File Buffer. A buffer may have a associated file path.
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
orwith-temp-buffer
. To switch buffer for user, useswitch-to-buffer
orpop-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.
Warning: 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: most of the time, you should just use
with-temp-buffer
to create new buffers. Because that saves you code of creating buffer, switching to it, do something, possibly close it, and restore (switch back) to the buffer that was current.;; use a temp buffer to manipulate string (setq myStr "big text") (with-temp-buffer (insert myStr) ;; manipulate the string here ;; return buffer content as string (buffer-string))
generate-new-buffer
-
(generate-new-buffer NAME)
Create and return a buffer with a name based on NAME. Buffer name is created by calling
generate-new-buffer-name
.Typically used like this:
;; 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")) ;; if name for new buffer start with space, undo is disabled
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, orwrite-region
to save to a file. [see Emacs Lisp: Write File]
List of All Buffer Functions
Here's a list of all buffer related functions. The most commonly used are explained above.
bufferp
current-buffer
set-buffer
save-current-buffer
with-current-buffer
with-temp-buffer
buffer-name
rename-buffer
get-buffer
generate-new-buffer-name
buffer-file-name
- buffer-file-name
- buffer-file-truename
- buffer-file-number
get-file-buffer
find-buffer-visiting
set-visited-file-name
- list-buffers-directory
buffer-modified-p
set-buffer-modified-p
restore-buffer-modified-p
not-modified
buffer-modified-tick
buffer-chars-modified-tick
with-silent-modifications
verify-visited-file-modtime
clear-visited-file-modtime
visited-file-modtime
set-visited-file-modtime
ask-user-about-supersession-threat
- buffer-read-only
- inhibit-read-only
read-only-mode
barf-if-buffer-read-only
buffer-list
other-buffer
last-buffer
bury-buffer
unbury-buffer
- buffer-list-update-hook
get-buffer-create
generate-new-buffer
kill-buffer
- kill-buffer-query-functions
- kill-buffer-hook
- buffer-offer-save
- buffer-save-without-query
buffer-live-p
make-indirect-buffer
clone-indirect-buffer
buffer-base-buffer
buffer-swap-text
gap-position
gap-size