Weird &key arglists in ibuf-macs.el

Weird &key arglists in ibuf-macs.el

[Juanma Barranquero]

ibuf-macs.el contains a few macros with CL-style arglists of the form

  (defmacro* macro1 (arg1 arg2 (&key arg3 arg4)...)

instead of

  (defmacro* macro1 (arg1 arg2 &key arg3 arg4...)

I'm not sure that's a legal CL lambda list, but in any case
help-make-usage and company don't grok them:

ELISP> (documentation (defmacro* test1 (arg1 &key arg2) "No doc"))
"No doc\n\n(fn ARG1 &key ARG2)"
ELISP> (documentation (defmacro* test1 (arg1 (&key arg2)) "No doc"))
"No doc\n\n(fn ARG1 (&KEY arg2))"



                                                                Juanma

Re: Weird &key arglists in ibuf-macs.el

[Lawrence Mitchell]

Juanma Barranquero wrote:

> ibuf-macs.el contains a few macros with CL-style arglists of the form

>   (defmacro* macro1 (arg1 arg2 (&key arg3 arg4)...)

> instead of

>   (defmacro* macro1 (arg1 arg2 &key arg3 arg4...)

> I'm not sure that's a legal CL lambda list

It is legal, see section 3.4.4.1 of the hyperspec <URL:
http://www.lispworks.com/reference/HyperSpec/Body/03_dda.htm>.

|  Anywhere in a macro lambda list where a parameter name can
|  appear, and where ordinary lambda list syntax (as described in
|  Section 3.4.1 (Ordinary Lambda Lists)) does not otherwise allow
|  a list, a destructuring lambda list can appear in place of the
|  parameter name. When this is done, then the argument that would
|  match the parameter is treated as a (possibly dotted) list, to
|  be used as an argument list for satisfying the parameters in the
|  embedded lambda list. This is known as destructuring.

It's often used for with-FOO type macros, e.g.

(defmacro* with-foo ((&key x y z &rest stuff) &body more-stuff)
  ...)

allowing

(with-foo (:x x :y y :z z (more-stuff))
  (doing-more-stuff))

> help-make-usage and company don't grok them:

> ELISP> (documentation (defmacro* test1 (arg1 &key arg2) "No doc"))
> "No doc\n\n(fn ARG1 &key ARG2)"
> ELISP> (documentation (defmacro* test1 (arg1 (&key arg2)) "No doc"))
> "No doc\n\n(fn ARG1 (&KEY arg2))"

The thing to do here is to explicitly write the arglist in the
end of the docstring.

(documentation (defmacro* test1 (arg1 (&key arg2))
                  "No doc\n\n(fn ARG1 (&key ARG2))"))
   => No doc\n\n(fn ARG1 (&key ARG2))

-- 
Lawrence Mitchell <wence@gmx.li>

Re: Weird &key arglists in ibuf-macs.el

[Juanma Barranquero]

On Mon, 10 May 2004 16:11:08 +0100, Lawrence Mitchell <wence@gmx.li> wrote:

> It is legal, see section 3.4.4.1 of the hyperspec <URL:
> http://www.lispworks.com/reference/HyperSpec/Body/03_dda.htm>.

Ah, very interesting, thanks.

> The thing to do here is to explicitly write the arglist in the
> end of the docstring.

Yes, I've seen (and sometimes, added) a few of these, mostly in cases
where

  (function ARG1 &optional ARG2)

is better explained as

  (function ARG1 ARG2 [OTHERARGS]...)

                                                           /L/e/k/t/u

Re: Weird &key arglists in ibuf-macs.el

[Juanma Barranquero]

On Mon, 10 May 2004 19:11:49 +0200, Juanma Barranquero <lektu@mi.madritel.es> wrote:

>   (function ARG1 &optional ARG2)

Obviously I meant

   (function ARG1 &rest ARG2)

Grrr...

Anyway, although what you propose works:

> The thing to do here is to explicitly write the arglist in the
> end of the docstring.

...I think "the thing to do" would be to fix help-make-usage. That's the
whole point in having a help function to build arglist info for
emacs-lisp/cl*.el modules, or else it would've sufficed
to add \(fn ...) to every cl-related function.

I'll put it in my TODO list, low-priority... :)

                                                           /L/e/k/t/u