How to make interactive functions (simply) undoable?

Question

This question refers exclusively to interactive functions that modify the contents of the current buffer.

What does one need to do to ensure that a single execution of (undo), right after running the function, will fully undo all the changes it made to the buffer's contents?

(For the rest of this post I'll use the word undoable to mean "can be undone with a single execution of (undo)".)

---

Apparently, interactive functions are not undoable by default, as the example below shows.

(NB: I stress that the function below is just an example of the problem; I'm looking for a general solution, not one that just works for this particular function/use-case. Also, please do not use this function! In addition to not being undoable, it has other shortcomings.)

The function quote-region inserts single quotes at the beginning and end of the current region, and replaces all occurrences of single quotes in-between with a backslash-escaped single quote:

(defun quote-region ()
  (interactive)

  (let ((beginning (region-beginning))
        (end       (region-end)))

    (goto-char end)
    (insert "'")

    (replace-string "'" "\\'" nil beginning end)

    (goto-char beginning)
    (insert "'")

))

For example, if the current region's content is

foo'bar

...then running M-x quote-region will change it to

'foo\'bar'

...as desired.

But if I now hit C-/ (undo), the buffer changes to

foo'bar'

I must then hit C-/ a second time to return to

foo'bar

Hence quote-region is not undoable, as defined above.

Answer 1

I recommend you do C-h f replace-string RET and read it:

[...]
This function is for interactive use only;
in Lisp code use `search-forward' and `replace-match' instead.
[...]

So, as suggested replace that call with something like

(while (search-backward "'" beginning t)
  (replace-match "\\'" t t)
  (goto-char (match-beginning 0)))

Some functions do "unusual" additional things which are helpful in interactive use but get in the way when you need their main functionality within your own function. Among those "unusual" operations, some interactive functions (such as replace-string) insert an undo-boundary, others set the mark (e.g. beginning-of-buffer), etc... We try to help the user discover those quirks by documenting them in the C-h f output, and we also try to make the byte-compiler emit a warning when it sees you call such a function, but you need to C-h f or to byte-compile your file in order to discover the problem.