Programmatic Buffer Management

1. What is a Buffer?

In your daily use of Emacs, you interact with buffers constantly—the *scratch* buffer, buffers visiting files, the *Messages* buffer, and buffers created by packages like Magit. From a programming standpoint, a buffer is a fundamental Lisp object that holds text and its associated properties (like syntax highlighting). It can be linked to a file, but it doesn't have to be.

This video from System Crafters provides an excellent overview of what buffers are in the context of Elisp and why they are so central to extending Emacs.

2. Finding and Retrieving Buffers

Before we can switch to a buffer, we first need a way to get a reference to it. Elisp provides several functions for this, each suited for a different situation. You can think of this as querying the Emacs environment for the specific buffer object you want to work with.

The following text from System Crafters (the companion article to the video) clearly lays out the most important functions for retrieving buffers. We'll walk through them one by one.

A. Getting a List of All Buffers

The most comprehensive way to see what's happening is to get a list of all active buffers. The buffer-list function returns a list of all buffer objects.

To make this list human-readable, we can use mapcar (which you'll remember from our lesson on lists) to apply the buffer-name function to each buffer object.

Try this in your *scratch* buffer:

(mapcar #'buffer-name (buffer-list))

After you evaluate this with C-x C-e, the minibuffer will show you a list of the names of every buffer currently open in your Emacs session.

B. Getting Specific Buffers

More often, you'll want to target a specific buffer. Here are the primary functions for doing so, as covered in the System Crafters article:

• current-buffer: Returns the buffer object that the Lisp code is currently executing in. This is not necessarily the buffer visible in the active window.

  (current-buffer)  ; => #<buffer *scratch*>
  

• get-buffer "buffer-name": Returns the buffer object corresponding to a given name. It returns nil if no such buffer exists.

  (get-buffer "*scratch*")       ; => #<buffer *scratch*>
  (get-buffer "non-existent")    ; => nil
  

• get-buffer-create "buffer-name": Like get-buffer, but if the buffer doesn't exist, it creates a new, empty one with that name. This is useful for creating temporary or utility buffers.

  (get-buffer-create "my-notes-buffer")
  

• get-file-buffer "path/to/file.txt": Returns the buffer object that is visiting a specific file. Returns nil if no buffer is visiting that file.
• find-file-noselect "path/to/file.txt": This is a powerful one. It opens a file into a buffer but does not display it in any window. It returns the buffer object. This is essential for programmatically reading or modifying a file in the background.

The following video segment demonstrates these functions in action.

The (or ...) pattern shown at the end is a cornerstone of robust Elisp. Since or stops and returns the first non-nil value, this expression elegantly says: "Try to get the buffer if it's already visiting the file; if that fails, then load the file into a new buffer."

3. Switching the Context: switch-to-buffer vs. set-buffer

Now that we can retrieve buffer objects, we can switch to them. There are two fundamentally different ways to "switch," and the distinction is crucial for writing correct Elisp.

1. switch-to-buffer: This is for human interaction. It changes which buffer is displayed in the currently selected window. It's the function that runs when you type C-x b.
2. set-buffer: This is for programmatic control. It changes Elisp's "current buffer" context without affecting what the user sees on screen. After (set-buffer ...), subsequent functions like insert or point will operate on that new buffer.

The classic Programming in Emacs Lisp manual explains this key difference very clearly.

Safe Programmatic Switching with with-current-buffer

Directly using set-buffer can be dangerous. If you change the buffer context in your function, it might not get set back, causing other code that runs after yours to operate on the wrong buffer.

The correct, idiomatic way to operate on another buffer is with the with-current-buffer macro. It temporarily switches to the specified buffer, runs your code, and—no matter what happens, even if there's an error—it guarantees the original buffer context is restored afterwards.

(with-current-buffer "buffer-name"
  ;; ... code inside here operates on "buffer-name" ...
  (insert "This text goes into the other buffer."))

;; ... code here continues in the original buffer ...

The System Crafters video explains this safety mechanism well.

4. Practical Application: A Smart Buffer Switcher

Let's see how these pieces come together to build a genuinely useful tool. The following video by Mike Zamansky shows the creation of a function to intelligently switch between Eshell buffers. This is a perfect real-world example of programmatic buffer retrieval and switching.

As a complement to switch-to-buffer, there is also switch-to-buffer-other-window, which is useful when you are working with a split-window layout.

Your Turn: A Custom Writing Buffer Switcher

Given your background in creative writing and your use of Emacs for it, let's build a tool for your workflow. Your task is to create an interactive command named ar-switch-to-writing-buffer.

This command should:

1. Get a list of all current buffers.
2. Filter this list to find only your "writing" buffers. For this exercise, let's define a writing buffer as any buffer whose name ends in .org. You can use string-suffix-p for this check, e.g., (string-suffix-p ".org" (buffer-name buffer-object)).
3. Use cond to implement the following logic:
   • If there are no writing buffers open, print a message like "No writing buffers found." using the message function.
   • If there is exactly one writing buffer, switch to it directly using switch-to-buffer.
   • If there are multiple writing buffers, use completing-read (as seen in the Zamansky video) to prompt the user to select one by name, and then switch to the selected buffer.

Hint: You will need to combine buffer-list, cl-remove-if-not, lambda, mapcar, completing-read, and switch-to-buffer. This is an excellent exercise to tie everything together. Take your time and build it piece by piece in your *scratch* buffer.

Conclusion

In this lesson, you've taken a significant step from being an Emacs user to an Emacs programmer. You now understand how to treat buffers as programmable objects within the Lisp environment.

Key Takeaways:

• Buffers as Objects: Buffers are Lisp objects that hold text, which you can retrieve and manipulate with functions like buffer-list and get-buffer.
• Retrieval Strategies: You can get all buffers (buffer-list), get one by name (get-buffer), get or create one (get-buffer-create), or get one tied to a file (get-file-buffer, find-file-noselect).
• Context vs. Display: switch-to-buffer changes the buffer shown in a window, while set-buffer changes the context for your code.
• Safe Switching: The with-current-buffer macro is the standard, safe way to temporarily execute code in a different buffer without causing side effects.

Preview of the Next Lesson

We've learned how to find and switch between buffers. The logical next step is to learn how to move and work within them. In our next lesson, we will dive into two of the most fundamental concepts for buffer manipulation: the point and the mark. You'll learn how to programmatically move the cursor, get its position, and define regions of text.