Re: Docs for &optional and &rest arguments together

[Adam Porter <adam@alphapapa.net>]

This doesn't exactly answer your question, but here's an alternative you
might be interested in: I wrote a similar macro a while back, and I
tried to follow CL-style arguments by using a list of options.

https://github.com/alphapapa/elexandria/blob/83a1b08d0711fdce07a5b33525535cc3a457c6ee/elexandria.el#L105

Here's the source code:

(cl-defmacro with-file-buffer (path options &body body)
  "Insert contents of file at PATH into a temp buffer, and evaluate and return the value of BODY in it.
OPTIONS is a plist accepting the following options:

`:must-exist': If non-nil, raise an error if no file exists at
PATH.

`:write': If non-nil, write the contents of the buffer to file at
PATH after evaluating BODY.

`:overwrite': If nil (or unset), raise an error instead of
overwriting an existing file at PATH.  If `ask', ask for
confirmation before overwriting an existing file.  If t,
overwrite a file at PATH unconditionally.

`:append': Passed to function `write-region', which see.

`:visit':  Passed to function `write-region', which see."
  (declare (indent 2))
  `(with-temp-buffer
     (if (file-readable-p ,path)
         (insert-file-contents ,path)
       (when ,(plist-get options :must-exist)
         (error "File not readable: %s" ,path)))
     (prog1
         (progn
           ,@body)
       ,(when (plist-get options :write)
          `(write-region nil nil path
                         ,(plist-get options :append)
                         ,(plist-get options :visit)
                         ,(pcase-exhaustive (plist-get options :overwrite)
                            ('nil ''excl)
                            ((or 'ask ''ask) ''ask)
                            ('t nil)))))))