bug#20268: 25.0.50; pcase-lambda broken

[Andy Moreton <andrewjmoreton@gmail.com>]

On Tue 07 Apr 2015, Stefan Monnier wrote:

>> After the recent rewrite, pcase-lambda is broken. For example, eval the
>> following to get 46422 instead of the correct value 65535.
>
>>    (cl-some (pcase-lambda (`[fullsweep_after ,v]) v)
>>             '([min_bin_vheap_size 46422]
>>               [min_heap_size 233]
>>               [fullsweep_after 65535]
>>               [minor_gcs 40]))
>
> Indeed, that's the semantics I chose.
> The previous semantics was for the function to do nothing and return nil
> if the arg doesn't match.  The new semantics is the same as the one used
> by pcase-let.  It's not without its fault of course, but at least it does
> correspond to the usual idea of "destructuring" and generates more
> efficient code.

Please improve the documentation for the pcase macros:

 a) The elisp manual has reference documentation for pcase, but it is
    confusing and short on examples. The first example would be clearer
    if it was more like the second example, by showing some example
    forms that invoke pcase and the result of evaluating them.

    The description would flow more logically if the second example
    followed the reference that describes the allowed patterns, and 
    included an example of each type of pattern.

 b) Add meaningful help strings for pcase-lambda, pcase-let* and
    pcase-let. The existing help strings all say that these constructs
    are "the same as another thing only different" which only serves to
    obscure what they do. A user should be able to discern what the
    interface contract is without reading the implementation. A short
    motivating example for each macro would be helpful.

These improvements would make code using the pcase macros more readable,
and aid understanding of the intended semantics.

    AndyM