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

changed weight to 5

added Tbug Trac import documentation labels

assigned to @mpickering

Thanks Thomas for the notes. I think much of the confusion around *pattern* synonyms is that the pattern part is (now) only a small part of what they are. A perhaps nicer way to think about them is as normal data constructors but not attached to a specific type like normal data constructors. After declaring a bidirectional synonym

pattern P x = [x]

then P should behave (nearly) exactly like a data constructor but instead of constructing some type Q, constructs lists.

I will try to improve this section whilst working on D1152.

so function f is rejected because the type signature is Maybe

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

I'm working through this now, if you add the type signature it suggests then it does fail to compile. However, the most general type works fine which I imagine is what you discovered.

It is confusing that the type signatures are commented out.

mentioned in commit b72ca3e3

closed

Trac metadata

Trac field	Value
Resolution	Unresolved → ResolvedFixed

Much better. Thanks!

The user guide (which is definitely much improved) still reads

A more complete specification can be found on the ghc-wiki.

I really think we should refrain from linking to the wiki from the users guide. For implemented stuff, the user’s guide should contain all that is necessary for a user to understand a feature. If there is anything of relevance in the wiki, then it needs to be moved to the user’s guide.

OTOH, if there is nothing of relevance to the user (e.g. rationale for this particular design, implementation aspects, historical notes), then we should send him there. Or at least write something like “For information on the history, the design process and the implementation, see the ghc-wiki”.

If you are worried about duplicated information, then remove from the wiki page whatever now has its authoritative place in the user’s guide, and maybe link to that from the wiki page.

Joachim, are you saying there is relevant information on the wiki page which should be in the user guide? Were you able to understand the feature by reading the relevant section?

Joachim, are you saying there is relevant information on the wiki page which should be in the user guide?

I’m not saying that (I didn’t read it in detail). If you think everything important is in the guide, we can simply remove the reference to the wiki, right?

changed milestone to %8.0.1

added Pnormal label