Re: pcase docs

[Eli Zaretskii <eliz@gnu.org>]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: jwiegley@gmail.com,  emacs-devel@gnu.org
> Date: Sat, 23 Jan 2016 15:22:08 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > > Surely not!  I just had the time to read the code, carefully (I had to,
> > > to be able to write my el-search.el thing).  Most others don't care
> > > because they just don't care, I think.
> >
> > But this stuff is widely used, by several different individuals.  How
> > do they know what to put in the code, if they, like me, are confused
> > about the purpose and the usage?
> 
> Dunno.  If it helps: I had spent really a lot of time into understanding
> pcase.  More time than you can probably invest, doing all the work you
> do.  And I made lots of errors over weeks after had finally internalized
> everything.

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

> > > Actually `pcase-defmacro' is easy to understand if you understood
> > > `defmacro': You define a pattern by its name and by the arguments it
> > > will accept.
> >
> > But 'pcase' patterns don't accept any arguments, they are matched
> > against a value of an expression.  So how to understand "arguments" in
> > this context?
> 
> pcase-defmacro can only define patterns that are used like function
> calls, (pattern-name pattern-args), like
> 
>  
>   (pred fun)
>   (guard expr)
>   (or pattern...)
> 
> 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...

> > And how to explain that a pattern that starts with "`(list" will
> > somehow end up using the pattern defined with "(pcase-defmacro map"?
> 
> No, `map' doesn't define `, it defines a pattern named `map' (that
> currently is rarely used, or nowhere).

That's the problem: that the pattern 'map' is not used.  Instead, I
see its sub-classes being used as pcase patterns.

> (pcase-defmacro greater-than (number)
>   `(and (pred numberp)
>         (pred (lambda (x) (< ,number x)))))
> 
> Then any occurrence of (greater-than N) in any pcase pattern is simply
> substituted with
> 
>   (and (pred numberp)
>        (pred (lambda (x) (< N x))))
> 
> That's it.

That's what I expected to see when I saw this:

  (pcase-defmacro map (&rest args)

I expected to see its use like this:

  (map SOMETHING)

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"?