Re: pcase docs

[Michael Heerdegen]

Eli Zaretskii <address@hidden> writes:

> Sorry, I don't understand: how can knowing what 'defmacro' does help
> to know what 'pcase-defmacro' does?

It works extremely analogous.

>  At the very least, one needs to know which patterns will be possible
> after using 'pcase-defmacro', don't you agree?
>
> Btw, this macro also has "issues".  The doc string is less than
> helpful:
>
>     "Define a new kind of pcase PATTERN, by macro expansion.
>   Patterns of the form (NAME ...) will be expanded according
>   to this macro."
>
> It says nothing about ARGS, and the "by macro expansion" part sounds
> strange -- what useful information does it supply here?

I agree that it's quite vague.

> And if you turn to the users of this macro, in the hope of gaining
> some understanding, you will see, for example, that map.el defines a
> pattern whose NAME is "map":
>
>   (pcase-defmacro map (&rest args)
>     "Build a `pcase' pattern matching map elements.
>
>   The `pcase' pattern will match each element of PATTERN against
>   the corresponding elements of the map.

> (btw: what PATTERN?),

the pattern that is gotten by expanding.

> but then uses it like this:
>
>   (pcase type
>     (`list (map-pairs map))
>     (`hash-table (map--into-hash-table map))
>     (_ (error "Not a map type name: %S" type))))

(why does my definition look like

`(and (pred mapp)
        ,@(map--make-pcase-bindings args))

?)

> IOW, it actually uses sub-classes of 'map' as patterns.  Hmm...

> As an aside, when I look at such doc strings, I always become
> frustrated, because I must be extremely stupid to ask all these
> questions, when no one else evidently cares, which must mean they all
> understand this stuff, and only I alone don't, right?

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.

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.

When the pcase "compiler" finds a pattern that is defined as a macro, it
substitutes the "call" with the "code" returned by evaluating the macro
definition with the given arguments.  Exactly like Lisp macros are
expanded by the lisp compiler.  Just that we have pcase "code" (i.e.,
another pattern again) in this case.  This is done recursively, i.e. the
returned pattern can be a pcase macro, a include pcase macros, again,
etc.

Try to understand the definition of ` - it's a challenge, but if you
succeed, you will see that things are much easier than you had expected.


Michael.