X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=372ebab6fcfee28552cd754a08da78cd612c5928;hp=a1c25e4333e2a2929c60479749184cfdc681c12c;hb=25f84fa7e4b84c3db5ba745a7881c009b778e0b1;hpb=0f556c9933f8214240e3143e5d18b2916b540521 diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml index a1c25e4..372ebab 100644 --- a/docs/users_guide/glasgow_exts.xml +++ b/docs/users_guide/glasgow_exts.xml @@ -717,9 +717,11 @@ qualifier list has just one element, a boolean expression. The recursive do-notation (also known as mdo-notation) is implemented as described in -"A recursive do for Haskell", -Levent Erkok, John Launchbury", +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, @@ -750,17 +752,24 @@ class Monad m => MonadFix m where The function mfix -dictates how the required recursion operation should be performed. If recursive bindings are required for a monad, -then that monad must be declared an instance of the MonadFix class. -For details, see the above mentioned reference. +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 } + +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). -There are three important points in using the recursive-do notation: +Here are some important points in using the recursive-do notation: The recursive version of the do-notation uses the keyword mdo (rather @@ -768,7 +777,21 @@ than do). -As with other extensions, ghc should be given the flag -fglasgow-exts +It is enabled with the flag -XRecursiveDo, which is in turn implied by +-fglasgow-exts. + + + +Unlike ordinary do-notation, but like let and where bindings, +name shadowing is not allowed; that is, all the names bound in a single mdo must +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). @@ -1893,9 +1916,77 @@ their selector functions actually have different types: + + +Extensions to the "deriving" mechanism + + +Inferred context for deriving clauses + + +The Haskell Report is vague about exactly when a deriving clause is +legal. For example: + + data T0 f a = MkT0 a deriving( Eq ) + data T1 f a = MkT1 (f a) deriving( Eq ) + data T2 f a = MkT2 (f (f a)) deriving( Eq ) + +The natural generated Eq code would result in these instance declarations: + + instance Eq a => Eq (T0 f a) where ... + instance Eq (f a) => Eq (T1 f a) where ... + instance Eq (f (f a)) => Eq (T2 f a) where ... + +The first of these is obviously fine. The second is still fine, although less obviously. +The third is not Haskell 98, and risks losing termination of instances. + + +GHC takes a conservative position: it accepts the first two, but not the third. The rule is this: +each constraint in the inferred instance context must consist only of type variables, +with no repititions. + + +This rule is applied regardless of flags. If you want a more exotic context, you can write +it yourself, using the standalone deriving mechanism. + + + + +Stand-alone deriving declarations + + +GHC now allows stand-alone deriving declarations, enabled by -XStandaloneDeriving: + + data Foo a = Bar a | Baz String + + deriving instance Eq a => Eq (Foo a) + +The syntax is identical to that of an ordinary instance declaration apart from (a) the keyword +deriving, and (b) the absence of the where part. +You must supply a context (in the example the context is (Eq a)), +exactly as you would in an ordinary instance declaration. +(In contrast the context is inferred in a deriving clause +attached to a data type declaration.) These deriving instance +rules obey the same rules concerning form and termination as ordinary instance declarations, +controlled by the same flags; see . + +The stand-alone syntax is generalised for newtypes in exactly the same +way that ordinary deriving clauses are generalised (). +For example: + + newtype Foo a = MkFoo (State Int a) + + deriving instance MonadState Int Foo + +GHC always treats the last parameter of the instance +(Foo in this exmample) as the type whose instance is being derived. + + + + Deriving clause for classes <literal>Typeable</literal> and <literal>Data</literal> @@ -1909,7 +2000,7 @@ classes Eq, Ord, GHC extends this list with two more classes that may be automatically derived -(provided the flag is specified): +(provided the flag is specified): Typeable, and Data. These classes are defined in the library modules Data.Typeable and Data.Generics respectively, and the appropriate class must be in scope before it can be mentioned in the deriving clause. @@ -1963,7 +2054,9 @@ dictionary, only slower! Generalising the deriving clause -GHC now permits such instances to be derived instead, so one can write +GHC now permits such instances to be derived instead, +using the flag , +so one can write newtype Dollars = Dollars Int deriving (Eq,Show,Num) @@ -2009,7 +2102,7 @@ In this case the derived instance declaration is of the form Notice that, since Monad is a constructor class, the instance is a partial application of the new type, not the entire left hand side. We can imagine that the type declaration is -``eta-converted'' to generate the context of the instance +"eta-converted" to generate the context of the instance declaration. @@ -2125,41 +2218,13 @@ and Data, for which the built-in derivation applies (section the standard method is used or the one described here.) - - - - -Stand-alone deriving declarations - - -GHC now allows stand-alone deriving declarations, enabled by -fglasgow-exts: - - data Foo a = Bar a | Baz String - - derive instance Eq (Foo a) - -The token "derive" is a keyword only when followed by "instance"; -you can use it as a variable name elsewhere. -The stand-alone syntax is generalised for newtypes in exactly the same -way that ordinary deriving clauses are generalised (). -For example: - - newtype Foo a = MkFoo (State Int a) - - derive instance MonadState Int Foo - -GHC always treats the last parameter of the instance -(Foo in this exmample) as the type whose instance is being derived. - - - - -Other type system extensions + +Class and instances declarations Class declarations @@ -2814,7 +2879,8 @@ So GHC rejects the program. (If you add the flag , GHC will instead pick (C), without complaining about the problem of subsequent instantiations.) - + + Notice that we gave a type signature to f, so GHC had to check that f has the specified type. Suppose instead we do not give a type signature, asking GHC to infer @@ -2916,6 +2982,86 @@ reversed, but it makes sense to me. + +Overloaded string literals + + + +GHC supports overloaded string literals. Normally a +string literal has type String, but with overloaded string +literals enabled (with -XOverloadedStrings) + a string literal has type (IsString a) => a. + + +This means that the usual string syntax can be used, e.g., for packed strings +and other variations of string like types. String literals behave very much +like integer literals, i.e., they can be used in both expressions and patterns. +If used in a pattern the literal with be replaced by an equality test, in the same +way as an integer literal is. + + +The class IsString is defined as: + +class IsString a where + fromString :: String -> a + +The only predefined instance is the obvious one to make strings work as usual: + +instance IsString [Char] where + fromString cs = cs + +The class IsString is not in scope by default. If you want to mention +it explicitly (for exmaple, to give an instance declaration for it), you can import it +from module GHC.Exts. + + +Haskell's defaulting mechanism is extended to cover string literals, when is specified. +Specifically: + + +Each type in a default declaration must be an +instance of Num or of IsString. + + + +The standard defaulting rule (Haskell Report, Section 4.3.4) +is extended thus: defaulting applies when all the unresolved constraints involve standard classes +or IsString; and at least one is a numeric class +or IsString. + + + + +A small example: + +module Main where + +import GHC.Exts( IsString(..) ) + +newtype MyString = MyString String deriving (Eq, Show) +instance IsString MyString where + fromString = MyString + +greet :: MyString -> MyString +greet "hello" = "world" +greet other = other + +main = do + print $ greet "hello" + print $ greet "fool" + + + +Note that deriving Eq is necessary for the pattern matching +to work since it gets translated into an equality comparison. + + + + + + +Other type system extensions + Type signatures @@ -4131,81 +4277,6 @@ pattern binding must have the same context. For example, this is fine: - -Overloaded string literals - - - -GHC supports overloaded string literals. Normally a -string literal has type String, but with overloaded string -literals enabled (with -XOverloadedStrings) - a string literal has type (IsString a) => a. - - -This means that the usual string syntax can be used, e.g., for packed strings -and other variations of string like types. String literals behave very much -like integer literals, i.e., they can be used in both expressions and patterns. -If used in a pattern the literal with be replaced by an equality test, in the same -way as an integer literal is. - - -The class IsString is defined as: - -class IsString a where - fromString :: String -> a - -The only predefined instance is the obvious one to make strings work as usual: - -instance IsString [Char] where - fromString cs = cs - -The class IsString is not in scope by default. If you want to mention -it explicitly (for exmaple, to give an instance declaration for it), you can import it -from module GHC.Exts. - - -Haskell's defaulting mechanism is extended to cover string literals, when is specified. -Specifically: - - -Each type in a default declaration must be an -instance of Num or of IsString. - - - -The standard defaulting rule (Haskell Report, Section 4.3.4) -is extended thus: defaulting applies when all the unresolved constraints involve standard classes -or IsString; and at least one is a numeric class -or IsString. - - - - -A small example: - -module Main where - -import GHC.Exts( IsString(..) ) - -newtype MyString = MyString String deriving (Eq, Show) -instance IsString MyString where - fromString = MyString - -greet :: MyString -> MyString -greet "hello" = "world" -greet other = other - -main = do - print $ greet "hello" - print $ greet "fool" - - - -Note that deriving Eq is necessary for the pattern matching -to work since it gets translated into an equality comparison. - - - Type families @@ -6370,112 +6441,10 @@ r) -> Special built-in functions -GHC has a few built-in funcions with special behaviour, -described in this section. All are exported by -GHC.Exts. - - The <literal>seq</literal> function - -The function seq is as described in the Haskell98 Report. - - seq :: a -> b -> b - -It evaluates its first argument to head normal form, and then returns its -second argument as the result. The reason that it is documented here is -that, despite seq's polymorphism, its -second argument can have an unboxed type, or -can be an unboxed tuple; for example (seq x 4#) -or (seq x (# p,q #)). This requires b -to be instantiated to an unboxed type, which is not usually allowed. - - - - The <literal>inline</literal> function - -The inline function is somewhat experimental. - - inline :: a -> a - -The call (inline f) arranges that f -is inlined, regardless of its size. More precisely, the call -(inline f) rewrites to the right-hand side of f's -definition. -This allows the programmer to control inlining from -a particular call site -rather than the definition site of the function -(c.f. INLINE pragmas ). - - -This inlining occurs regardless of the argument to the call -or the size of f's definition; it is unconditional. -The main caveat is that f's definition must be -visible to the compiler. That is, f must be -let-bound in the current scope. -If no inlining takes place, the inline function -expands to the identity function in Phase zero; so its use imposes -no overhead. - - If the function is defined in another -module, GHC only exposes its inlining in the interface file if the -function is sufficiently small that it might be -inlined by the automatic mechanism. There is currently no way to tell -GHC to expose arbitrarily-large functions in the interface file. (This -shortcoming is something that could be fixed, with some kind of pragma.) - - - - The <literal>lazy</literal> function - -The lazy function restrains strictness analysis a little: - - lazy :: a -> a - -The call (lazy e) means the same as e, -but lazy has a magical property so far as strictness -analysis is concerned: it is lazy in its first argument, -even though its semantics is strict. After strictness analysis has run, -calls to lazy are inlined to be the identity function. - - -This behaviour is occasionally useful when controlling evaluation order. -Notably, lazy is used in the library definition of -Control.Parallel.par: - - par :: a -> b -> b - par x y = case (par# x) of { _ -> lazy y } - -If lazy were not lazy, par would -look strict in y which would defeat the whole -purpose of par. - - -Like seq, the argument of lazy can have -an unboxed type. - - - - - The <literal>unsafeCoerce#</literal> function - -The function unsafeCoerce# allows you to side-step the -typechecker entirely. It has type - - unsafeCoerce# :: a -> b - -That is, it allows you to coerce any type into any other type. If you use this -function, you had better get it right, otherwise segmentation faults await. -It is generally used when you want to write a program that you know is -well-typed, but where Haskell's type system is not expressive enough to prove -that it is well typed. - - -The argument to unsafeCoerce# can have unboxed types, -although extremely bad things will happen if you coerce a boxed type -to an unboxed type. - - - - +GHC has a few built-in funcions with special behaviour. These +are now described in the module GHC.Prim +in the library documentation.