[GHC] #10900: Suggestions for improvement of the PatternSynonyms chapter in the User's Guide

[GHC]

#10900: Suggestions for improvement of the PatternSynonyms chapter in the User's
Guide
-------------------------------------+-------------------------------------
              Reporter:  thomie      |             Owner:
                  Type:  bug         |            Status:  new
              Priority:  normal      |         Milestone:
             Component:              |           Version:  7.10.2
  Documentation                      |
              Keywords:              |  Operating System:  Unknown/Multiple
  PatternSynonms                     |
          Architecture:              |   Type of failure:  Documentation
  Unknown/Multiple                   |  bug
             Test Case:              |        Blocked By:
              Blocking:              |   Related Tickets:
Differential Revisions:              |
-------------------------------------+-------------------------------------
 I read the chapter on PatternSynonyms recently. Seems like a very useful
 feature! Here are my notes, in the same spirit as #10140.

 == 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, 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'?

--
Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/10900>
GHC <http://www.haskell.org/ghc/>
The Glasgow Haskell Compiler