Re: Replace trivial pcase occurrences in the Emacs sources

[Andy Moreton]

On Sun 28 Oct 2018, Stefan Monnier wrote:

>> pcase-lambda, pcase-let, pcase-let*, and pcase-dolist still have no
>> meaningful documentation,
>
> Not sure what kind of documentation would be more meaningful, sorry.
> Do you happen to have concrete questions about them which aren't answered
> by their docstrings?

Here is the documentation for lambda - reasonably complete and
descriptive, and with links to other referenced symbols:

  (lambda ARGS [DOCSTRING] [INTERACTIVE] BODY)

  Return a lambda expression.
  A call of the form (lambda ARGS DOCSTRING INTERACTIVE BODY) is
  self-quoting; the result of evaluating the lambda expression is the
  expression itself.  The lambda expression may then be treated as a
  function, i.e., stored as the function value of a symbol, passed to
  ‘funcall’ or ‘mapcar’, etc.

  ARGS should take the same form as an argument list for a ‘defun’.
  DOCSTRING is an optional documentation string.
   If present, it should describe how to call the function.
   But documentation strings are usually not useful in nameless functions.
  INTERACTIVE should be a call to the function ‘interactive’, which see.
  It may also be omitted.
  BODY should be a list of Lisp expressions.

Contrast this with the `pcase-lambda' docstring:

  (pcase-lambda LAMBDA-LIST &rest BODY)

  Like ‘lambda’ but allow each argument to be a pattern.
  I.e. accepts the usual &optional and &rest keywords, but every
  formal argument can be any pattern accepted by ‘pcase’ (a mere
  variable name being but a special case of it).

This mentions "each argument", but the arguments shown have
`LAMBDA-LIST' (which is not described) and BODY - is this an argument
that can be pattern ? There is no discussion of how pattern match
failure is treated - what happens ? Please note that users can only read
what is in the docstring, not the unwritten intentions of the docstring
author.

The `pcase-let' docstring warns that it assumes patterns will match and
fails arbitrarily if that is not the case. This seems a strng indicator
that this macro is unsafe for use in any user code.

The `pcase-let*' docstring does not mention a similar pattern matching
assumption, so does it also behave randomly on pattern match failure ?

The `pcase-dolist' docstring is entirely uninformative. None of the
arguments are described, nor are the semantics of the macro. The
docstring needs complete replacement.

The pcase-exhaustive docstring mentions that an error is signalled if
pattern matching fails, but which error ? How are users supposed to
write code that determines that a pattern match failure has occurred
rather than any other error ? Which error is signalled should be part of
the interface contract here, and should be documented.

There are no entry in the manual for the pcase macros, and there are no
meaningful examples to show proper usage of each of the pcase match
pattern types.

> Could you clarify what you find problematic in those uses?

Given that the documentation is insufficient to describe the syntax and
semantics of these macros, how can ordinary users discern the meaning of
a pcase construct that they read in code ? How can they learn to write
code containing pcase macros which has the user's desired semantics ?

How can users learn when these constructs may be beneficial and when
they should be avoided ?

    AndyM