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

[David Kastrup]

Dmitry Gutov <address@hidden> writes:

> On 01/03/2016 05:52 PM, David Kastrup wrote:
>
>> More like "easier" to just use the _only_ documented kind of quote for
>> pcase everywhere.
>
> From pcase docstring:
>
>     'VAL              matches if the object is ‘equal’ to VAL

Congratulations.  From

<URL:https://www.gnu.org/software/emacs/manual/html_node/elisp/Pattern-matching-case-statement.html#index-pcase>

    To compare a particular value against various possible cases, the
    macro pcase can come handy. It takes the following form:

    (pcase exp branch1 branch2 branch3 …)

    where each branch takes the form (upattern body-forms…).

    It will first evaluate exp and then compare the value against each
    upattern to see which branch to use, after which it will run the
    corresponding body-forms. A common use case is to distinguish
    between a few different constant values:

    (pcase (get-return-code x)
      (`success       (message "Done!"))
      (`would-block   (message "Sorry, can't do it now"))
      (`read-only     (message "The shmliblick is read-only"))
      (`access-denied (message "You do not have the needed rights"))
      (code           (message "Unknown return code %S" code)))

    In the last clause, code is a variable that gets bound to the value that
    was returned by (get-return-code x).

And so forth and so on.  The whole documentation idea of "qpattern" and
"upattern" does not even _allow_ discussing different ways of quoting
(since of course '-quoted entries are different from "qpatterns" as they
don't interpret unquote and unquote-splicing, namely , and ,@) so the
Elisp manual entry, arguably the decisive reference for use of pcase,
actively avoids mentioning ' at all in order not to have to upset its
terminology.

This is not helpful, as witnessed by the actual code extracts seen in
the Emacs code base and mailing list.

-- 
David Kastrup