Re: pcase docs

[Michael Heerdegen]

Eli Zaretskii <address@hidden> writes:

> So maybe we should drop everything and make sure those doc strings are
> corrected?

I think we have already made some good progress since then.  But where
things are unclear, things should be improved further.

> > In the sense of pcase-defmacro, FUN, EXPR or the PATTERNs play the role
> > of arguments of the pattern.
>
> I don't think I see any of this in the doc string...

... of pcase-defmacro.  You must read between the lines ;-)

Yes, it's missing.

> I expected to see its use like this:
>
>   (map SOMETHING)


Indeed.

> But instead I see this:
>
>   (pcase type
>     (`list (map-pairs map))
>     (`hash-table (map--into-hash-table map))
>     (_ (error "Not a map type name: %S" type))))

> IOW, there's no 'map', which was defined with pcase-defmacro, but
> there are 'list' and 'hash-table', which weren't.  And btw, why "`list"
> instead of "`(list"?

That's something completely unrelated to the pcase `map' pattern, just a
random usage of pcase.  It's equivalent to

(cl-case type
  ((list) (map-pairs map))
  ((hash-table) (map--into-hash-table map))
  (t (error "Not a map type name: %S" type)))

i.e., this just tests whether TYPE is bound to one of two constants.

A usage of the function `map-into' would look like:

  (map-into '((1 . a) (2 . b)) 'hash-table)

  ==> an equivalent hash table to this alist


A usage of the pcase map pattern would look like this:

(pcase '((1 . a) (2 . b) (3 . c))
  ((map (2 x)) x))

  ==> b

Semantic and doc of the `map' pcase pattern are still a bit strange (or
wrong), I must say.  I had hoped Nicolas would have time to improve the
doc a bit.


Michael.