X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fglasgow_exts.sgml;h=d4a39bef56ca1f188bd3d36657347524cc4f8855;hb=7b398a32ad0e56d07bbf1feb653e3eda123dc9b2;hp=bc6dd137a7e8b82c846c92e3c5f736ce9cb33b1d;hpb=71f504147cda20d448b397b9872c2110bfbb6fbe;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml index bc6dd13..d4a39be 100644 --- a/ghc/docs/users_guide/glasgow_exts.sgml +++ b/ghc/docs/users_guide/glasgow_exts.sgml @@ -19,8 +19,9 @@ performance because of the implementation costs of Haskell's Before you get too carried away working at the lowest level (e.g., sloshing MutableByteArray#s around your program), you may wish to check if there are libraries that provide a -“Haskellised veneer” over the features you want. See -. +“Haskellised veneer” over the features you want. The +separate libraries documentation describes all the libraries that come +with GHC. @@ -52,6 +53,30 @@ program), you may wish to check if there are libraries that provide a + and : + + + + This option enables the language extension defined in the + Haskell 98 Foreign Function Interface Addendum plus deprecated + syntax of previous versions of the FFI for backwards + compatibility. + + + + + : + + + This option enables the deprecated with + keyword for implicit parameters; it is merely provided for backwards + compatibility. + It is independent of the + flag. + + + + : @@ -106,7 +131,7 @@ program), you may wish to check if there are libraries that provide a module namespace is flat, and you must not conflict with any Prelude module.) - Even though you have not imported the Prelude, all + Even though you have not imported the Prelude, most of the built-in syntax still refers to the built-in Haskell Prelude types and values, as specified by the Haskell Report. For example, the type [Int] @@ -115,51 +140,9 @@ program), you may wish to check if there are libraries that provide a translation for list comprehensions continues to use Prelude.map etc. - With one group of exceptions! You may want to - define your own numeric class hierarchy. It completely - defeats that purpose if the literal "1" means - "Prelude.fromInteger 1", which is what - the Haskell Report specifies. So the - flag causes the - following pieces of built-in syntax to refer to whatever - is in scope, not the Prelude versions: - - - - Integer and fractional literals mean - "fromInteger 1" and - "fromRational 3.2", not the - Prelude-qualified versions; both in expressions and in - patterns. - - - - Negation (e.g. "- (f x)") - means "negate (f x)" (not - Prelude.negate). - - - - In an n+k pattern, the standard Prelude - Ord class is still used for comparison, - but the necessary subtraction uses whatever - "(-)" is in scope (not - "Prelude.(-)"). - - - - Note: Negative literals, such as -3, are - specified by (a careful reading of) the Haskell Report as - meaning Prelude.negate (Prelude.fromInteger 3). - However, GHC deviates from this slightly, and treats them as meaning - fromInteger (-3). One particular effect of this - slightly-non-standard reading is that there is no difficulty with - the literal -2147483648 at type Int; - it means fromInteger (-2147483648). The strict interpretation - would be negate (fromInteger 2147483648), - and the call to fromInteger would overflow - (at type Int, remember). - + However, does + change the handling of certain built-in syntax: see + . @@ -181,19 +164,136 @@ program), you may wish to check if there are libraries that provide a With the flag, GHC lets you declare a data type with no constructors. For example: + data S -- S :: * data T a -- T :: * -> * + Syntactically, the declaration lacks the "= constrs" part. The -type can be parameterised, but only over ordinary types, of kind *; since -Haskell does not have kind signatures, you cannot parameterise over higher-kinded -types. +type can be parameterised over types of any kind, but if the kind is +not * then an explicit kind annotation must be used +(see ). Such data types have only one value, namely bottom. Nevertheless, they can be useful when defining "phantom types". + +Infix type constructors + + +GHC allows type constructors to be operators, and to be written infix, very much +like expressions. More specifically: + + + A type constructor can be an operator, beginning with a colon; e.g. :*:. + The lexical syntax is the same as that for data constructors. + + + Types can be written infix. For example Int :*: Bool. + + + Back-quotes work + as for expressions, both for type constructors and type variables; e.g. Int `Either` Bool, or + Int `a` Bool. Similarly, parentheses work the same; e.g. (:*:) Int Bool. + + + Fixities may be declared for type constructors just as for data constructors. However, + one cannot distinguish between the two in a fixity declaration; a fixity declaration + sets the fixity for a data constructor and the corresponding type constructor. For example: + + infixl 7 T, :*: + + sets the fixity for both type constructor T and data constructor T, + and similarly for :*:. + Int `a` Bool. + + + Function arrow is infixr with fixity 0. (This might change; I'm not sure what it should be.) + + + Data type and type-synonym declarations can be written infix. E.g. + + data a :*: b = Foo a b + type a :+: b = Either a b + + + + The only thing that differs between operators in types and operators in expressions is that + ordinary non-constructor operators, such as + and * + are not allowed in types. Reason: the uniform thing to do would be to make them type + variables, but that's not very useful. A less uniform but more useful thing would be to + allow them to be type constructors. But that gives trouble in export + lists. So for now we just exclude them. + + + + + + + +Explicitly-kinded quantification + + +Haskell infers the kind of each type variable. Sometimes it is nice to be able +to give the kind explicitly as (machine-checked) documentation, +just as it is nice to give a type signature for a function. On some occasions, +it is essential to do so. For example, in his paper "Restricted Data Types in Haskell" (Haskell Workshop 1999) +John Hughes had to define the data type: + + data Set cxt a = Set [a] + | Unused (cxt a -> ()) + +The only use for the Unused constructor was to force the correct +kind for the type variable cxt. + + +GHC now instead allows you to specify the kind of a type variable directly, wherever +a type variable is explicitly bound. Namely: + +data declarations: + + data Set (cxt :: * -> *) a = Set [a] + +type declarations: + + type T (f :: * -> *) = f Int + +class declarations: + + class (Eq a) => C (f :: * -> *) a where ... + +forall's in type signatures: + + f :: forall (cxt :: * -> *). Set cxt Int + + + + + +The parentheses are required. Some of the spaces are required too, to +separate the lexemes. If you write (f::*->*) you +will get a parse error, because "::*->*" is a +single lexeme in Haskell. + + + +As part of the same extension, you can put kind annotations in types +as well. Thus: + + f :: (Int :: *) -> Int + g :: forall a. a -> (a :: *) + +The syntax is + + atype ::= '(' ctype '::' kind ') + +The parentheses are required. + + + + Class method types @@ -859,24 +959,45 @@ is (?x::a) => (a,a), and not class constraints. -An implicit parameter is bound using an expression of the form -expr with binds, -where with is a new keyword. This form binds the implicit -parameters arising in the body, not the free variables as a let or -where would do. For example, we define the min function by binding -cmp. +An implicit parameter is bound using the standard +let binding form, where the bindings must be a +collection of simple bindings to implicit-style variables (no +function-style bindings, and no type signatures); these bindings are +neither polymorphic or recursive. This form binds the implicit +parameters arising in the body, not the free variables as a +let or where would do. For +example, we define the min function by binding +cmp. min :: [a] -> a - min = least with ?cmp = (<=) + min = let ?cmp = (<=) in least -Syntactically, the binds part of a with construct must be a -collection of simple bindings to variables (no function-style -bindings, and no type signatures); these bindings are neither -polymorphic or recursive. - -Note the following additional constraints: +Note the following points: + +You may not mix implicit-parameter bindings with ordinary bindings in a +single let +expression; use two nested lets instead. + + + +You may put multiple implicit-parameter bindings in a +single let expression; they are not treated +as a mutually recursive group (as ordinary let bindings are). +Instead they are treated as a non-recursive group, each scoping over the bindings that +follow. For example, consider: + + f y = let { ?x = y; ?x = ?x+1 } in ?x + +This function adds one to its argument. + + + +You may not have an implicit-parameter binding in a where clause, +only in a let binding. + + You can't have an implicit parameter in the context of a class or instance declaration. For example, both these declarations are illegal: @@ -918,12 +1039,14 @@ written '%x' instead of '?x'. For example: + import GHC.Exts( Splittable ) + data NameSupply = ... splitNS :: NameSupply -> (NameSupply, NameSupply) newName :: NameSupply -> Name - instance PrelSplit.Splittable NameSupply where + instance Splittable NameSupply where split = splitNS @@ -954,7 +1077,7 @@ the parameter explicit: Notice the call to 'split' introduced by the type checker. How did it know to use 'splitNS'? Because what it really did was to introduce a call to the overloaded function 'split', -defined by +defined by the class Splittable: class Splittable a where split :: a -> (a,a) @@ -968,8 +1091,8 @@ and GHC will infer g :: (Splittable a, %ns :: a) => b -> (b,a,a) -The Splittable class is built into GHC. It's defined in PrelSplit, -and exported by GlaExts. +The Splittable class is built into GHC. It's exported by module +GHC.Exts. Other points: @@ -1020,6 +1143,47 @@ Haskell programs without knowing their typing. +Recursive functions +Linear implicit parameters can be particularly tricky when you have a recursive function +Consider + + foo :: %x::T => Int -> [Int] + foo 0 = [] + foo n = %x : foo (n-1) + +where T is some type in class Splittable. + +Do you get a list of all the same T's or all different T's +(assuming that split gives two distinct T's back)? + +If you supply the type signature, taking advantage of polymorphic +recursion, you get what you'd probably expect. Here's the +translated term, where the implicit param is made explicit: + + foo x 0 = [] + foo x n = let (x1,x2) = split x + in x1 : foo x2 (n-1) + +But if you don't supply a type signature, GHC uses the Hindley +Milner trick of using a single monomorphic instance of the function +for the recursive calls. That is what makes Hindley Milner type inference +work. So the translation becomes + + foo x = let + foom 0 = [] + foom n = x : foom (n-1) + in + foom + +Result: 'x' is not split, and you get a list of identical T's. So the +semantics of the program depends on whether or not foo has a type signature. +Yikes! + +You may say that this is a good reason to dislike linear implicit parameters +and you'd be right. That is why they are an experimental feature. + + + @@ -1027,9 +1191,10 @@ Haskell programs without knowing their typing. Functional dependencies are implemented as described by Mark Jones -in "Type Classes with Functional Dependencies", Mark P. Jones, +in “Type Classes with Functional Dependencies”, Mark P. Jones, In Proceedings of the 9th European Symposium on Programming, -ESOP 2000, Berlin, Germany, March 2000, Springer-Verlag LNCS 1782. +ESOP 2000, Berlin, Germany, March 2000, Springer-Verlag LNCS 1782, +. @@ -1342,7 +1507,7 @@ for rank-2 types. - + Liberalised type synonyms @@ -1382,7 +1547,7 @@ You can apply a type synonym to a forall type: f :: Foo (forall b. b->b) -After epxanding the synonym, f has the legal (in GHC) type: +After expanding the synonym, f has the legal (in GHC) type: f :: (forall b. b->b) -> (forall b. b->b) -> Bool @@ -1470,6 +1635,18 @@ valid way to write g's type signature: g :: Int -> Int -> forall b. b -> Int + +When doing this hoisting operation, GHC eliminates duplicate constraints. For +example: + + type Foo a = (?x::Int) => Bool -> a + g :: Foo (Foo Int) + +means + + g :: (?x::Int) => Bool -> Bool -> Int + + @@ -1799,7 +1976,7 @@ declarations. Define your own instances! -Scoped Type Variables +<title>Scoped type variables @@ -2181,66 +2358,6 @@ in f4's scope. - -Explicitly-kinded quantification - - -Haskell infers the kind of each type variable. Sometimes it is nice to be able -to give the kind explicitly as (machine-checked) documentation, -just as it is nice to give a type signature for a function. On some occasions, -it is essential to do so. For example, in his paper "Restricted Data Types in Haskell" (Haskell Workshop 1999) -John Hughes had to define the data type: - - data Set cxt a = Set [a] - | Unused (cxt a -> ()) - -The only use for the Unused constructor was to force the correct -kind for the type variable cxt. - - -GHC now instead allows you to specify the kind of a type variable directly, wherever -a type variable is explicitly bound. Namely: - -data declarations: - - data Set (cxt :: * -> *) a = Set [a] - -type declarations: - - type T (f :: * -> *) = f Int - -class declarations: - - class (Eq a) => C (f :: * -> *) a where ... - -forall's in type signatures: - - f :: forall (cxt :: * -> *). Set cxt Int - - - - - -The parentheses are required. Some of the spaces are required too, to -separate the lexemes. If you write (f::*->*) you -will get a parse error, because "::*->*" is a -single lexeme in Haskell. - - - -As part of the same extension, you can put kind annotations in types -as well. Thus: - - f :: (Int :: *) -> Int - g :: forall a. a -> (a :: *) - -The syntax is - - atype ::= '(' ctype '::' kind ') - -The parentheses are required. - - @@ -2309,28 +2426,82 @@ assert pred val ==> assertError "Main.hs|15" pred val The rewrite is only performed by the compiler when it spots -applications of Exception.assert, so you can still define and -use your own versions of assert, should you so wish. If not, -import Exception to make use assert in your code. +applications of Control.Exception.assert, so you +can still define and use your own versions of +assert, should you so wish. If not, import +Control.Exception to make use +assert in your code. To have the compiler ignore uses of assert, use the compiler option -. -fignore-asserts option That is, -expressions of the form assert pred e will be rewritten to e. +. -fignore-asserts +option That is, expressions of the form +assert pred e will be rewritten to +e. Assertion failures can be caught, see the documentation for the -Exception library () -for the details. +Control.Exception library for the details. + + +Syntactic extensions + + + + + Hierarchical Modules + + GHC supports a small extension to the syntax of module + names: a module name is allowed to contain a dot + ‘.’. This is also known as the + “hierarchical module namespace” extension, because + it extends the normally flat Haskell module namespace into a + more flexible hierarchy of modules. + + This extension has very little impact on the language + itself; modules names are always fully + qualified, so you can just think of the fully qualified module + name as the module name. In particular, this + means that the full module name must be given after the + module keyword at the beginning of the + module; for example, the module A.B.C must + begin + +module A.B.C + + + It is a common strategy to use the as + keyword to save some typing when using qualified names with + hierarchical modules. For example: + + +import qualified Control.Monad.ST.Strict as ST + + + Hierarchical modules have an impact on the way that GHC + searches for files. For a description, see . + + GHC comes with a large collection of libraries arranged + hierarchically; see the accompanying library documentation. + There is an ongoing project to create and maintain a stable set + of core libraries used by several Haskell + compilers, and the libraries that GHC comes with represent the + current status of that project. For more details, see Haskell + Libraries. + + + - + Pattern guards @@ -2455,11 +2626,96 @@ f x | [y] <- x Haskell's current guards therefore emerge as a special case, in which the qualifier list has just one element, a boolean expression. - + + + + + +The recursive do-notation + + + The recursive do-notation (also known as mdo-notation) is implemented as described in +"A recursive do for Haskell", +Levent Erkok, John Launchbury", +Haskell Workshop 2002, pages: 29-37. Pittsburgh, Pennsylvania. + + +The do-notation of Haskell 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. + + +Here is a simple (yet contrived) example: + + +justOnes = mdo xs <- Just (1:xs) + return xs + + +As you can guess justOnes will evaluate to Just [1,1,1,.... + + + +The MonadFix library introduces the MonadFix class. It's definition is: + + +class Monad m => MonadFix m where + mfix :: (a -> m a) -> m a + + +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. + + +The MonadFix library automatically declares List, Maybe, IO, and +state monads (both lazy and strict) as instances of the MonadFix class. + + +There are three important points in using the recursive-do notation: + + +The recursive version of the do-notation uses the keyword mdo (rather +than do). + + + +If you want to declare an instance of the MonadFix class for one of +your own monads, or you need to refer to the class name MonadFix in any other way (for instance in +writing a type constraint), then your program should import Control.Monad.MonadFix. +Otherwise, you don't need to import any special libraries to use the mdo-notation. That is, +as long as you only use the predefined instances mentioned above, the mdo-notation will +be automatically available. (Note: This differs from the Hugs implementation, where +MonadFix should always be imported.) + + + +As with other extensions, ghc should be given the flag -fglasgow-exts + + + + + +Historical note: The originial implementation of the mdo-notation, and most +of the existing documents, use the names +MonadRec for the class, and +Control.Monad.MonadRec for the library. These names +are no longer supported. + + + +The web page: http://www.cse.ogi.edu/PacSoft/projects/rmb +contains up to date information on recursive monadic bindings. + + + - + Parallel List Comprehensions list comprehensionsparallel @@ -2507,7 +2763,80 @@ qualifier list has just one element, a boolean expression. where `zipN' is the appropriate zip for the given number of branches. - + + + +Rebindable syntax + + + GHC allows most kinds of built-in syntax to be rebound by + the user, to facilitate replacing the Prelude + with a home-grown version, for example. + + You may want to define your own numeric class + hierarchy. It completely defeats that purpose if the + literal "1" means "Prelude.fromInteger + 1", which is what the Haskell Report specifies. + So the flag causes + the following pieces of built-in syntax to refer to + whatever is in scope, not the Prelude + versions: + + + + Integer and fractional literals mean + "fromInteger 1" and + "fromRational 3.2", not the + Prelude-qualified versions; both in expressions and in + patterns. + However, the standard Prelude Eq class + is still used for the equality test necessary for literal patterns. + + + + Negation (e.g. "- (f x)") + means "negate (f x)" (not + Prelude.negate). + + + + In an n+k pattern, the standard Prelude + Ord class is still used for comparison, + but the necessary subtraction uses whatever + "(-)" is in scope (not + "Prelude.(-)"). + + + + "Do" notation is translated using whatever + functions (>>=), + (>>), fail, and + return, are in scope (not the Prelude + versions). List comprehensions, and parallel array + comprehensions, are unaffected. + + + Be warned: this is an experimental facility, with fewer checks than + usual. In particular, it is essential that the functions GHC finds in scope + must have the appropriate types, namely: + + fromInteger :: forall a. (...) => Integer -> a + fromRational :: forall a. (...) => Rational -> a + negate :: forall a. (...) => a -> a + (-) :: forall a. (...) => a -> a -> a + (>>=) :: forall m a. (...) => m a -> (a -> m b) -> m b + (>>) :: forall m a. (...) => m a -> m b -> m b + return :: forall m a. (...) => a -> m a + fail :: forall m a. (...) => String -> m a + + (The (...) part can be any context including the empty context; that part + is up to you.) + If the functions don't have the right type, very peculiar things may + happen. Use -dcore-lint to + typecheck the desugared program. If Core Lint is happy you should be all right. + + + @@ -3780,6 +4109,7 @@ classes usually have one "main" parameter for which deriving new instances is most interesting. +