X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=f6879febecf3a1c4e660caf00235c09af0871bc1;hb=b7078f351d72f77b0a2b5d1fdf6e050ea0bfef61;hp=4e541a696629a2bd23f3275ddb4ada1a2cc0a9f1;hpb=d64022dc071b587c20a693b7f355f69dc110b707;p=ghc-hetmet.git
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 4e541a6..f6879fe 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -78,10 +78,11 @@ documentation describes all the libraries that come with GHC.
,
,
,
+ ,
,
,
,
- ,
+ ,
,
,
,
@@ -859,33 +860,58 @@ it, you can use the flag.
The recursive do-notation
- The recursive do-notation (also known as mdo-notation) is implemented as described in
-A recursive do for Haskell,
-by Levent Erkok, John Launchbury,
-Haskell Workshop 2002, pages: 29-37. Pittsburgh, Pennsylvania.
-This paper is essential reading for anyone making non-trivial use of mdo-notation,
-and we do not repeat it here.
-
-The do-notation of Haskell does not allow recursive bindings,
+The do-notation of Haskell 98 does not allow recursive bindings,
that is, the variables bound in a do-expression are visible only in the textually following
code block. Compare this to a let-expression, where bound variables are visible in the entire binding
group. It turns out that several applications can benefit from recursive bindings in
-the do-notation, and this extension provides the necessary syntactic support.
+the do-notation. The flag provides the necessary syntactic support.
-Here is a simple (yet contrived) example:
-
+Here is a simple (albeit contrived) example:
+{-# LANGUAGE DoRec #-}
import Control.Monad.Fix
-justOnes = mdo xs <- Just (1:xs)
- return xs
+justOnes = do { rec { xs <- Just (1:xs) }
+ ; return (map negate xs) }
+As you can guess justOnes will evaluate to Just [-1,-1,-1,....
+
-As you can guess justOnes will evaluate to Just [1,1,1,....
+The background and motivation for recusrive do-notation is described in
+A recursive do for Haskell,
+by Levent Erkok, John Launchbury,
+Haskell Workshop 2002, pages: 29-37. Pittsburgh, Pennsylvania.
+This paper is essential reading for anyone making non-trivial use of mdo-notation,
+and we do not repeat it here. However, note that GHC uses a different syntax than the one
+in the paper.
+
+Details of recursive do-notation
+
+The recursive do-notation is enabled with the flag or, equivalently,
+the LANGUAGE pragma . It introduces the single new keyword "rec",
+which wraps a mutually-recursive group of monadic statements,
+producing a single statement.
+
+Similar to a let
+statement, the variables bound in the rec are
+visible throughout the rec group, and below it.
+For example, compare
+
+do { a <- getChar do { a <- getChar
+ ; let { r1 = f a r2 ; rec { r1 <- f a r2
+ ; r2 = g r1 } ; r2 <- g r1 }
+ ; return (r1 ++ r2) } ; return (r1 ++ r2) }
+
+In both cases, r1 and r2 are
+available both throughout the let or rec block, and
+in the statements that follow it. The difference is that let is non-monadic,
+while rec is monadic. (In Haskell let is
+really letrec, of course.)
+
The Control.Monad.Fix library introduces the MonadFix class. Its definition is:
@@ -898,30 +924,37 @@ The function mfix
dictates how the required recursion operation should be performed. For example,
justOnes desugars as follows:
-justOnes = mfix (\xs' -> do { xs <- Just (1:xs'); return xs }
+justOnes = do { xs <- mfix (\xs' -> do { xs <- Just (1:xs'); return xs })
+ ; return (map negate xs) }
-For full details of the way in which mdo is typechecked and desugared, see
-the paper A recursive do for Haskell.
-In particular, GHC implements the segmentation technique described in Section 3.2 of the paper.
-
-
-If recursive bindings are required for a monad,
-then that monad must be declared an instance of the MonadFix class.
-The following instances of MonadFix are automatically provided: List, Maybe, IO.
-Furthermore, the Control.Monad.ST and Control.Monad.ST.Lazy modules provide the instances of the MonadFix class
-for Haskell's internal state monad (strict and lazy, respectively).
+In general, the statment rec ss
+is desugared to the statement
+
+ vs <- mfix (\~vs -> do { ss; return vs })
+
+where vs is a tuple of the variables bound by ss.
+Moreover, the original rec typechecks exactly
+when the above desugared version would do so. (For example, this means that
+the variables vs are all monomorphic in the statements
+following the rec, because they are bound by a lambda.)
-Here are some important points in using the recursive-do notation:
+Here are some other important points in using the recursive-do notation:
-The recursive version of the do-notation uses the keyword mdo (rather
-than do).
+It is enabled with the flag -XDoRec, which is in turn implied by
+-fglasgow-exts.
-It is enabled with the flag -XRecursiveDo, which is in turn implied by
--fglasgow-exts.
+If recursive bindings are required for a monad,
+then that monad must be declared an instance of the MonadFix class.
+
+
+
+The following instances of MonadFix are automatically provided: List, Maybe, IO.
+Furthermore, the Control.Monad.ST and Control.Monad.ST.Lazy modules provide the instances of the MonadFix class
+for Haskell's internal state monad (strict and lazy, respectively).
@@ -931,20 +964,32 @@ be distinct (Section 3.3 of the paper).
-Variables bound by a let statement in an mdo
-are monomorphic in the mdo (Section 3.1 of the paper). However
-GHC breaks the mdo into segments to enhance polymorphism,
-and improve termination (Section 3.2 of the paper).
+Similar to let-bindings, GHC implements the segmentation technique described in Section 3.2 of
+A recursive do for Haskell,
+to break up a single rec statement into a sequence of statements with
+rec groups of minimal size. This
+improves polymorphism, reduces the size of the recursive "knot", and, as the paper
+describes, also has a semantic effect (unless the monad satisfies the right-shrinking law).
+
+
+ Mdo-notation (deprecated)
+ GHC used to support the flag ,
+which enabled the keyword mdo, precisely as described in
+A recursive do for Haskell,
+but this is now deprecated. Instead of mdo { Q; e }, write
+do { rec Q; e }.
+
Historical note: The old implementation of the mdo-notation (and most
of the existing documents) used the name
MonadRec for the class and the corresponding library.
This name is not supported by GHC.
+
@@ -1664,7 +1709,8 @@ The following syntax is stolen:
forall
- Stolen (in types) by: ,
+ Stolen (in types) by: , and hence by
+ ,
,
,
,
@@ -3157,7 +3203,8 @@ All the extensions are enabled by the flag.
Multi-parameter type classes
-Multi-parameter type classes are permitted. For example:
+Multi-parameter type classes are permitted, with flag .
+For example:
@@ -3169,13 +3216,17 @@ Multi-parameter type classes are permitted. For example:
-
+The superclasses of a class declaration
-There are no restrictions on the context in a class declaration
-(which introduces superclasses), except that the class hierarchy must
-be acyclic. So these class declarations are OK:
+In Haskell 98 the context of a class declaration (which introduces superclasses)
+must be simple; that is, each predicate must consist of a class applied to
+type variables. The flag
+()
+lifts this restriction,
+so that the only restriction on the context in a class declaration is
+that the class hierarchy must be acyclic. So these class declarations are OK:
@@ -3257,7 +3308,7 @@ There should be more documentation, but there isn't (yet). Yell if you need it.
Rules for functional dependencies
In a class declaration, all of the class type variables must be reachable (in the sense
-mentioned in )
+mentioned in )
from the free variables of each method type.
For example:
@@ -4708,10 +4759,30 @@ might be in another module, or even in a module that is not yet written.
Other type system extensions
-
-Type signatures
+Explicit universal quantification (forall)
+
+Haskell type signatures are implicitly quantified. When the language option
+is used, the keyword forall
+allows us to say exactly what this means. For example:
+
+
+
+ g :: b -> b
+
+means this:
+
+ g :: forall b. (b -> b)
+
+The two are treated identically.
+
+
+Of course forall becomes a keyword; you can't use forall as
+a type variable any more!
+
+
+
-The context of a type signature
+The context of a type signature
The flag lifts the Haskell 98 restriction
that the type-class constraints in a type signature must have the
@@ -4723,7 +4794,11 @@ these type signatures are perfectly OK
g :: Eq [a] => ...
g :: Ord (T a ()) => ...
+The flag also lifts the corresponding
+restriction on class declarations () and instance declarations
+().
+
GHC imposes the following restrictions on the constraints in a type signature.
Consider the type:
@@ -4736,7 +4811,7 @@ Consider the type:
language omits them; in Haskell 98, all the free type variables of an
explicit source-language type signature are universally quantified,
except for the class type variables in a class declaration. However,
-in GHC, you can give the foralls if you want. See ).
+in GHC, you can give the foralls if you want. See ).
@@ -4824,9 +4899,6 @@ territory free in case we need it later.
-
-
-
@@ -5304,22 +5376,7 @@ The parentheses are required.
-Haskell type signatures are implicitly quantified. The new keyword forall
-allows us to say exactly what this means. For example:
-
-
-
- g :: b -> b
-
-means this:
-
- g :: forall b. (b -> b)
-
-The two are treated identically.
-
-
-
-However, GHC's type system supports arbitrary-rank
+GHC's type system supports arbitrary-rank
explicit universal quantification in
types.
For example, all the following types are legal:
@@ -5374,8 +5431,6 @@ field type signatures.
-Of course forall becomes a keyword; you can't use forall as
-a type variable any more!
@@ -5990,6 +6045,21 @@ pattern binding must have the same context. For example, this is fine:
+
+Monomorphic local bindings
+
+We are actively thinking of simplifying GHC's type system, by not generalising local bindings.
+The rationale is described in the paper
+Let should not be generalised.
+
+
+The experimental new behaviour is enabled by the flag . The effect is
+that local (that is, non-top-level) bindings without a type signature are not generalised at all. You can
+think of it as an extreme (but much more predictable) version of the Monomorphism Restriction.
+If you supply a type signature, then the flag has no effect.
+
+
+
@@ -6056,12 +6126,11 @@ Wiki page.
have type Q Exp an type; the spliced expression must
have type Q Typ
- a list of top-level declarations; the spliced expression must have type Q [Dec]
+ a list of top-level declarations; the spliced expression
+ must have type Q [Dec]
-
Inside a splice you can can only call functions defined in imported modules,
- not functions defined elsewhere in the same module.
-
+ not functions defined elsewhere in the same module.
A expression quotation is written in Oxford brackets, thus:
@@ -6078,7 +6147,7 @@ Wiki page.
A quasi-quotation can appear in either a pattern context or an
expression context and is also written in Oxford brackets:
- [:varid| ... |],
+ [$varid| ... |],
where the "..." is an arbitrary string; a full description of the
quasi-quotation facility is given in .
@@ -6099,6 +6168,25 @@ Wiki page.
+ You may omit the $(...) in a top-level declaration splice.
+ Simply writing an expression (rather than a declaration) implies a splice. For example, you can write
+
+module Foo where
+import Bar
+
+f x = x
+
+$(deriveStuff 'f) -- Uses the $(...) notation
+
+g y = y+1
+
+deriveStuff 'g -- Omits the $(...)
+
+h z = z-1
+
+ This abbreviation makes top-level declaration slices quieter and less intimidating.
+
+
(Compared to the original paper, there are many differences of detail.