Re: The poor state of documentation of pcase like things.

[Michael Heerdegen]

John Wiegley <address@hidden> writes:

> # QPatterns and UPatterns
>
> To master `pcase', there are two types of patterns you must know: UPatterns
> and QPatterns. UPatterns are the "logical" aspect of pattern matching, where
> we describe the kind of data we'd like to match against, and other special
> actions to take when it matches; and QPatterns are the "literal" aspect,
> stating the exact form of a particular match.

I think we should not emphasize QPatterns and UPatterns too much,
because today, ``' is just a pcase macro.  When not using ``' is pcase,
we speak of just PATTERNs.

> QPatterns are by far the easiest to think about. To match against any atom,
> string, or list of the same, the corresponding QPattern is that exact value.
> So the QPattern "foo" matches the string "foo", 1 matches the atom 1,
> etc.

Note that atoms are compared with `equal', so "foo" matches any string
"foo", for example.

> `pcase' matches against a list of UPatterns, so to use a QPattern, we must
> backquote it:
>
>     (pcase value
>       (`1 (message "Matched a 1"))
>       (`2 (message "Matched a 2"))
>       (`"Hello" (message "Matched the string Hello")))

We used to write it like that in the old times.  Today, we better quote
stuff at toplevel with quote: `''.

>     (pcase value
>       (`(_ 1 2)
>        (message "Matched a list of anything followed by (2 3)")))

The example is wrong, as already had been mentioned.


Just had a very quick look.


To sum up, I don't think that basing the tutorial on the difference of
qpatterns and upatterns is a good idea.  Destructuring is only one
specific aspect of pcase.  And there are even different means of
destructuring now, namely seq and map.

If there are still examples like

>     (pcase value
>       (`1 (message "Matched a 1"))
>       (`2 (message "Matched a 2"))
>       (`"Hello" (message "Matched the string Hello")))

in the info manual, they should be changed to not use backquote.


Regards,

Michael.