Capturing User Input: Interactive Codes

1. Prompting for Simple Input: Strings, Numbers, and Files

The most straightforward way to provide arguments to an interactive function is to prompt the user in the minibuffer. You accomplish this by passing a specially formatted string to interactive.

The general format is:
"(<code><prompt>\n<code><prompt>...)"

• <code>: A single character that specifies the type of input to read.
• <prompt>: The text displayed to the user in the minibuffer.
• \n: A newline character to separate prompts for multiple arguments.

Let's explore the most common codes.

Your Turn: Fixing greet-person

As you just read, the M code is used to prompt for a string. Let's apply this to the greet-person function that failed in our last lesson.

1. Open your *scratch* buffer.

2. Write or paste the following code:

   (defun greet-person (name)
     "Display a personalized greeting for NAME."
     (interactive "MEnter your name: ")
     (message "Hello, %s!" name))
   

3. Evaluate the function with C-x C-e.

4. Now, run it with M-x greet-person.

This time, Emacs prompts you in the minibuffer for a name. The string you type is automatically passed as the name argument to the function.

Common Interactive Codes

Besides M for a string, here are a few other essential codes:

• n: Prompts for a number.
• f: Prompts for an existing file path, with completion.
• b: Prompts for an existing buffer name, with completion.
• r: A special code that doesn't prompt but provides the region's start and end points. We'll explore this next.

The image below shows a function that uses the f code to ask for a filename. Notice the structure is identical to our greet-person example.

2. Working with the Active Region

As a writer and editor, many of your custom commands will likely operate on a piece of selected text—what Emacs calls the region. The r interactive code is designed for exactly this.

When you use (interactive "r"), Emacs does not prompt you. Instead, it automatically passes two arguments to your function: the numeric positions of the point (where the cursor is) and the mark (the other end of the selection). By convention, the function should accept these as start and end.

Let's build a command to convert the selected text to uppercase.

Step 1: The Basic Function

(defun upcase-region (start end)
  "Convert the text in the region to uppercase."
  (interactive "r")
  (let ((text (buffer-substring-no-properties start end)))
    (delete-region start end)
    (insert (upcase text))))

Let's break this down:

• (defun upcase-region (start end) ...): The function is defined to accept two arguments.
• (interactive "r"): This tells Emacs to pass the region's boundaries to start and end.
• (let ((text (buffer-substring-no-properties start end))) ...): We create a local variable text and store the string from the region in it.
• (delete-region start end): We remove the original text.
• (insert (upcase text)): We insert the new, uppercased version of the text.

Try it out:

1. Evaluate the function in your *scratch* buffer.
2. In any buffer, select a piece of text.
3. Run M-x upcase-region.

The selected text should be replaced by its uppercase version.

Step 2: A User-Experience Improvement with save-excursion

You might notice that after the command runs, your cursor (the point) is left at the end of the newly inserted text. This can be disruptive. A common practice in Emacs Lisp is to wrap buffer-modifying code in save-excursion, which saves the state of the point, mark, and current buffer, executes your code, and then restores everything. This makes your command feel much smoother.

Watch this short clip to see save-excursion in action.

Let's apply this to our function:

(defun upcase-region (start end)
  "Convert the text in the region to uppercase."
  (interactive "r")
  (save-excursion
    (let ((text (buffer-substring-no-properties start end)))
      (delete-region start end)
      (goto-char start) ; Go back to the start before inserting
      (insert (upcase text)))))

Notice we now wrap the core logic in save-excursion. We also explicitly move to the start of the original region before inserting. When you run this version, the text will be uppercased, but your cursor will remain exactly where it was.

3. A Practical Tool: The "Surround Region" Command

Now, let's combine these concepts to build a genuinely useful command for your creative writing workflow. A common task is to surround a piece of text with delimiters—for example, wrapping a word in asterisks for italics in Markdown, or surrounding a phrase with quotation marks.

We will create a command surround-region that:

1. Acts on the selected region (r).
2. Prompts you for the opening delimiter (M).
3. Prompts you for the closing delimiter (M).

Your Turn: Build the surround-region Command

Here is the complete code. Read through it, then copy it to your *scratch* buffer and evaluate it.

(defun surround-region (start end opening-str closing-str)
  "Surround the active region with user-provided strings."
  (interactive "r\nMOpening string: \nMClosing string: ")
  (save-excursion
    ;; Go to the end first so the 'start' position remains valid
    (goto-char end)
    (insert closing-str)
    ;; Now go to the start and insert
    (goto-char start)
    (insert opening-str)))

Let's analyze the interactive string: "r\nMOpening string: \nMClosing string: ".

• r: Provides the start and end arguments.
• \n: Separates the specifiers.
• MOpening string: : Prompts for and provides the opening-str argument.
• \n: Separates the specifiers.
• MClosing string: : Prompts for and provides the closing-str argument.

Test your new tool:

1. Select a word in a buffer.
2. Run M-x surround-region.
3. At the "Opening string:" prompt, type * and press Enter.
4. At the "Closing string:" prompt, type * and press Enter.
   The word will now be surrounded by asterisks. Try it again with " for both, or ( and ). You've built a flexible text manipulation utility.

For a deeper dive into this "surround" concept and to see how it can be made even more powerful, this article is an excellent resource.

The article goes on to show more advanced techniques, like providing a menu of pre-defined choices, which you might find useful as you get more comfortable with Elisp.

Conclusion

You have now unlocked one of the most powerful features of Emacs Lisp for customization. By providing a formatted string to interactive, you can build sophisticated commands that take input directly from the user or the buffer's context.

Key Takeaways:

• The interactive specifier can take a string argument to define how a command gets its parameters.
• Interactive codes like M (string), n (number), and f (file) prompt the user for input in the minibuffer.
• The r code is special: it automatically passes the start and end points of the active region as two integer arguments.
• You can combine codes using \n to supply multiple arguments to a single command.
• Using save-excursion is a best practice to ensure your commands don't have disruptive side effects, like moving the cursor unexpectedly.

Preview of the Next Lesson

Running your commands via M-x is fine, but for tools you use frequently, you'll want faster access. In the next lesson, we will focus on the final step in making a command truly part of your workflow: binding it to a key sequence. You'll learn how to use global-set-key to make your custom commands available at the press of a few keys.