26.10 Recursive Editing Levels

A recursive edit is a situation in which you are using SXEmacs commands to perform arbitrary editing while in the middle of another SXEmacs command. For example, when you type C-r inside a query-replace, you enter a recursive edit in which you can change the current buffer. When you exit from the recursive edit, you go back to the query-replace.

Exiting a recursive edit means returning to the unfinished command, which continues execution. For example, exiting the recursive edit requested by C-r in query-replace causes query replacing to resume. Exiting is done with C-M-c (exit-recursive-edit).

You can also abort a recursive edit. This is like exiting, but also quits the unfinished command immediately. Use the command C-] (abort-recursive-edit) for this. See Quitting.

The mode line shows you when you are in a recursive edit by displaying square brackets around the parentheses that always surround the major and minor mode names. Every window’s mode line shows the square brackets, since SXEmacs as a whole, rather than any particular buffer, is in a recursive edit.

It is possible to be in recursive edits within recursive edits. For example, after typing C-r in a query-replace, you might type a command that entered the debugger. In such a case, two or more sets of square brackets appear in the mode line(s). Exiting the inner recursive edit (here with the debugger c command) resumes the query-replace command where it called the debugger. After the end of the query-replace command, you would be able to exit the first recursive edit. Aborting exits only one level of recursive edit; it returns to the command level of the previous recursive edit. You can then abort that one as well.

The command M-x top-level aborts all levels of recursive edits, returning immediately to the top level command reader.

The text you edit inside the recursive edit need not be the same text that you were editing at top level. If the command that invokes the recursive edit selects a different buffer first, that is the buffer you will edit recursively. You can switch buffers within the recursive edit in the normal manner (as long as the buffer-switching keys have not been rebound). While you could theoretically do the rest of your editing inside the recursive edit, including visiting files, this could have surprising effects (such as stack overflow) from time to time. It is best if you always exit or abort a recursive edit when you no longer need it.

In general, SXEmacs tries to avoid using recursive edits. It is usually preferable to allow users to switch among the possible editing modes in any order they like. With recursive edits, the only way to get to another state is to go “back” to the state that the recursive edit was invoked from.