Suggestions for improvement of the PatternSynonyms chapter in the User's Guide

I read the chapter on PatternSynonyms recently. Seems like a very useful feature! Here are my notes, in the same spirit as #10140 (closed).

7.3.9

• This section starts with a nice example of how pattern synonyms can make some code much clearer. No problems sofar.

Note that in this example, the pattern synonyms Int and Arrow can also be used as expressions (they are bidirectional).

• How can a pattern (synonym) possibly be used as an expression. They seem such

  different concepts. You say "bidirectional", but what are the directions? You mentioned "constructor-like" before, maybe it's

  something like that?

• This could use an example.

• Is Arrow Int Int an example of using a pattern synonym as an expression?

• What about pattern Maybe t, can it also be used as an expression? Why is

  this not mentioned? What is it doing there anyway, it's not used in either of

  the functions collectArgs, isInt and isIntEndo.

This is not necessarily the case: unidirectional pattern synonyms can also be declared with the following syntax

• Ok.

We can give an explicit inversion of a pattern synonym using the following syntax

• What does inverting a pattern synonym mean?
• You mentioned unidirectional and bidirectional pattern synonyms. Can I invert both?

pattern Head x <- x:xs where
    Head x = [x]

• Weird syntax. But what does it //do//? (I'm very confused now)

7.3.9.1

Either prefix or infix syntax can be used.

• I have no idea what this refers to.

For implicitly bidirectional pattern synonyms

• This is the first time you mention the word "implicit".

For unidirectional and explicitly-bidirectional pattern synonyms

• Ok, now it's getting clear. There seem to be 3 types of pattern synonyms. I wish you had said this earlier. (goes back to read from the beginning: ok I guess the first time you mentioned bidirectional patttern synonyms, they were the implicit ones, and the "explicit inversion" stuff with the weird syntax are the explicit ones.)

7.3.9.2

import Data.Maybe( pattern Just )

• This doesn't compile. It turns out I need the PatternSynonyms extension in the importing module, even though you said in the beginning "it is required for defining them, but //not// for using them".
• I later found #10653 (closed), so that explains it. Maybe mention that ticket.

7.3.9.3

In the common case where CReq is empty, (), it can be omitted altogether.

• Why is it more common for CReq to empty than for CProv to be empty?
• What if CProv is empty, but CReq isn't?
• What if both are empty, can they both be omitted?

so function f is rejected because the type signature is Maybe a

• I tried this example, and f is not rejected at all. **Bug**?

7.3.9.4

A pattern synonym occurrence in a pattern is evaluated by first matching against the pattern synonym itself, and then on the argument patterns.

• Should be "against the //rhs// of the pattern synonym" I think.
• This is tricky stuff. Why is pattern synonym semantics not just defined as 'textual substitution'?

Trac metadata

Trac field	Value
Version	7.10.2
Type	Bug
TypeOfFailure	OtherFailure
Priority	normal
Resolution	Unresolved
Component	Documentation
Test case
Differential revisions
BlockedBy
Related
Blocking
CC	cactus
Operating system
Architecture