reworking the informal explanation of pattern gaurds
[haskell-report.git] / report / exps.verb
index 9dc0b5e..6adba85 100644 (file)
@@ -1,5 +1,5 @@
 %
-% $Header: /home/cvs/root/haskell-report/report/exps.verb,v 1.19 2002/12/10 11:51:10 simonpj Exp $
+% $Header: /home/cvs/root/haskell-report/report/exps.verb,v 1.20 2003/01/13 13:08:55 simonpj Exp $
 %
 %*section 3
 %**<title>The Haskell 98 Report: Expressions</title>
@@ -663,7 +663,6 @@ on the instance declaration for the type "t".
 See Section~\ref{enum-class} for more details of which @Prelude@
 types are in @Enum@ and their semantics.
 
-
 \subsection{List Comprehensions}
 \index{list comprehension}
 \index{let expression!in list comprehensions}
@@ -671,9 +670,9 @@ types are in @Enum@ and their semantics.
 %
 @@@
 aexp   -> @[@ exp @|@ qual_1 @,@ ... @,@ qual_n @]@    & (\tr{list comprehension}, n>=1)
-qual   -> pat @<-@ exp         & (\tr{generator})
-         | @let@ decls         & (\tr{local declaration})
-         | exp                         & (\tr{guard})
+qual    -> pat @<-@ exp         & (\tr{generator})
+         | @let@ decls          & (\tr{local declaration})
+         | exp                  & (\tr{boolean guard})
 @@@
 \indexsyn{aexp}
 \indexsyn{qual}
@@ -683,13 +682,13 @@ A {\em list comprehension} has the form "@[@ e @|@ q_1@,@ ...@,@ q_n @]@,
 n>=1," where the "q_i" qualifiers\index{qualifier} are either
 \begin{itemize}
 \item {\em generators}\index{generator} of the form "p @<-@ e", where
-"p" is a 
+"p" is a
 pattern (see Section~\ref{pattern-matching}) of type "t" and "e" is an
 expression of type "@[@t@]@"
-\item {\em guards},\index{guard} which are arbitrary expressions of
-type @Bool@ 
+\item {\em boolean guards},\index{boolean guard} which are arbitrary expressions of
+type @Bool@
 \item {\em local bindings} that provide new definitions for use in
-the generated expression "e" or subsequent guards and generators.
+the generated expression "e" or subsequent boolean guards and generators.
 \end{itemize}
 
 Such a list comprehension returns the list of elements
@@ -704,7 +703,7 @@ match fails then that element of the list is simply skipped over.  Thus:\nopageb
       (3,x) <- xs ]
 @
 \eprog
-yields the list @[4,2]@.  If a qualifier is a guard, it must evaluate
+yields the list @[4,2]@.  If a qualifier is a boolen guard, it must evaluate
 to @True@ for the previous pattern match to succeed.  
 As usual, bindings in list comprehensions can shadow those in outer
 scopes; for example:
@@ -812,19 +811,24 @@ Section~\ref{pattern-bindings}.
 %
 @@@
 exp    ->  @case@ exp @of@ @{@ alts @}@
-alts   ->  alt_1 @;@ ... @;@ alt_n             & (n>=0)
+alts   ->  alt_1 @;@ ... @;@ alt_n             & (n>=1)
 alt    ->  pat @->@ exp [@where@ decls]
        |   pat gdpat [@where@ decls]
        |                                       & (empty alternative)
 
-gdpat   ->  gd @->@ exp [ gdpat ]
-gd     ->  @|@ exp^0 
+gdpat   ->  guards @->@ exp [ gdpat ]
+guards ->  @|@ guard_1, ..., guard_n             & (n>=1)
+guard  -> pat @<-@ exp^0       & (\tr{pattern guard})
+         | @let@ decls         & (\tr{local declaration})
+         | exp^0               & (\tr{boolean guard})
 @@@
 \indexsyn{exp}%
 \indexsyn{alts}%
 \indexsyn{alt}%
 \indexsyn{gdpat}%
-\indexsyn{gd}%
+\indexsyn{guards}%
+\indexsyn{guard}%
+
 
 A {\em case expression}\index{case expression} has the general form
 \[
@@ -832,20 +836,36 @@ A {\em case expression}\index{case expression} has the general form
 \]
 where each "match_i" is of the general form
 \[\ba{lll}
- & "@|@ g_{i1}"   & "@->@ e_{i1}" \\
+ & "@|@ gs_{i1}"   & "@->@ e_{i1}" \\
  & "..." \\
- & "@|@ g_{im_i}" & "@->@ e_{im_i}" \\
+ & "@|@ gs_{im_i}" & "@->@ e_{im_i}" \\
  & \multicolumn{2}{l}{"@where@ decls_i"}
 \ea\]
-(Notice that in the syntax rule for "gd", the ``@|@'' is a 
+(Notice that in the syntax rule for "guards", the ``@|@'' is a 
 terminal symbol, not the syntactic metasymbol for alternation.)
 Each alternative "p_i match_i" consists of a 
 pattern\index{pattern} "p_i" and its matches, "match_i".
 Each match in turn
 consists of a sequence of pairs of guards\index{guard}
-"g_{ij}" and bodies "e_{ij}" (expressions), followed by
+"gs_{ij}" and bodies "e_{ij}" (expressions), followed by
 optional bindings ("decls_i") that scope over all of the guards and
-expressions of the alternative.  An alternative of the form
+expressions of the alternative.
+
+\index{Pattern Guards}
+\index{guards}
+A {\em guard}\index{guard} has one of the following forms:
+\begin{itemize}
+\item {\em pattern guards}\index{pattern guard} are of the form "p @<-@ e", where
+"p" is a 
+pattern (see Section~\ref{pattern-matching}) of type "t" and "e" is an
+expression type "t".  They succeed if the expression "e" matches the pattern "p", and introduce the bindings of the pattern to the environment.
+\item {\em boolean guards}\index{boolean guard} are arbitrary expressions of
+type @Bool@.  They succeed if the expression evaluates to @True@, and they do not introduce new names to the environment.  A boolean guard, "g", is semantically equivalent to the pattern guard "@True <- @g".
+\item {\em local bindings} are of the form "@let @decls".  They always succeed, and they introduce the names defined in "decls" to the environment.
+\end{itemize}
+
+
+An alternative of the form
 \[
 "pat @->@ exp @where@ decls"
 \]
@@ -861,21 +881,29 @@ type of the whole expression is that type.
 
 A case expression is evaluated by pattern matching the expression "e"
 against the individual alternatives.  The alternatives are tried
-sequentially, from top to bottom.  If "e" matches the pattern in the
-alternative, the guards for that alternative are tried sequentially
-from top to bottom, in the environment of the case expression extended
-first by the bindings created during the matching of the pattern, and then 
-by the "decls_i" in the @where@ clause associated with that alternative.  
-If one of the guards
-evaluates to @True@, the corresponding right-hand side is evaluated in the
-same environment as the guard.
-If all the guards evaluate to @False@, matching continues with the
-next alternative.  If no match succeeds, the result is "\bot".
-Pattern matching is described in Section~\ref{pattern-matching}, with
-the formal semantics of case expressions in
-Section~\ref{case-semantics}.
-
-{\em A note about parsing}. The expression
+sequentially, from top to bottom.  If "e" matches the pattern of an
+alternative, then the guarded expressions for that alternative are
+tried sequentially from top to bottom in the environment of the case
+expression extended first by the bindings created during the matching
+of the pattern, and then by the "decls_i" in the @where@ clause
+associated with that alternative.
+
+For each guarded expression, the comma-separated guards are tried
+sequentially from left to right.  If all of them succeed, then the
+corresponding expression is evaluated in the environment extended with
+the bindings introduced by the guards.  That is, the bindings that are
+introduced by a guard (either by using a let clause or a pattern
+guard) are in scope in the following guards and the corresponding
+expression.  If any of the guards fail, then this guarded expression
+fails and the next guarded expression is tried.
+
+If none of the guarded expressions for a given alternative succeed,
+then matching continues with the next alternative.  If no alternative
+succeeds, then the result is "\bot".  Pattern matching is described in
+Section~\ref{pattern-matching}, with the formal semantics of case
+expressions in Section~\ref{case-semantics}.
+
+{\em A note about parsing.} The expression
 \bprog
 @
   case x of { (a,_) | let b = not a in b :: Bool -> a }
@@ -890,7 +918,7 @@ is tricky to parse correctly.  It has a single unambiguous parse, namely
 However, the phrase "@Bool -> a@" is syntactically valid as a type, and
 parsers with limited lookahead may incorrectly commit to this choice, and hence
 reject the program.  Programmers are advised, therefore, to avoid guards that
-end with a type signature --- indeed that is why a "gd" contains 
+end with a type signature --- indeed that is why a "guard" contains 
 an "exp^0" not an "exp".
 
 \subsection{Do Expressions}
@@ -1464,15 +1492,10 @@ Additional examples may be found in Section~\ref{datatype-renaming}.
 % \eprogNoSkip
 % \end{enumerate}
 
-Top level patterns in case
-expressions and the set of top level patterns in function or pattern
-bindings may have zero or more associated {\em guards}\index{guard}.
-A guard is 
-a boolean expression that is evaluated only after all of the
-arguments have been successfully matched, and it must be true for the
-overall pattern match to succeed.  The environment of the guard is the same
-as the right-hand-side of the case-expression
-alternative, function definition, or pattern binding to which it is attached.
+Top level patterns in case expressions and the set of top level
+patterns in function or pattern bindings may have zero or more
+associated {\em qualifiers}\index{qualifier}.  See
+Section~\ref{qualifiers-in-patterns}.
 
 The guard semantics have an obvious influence on the
 strictness characteristics of a function or case expression.  In