X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fglasgow_exts.xml;h=48367490a297a6fab6d3ba0105a6b6e5967b6219;hb=44644ebe79c748861894de4813efd47dae6cb945;hp=d058119da0e69bea994a76027e8a3b9e72a6d11b;hpb=f9b37bc8e6ceae4da007623606201afa5c33a7fe;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/glasgow_exts.xml b/ghc/docs/users_guide/glasgow_exts.xml index d058119..4836749 100644 --- a/ghc/docs/users_guide/glasgow_exts.xml +++ b/ghc/docs/users_guide/glasgow_exts.xml @@ -219,6 +219,28 @@ documentation describes all the libraries that come with GHC. + + + Enables implicit parameters (see ). Currently also implied by + . + + Syntax stolen: + ?varid, + %varid. + + + + + + + Enables lexically-scoped type variables (see ). Implied by + . + + + + Enables Template Haskell (see describes all the libraries that come with GHC. - - - - Enables implicit parameters (see ). Currently also implied by - . - - Syntax stolen: - ?varid, - %varid. - - - @@ -270,7 +279,7 @@ became out of date, and wrong information is worse than none. The Real Truth about what primitive types there are, and what operations work over those types, is held in the file -fptools/ghc/compiler/prelude/primops.txt. +fptools/ghc/compiler/prelude/primops.txt.pp. This file is used directly to generate GHC's primitive-operation definitions, so it is always correct! It is also intended for processing into text. @@ -334,11 +343,16 @@ it is accidental that it is represented by a pointer. If a pointer represents a primitive value, then it really does point to that value: no unevaluated thunks, no indirections…nothing can be at the other end of the pointer than the primitive value. +A numerically-intensive program using unboxed types can +go a lot faster than its “standard” +counterpart—we saw a threefold speedup on one example. -There are some restrictions on the use of primitive types, the main -one being that you can't pass a primitive value to a polymorphic +There are some restrictions on the use of primitive types: + +The main restriction +is that you can't pass a primitive value to a polymorphic function or store one in a polymorphic data type. This rules out things like [Int#] (i.e. lists of primitive integers). The reason for this restriction is that polymorphic @@ -350,11 +364,33 @@ attempt to dereference the pointer, with disastrous results. Even worse, the unboxed value might be larger than a pointer (Double# for instance). + + You cannot bind a variable with an unboxed type +in a top-level binding. + + You cannot bind a variable with an unboxed type +in a recursive binding. + + You may bind unboxed variables in a (non-recursive, +non-top-level) pattern binding, but any such variable causes the entire +pattern-match +to become strict. For example: + + data Foo = Foo Int Int# - -Nevertheless, A numerically-intensive program using unboxed types can -go a lot faster than its “standard” -counterpart—we saw a threefold speedup on one example. + f x = let (Foo a b, w) = ..rhs.. in ..body.. + +Since b has type Int#, the entire pattern +match +is strict, and the program behaves as if you had written + + data Foo = Foo Int Int# + + f x = case ..rhs.. of { (Foo a b, w) -> ..body.. } + + + + @@ -389,21 +425,19 @@ values, but they avoid the heap allocation normally associated with using fully-fledged tuples. When an unboxed tuple is returned, the components are put directly into registers or on the stack; the unboxed tuple itself does not have a composite representation. Many -of the primitive operations listed in this section return unboxed +of the primitive operations listed in primops.txt.pp return unboxed tuples. +In particular, the IO and ST monads use unboxed +tuples to avoid unnecessary allocation during sequences of operations. There are some pretty stringent restrictions on the use of unboxed tuples: - - - - - Unboxed tuple types are subject to the same restrictions as +Values of unboxed tuple types are subject to the same restrictions as other unboxed types; i.e. they may not be stored in polymorphic data structures or passed to polymorphic functions. @@ -412,56 +446,46 @@ structures or passed to polymorphic functions. - Unboxed tuples may only be constructed as the direct result of -a function, and may only be deconstructed with a case expression. -eg. the following are valid: +No variable can have an unboxed tuple type, nor may a constructor or function +argument have an unboxed tuple type. The following are all illegal: -f x y = (# x+1, y-1 #) -g x = case f x x of { (# a, b #) -> a + b } - + data Foo = Foo (# Int, Int #) + f :: (# Int, Int #) -> (# Int, Int #) + f x = x -but the following are invalid: + g :: (# Int, Int #) -> Int + g (# a,b #) = a - - -f x y = g (# x, y #) -g (# x, y #) = x + y + h x = let y = (# x,x #) in ... - - - - - - - - No variable can have an unboxed tuple type. This is illegal: - - - -f :: (# Int, Int #) -> (# Int, Int #) -f x = x - - - -because x has an unboxed tuple type. - - - - -Note: we may relax some of these restrictions in the future. - - - -The IO and ST monads use unboxed -tuples to avoid unnecessary allocation during sequences of operations. +The typical use of unboxed tuples is simply to return multiple values, +binding those multiple results with a case expression, thus: + + f x y = (# x+1, y-1 #) + g x = case f x x of { (# a, b #) -> a + b } + +You can have an unboxed tuple in a pattern binding, thus + + f x = let (# p,q #) = h x in ..body.. + +If the types of p and q are not unboxed, +the resulting binding is lazy like any other Haskell pattern binding. The +above example desugars like this: + + f x = let t = case h x o f{ (# p,q #) -> (p,q) + p = fst t + q = snd t + in ..body.. + +Indeed, the bindings can even be recursive. @@ -901,18 +925,34 @@ Nevertheless, they can be useful when defining "phantom types". -Infix type constructors +Infix type constructors and classes -GHC allows type constructors to be operators, and to be written infix, very much +GHC allows type constructors and classes 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. :*:. + A type constructor or class 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. + Data type and type-synonym declarations can be written infix, parenthesised + if you want further arguments. E.g. + + data a :*: b = Foo a b + type a :+: b = Either a b + class a :=: b where ... + + data (a :**: b) x = Baz a b x + type (a :++: b) y = Either (a,b) y + + + + Types, and class constraints, can be written infix. For example + + x :: Int :*: Bool + f :: (a :=: b) => a -> b + Back-quotes work @@ -920,7 +960,7 @@ like expressions. More specifically: 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, + Fixities may be declared for type constructors, or classes, 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: @@ -934,13 +974,6 @@ like expressions. More specifically: 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 @@ -1698,7 +1731,7 @@ means Instance declarations - + Overlapping instances In general, GHC requires that that it be unambiguous which instance @@ -1754,6 +1787,11 @@ So GHC rejects the program. If you add the flag + +Because overlaps are checked and reported lazily, as described above, you need +the in the module that calls +the overloaded function, rather than in the module that defines it. + @@ -2070,6 +2108,68 @@ the binding for ?x, so the type of f is + +Implicit parameters and polymorphic recursion + + +Consider these two definitions: + + len1 :: [a] -> Int + len1 xs = let ?acc = 0 in len_acc1 xs + + len_acc1 [] = ?acc + len_acc1 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc1 xs + + ------------ + + len2 :: [a] -> Int + len2 xs = let ?acc = 0 in len_acc2 xs + + len_acc2 :: (?acc :: Int) => [a] -> Int + len_acc2 [] = ?acc + len_acc2 (x:xs) = let ?acc = ?acc + (1::Int) in len_acc2 xs + +The only difference between the two groups is that in the second group +len_acc is given a type signature. +In the former case, len_acc1 is monomorphic in its own +right-hand side, so the implicit parameter ?acc is not +passed to the recursive call. In the latter case, because len_acc2 +has a type signature, the recursive call is made to the +polymoprhic version, which takes ?acc +as an implicit parameter. So we get the following results in GHCi: + + Prog> len1 "hello" + 0 + Prog> len2 "hello" + 5 + +Adding a type signature dramatically changes the result! This is a rather +counter-intuitive phenomenon, worth watching out for. + + + +Implicit parameters and monomorphism + +GHC applies the dreaded Monomorphism Restriction (section 4.5.5 of the +Haskell Report) to implicit parameters. For example, consider: + + f :: Int -> Int + f v = let ?x = 0 in + let y = ?x + v in + let ?x = 5 in + y + +Since the binding for y falls under the Monomorphism +Restriction it is not generalised, so the type of y is +simply Int, not (?x::Int) => Int. +Hence, (f 9) returns result 9. +If you add a type signature for y, then y +will get type (?x::Int) => Int, so the occurrence of +y in the body of the let will see the +inner binding of ?x, so (f 9) will return +14. + + @@ -2640,22 +2740,19 @@ for rank-2 types. -A pattern type signature can introduce a scoped type -variable. For example - - - - +A lexically scoped type variable can be bound by: + +A declaration type signature () +A pattern type signature () +A result type signature () + +For example: f (xs::[a]) = ys ++ ys where ys :: [a] ys = reverse xs - - - - The pattern (xs::[a]) includes a type signature for xs. This brings the type variable a into scope; it scopes over all the patterns and right hand sides for this equation for f. @@ -2663,8 +2760,6 @@ In particular, it is in scope at the type signature for y. - Pattern type signatures are completely orthogonal to ordinary, separate -type signatures. The two can be used independently or together. At ordinary type signatures, such as that for ys, any type variables mentioned in the type signature that are not in scope are implicitly universally quantified. (If there are no type variables in @@ -2687,10 +2782,10 @@ So much for the basic idea. Here are the details. -What a pattern type signature means +What a scoped type variable means -A type variable brought into scope by a pattern type signature is simply -the name for a type. The restriction they express is that all occurrences +A lexically-scoped type variable is simply +the name for a type. The restriction it expresses is that all occurrences of the same name mean the same type. For example: f :: [Int] -> Int -> Int @@ -2860,7 +2955,33 @@ scope over the methods defined in the where part. For exampl - + +Declaration type signatures +A declaration type signature that has explicit +quantification (using forall) brings into scope the +explicitly-quantified +type variables, in the definition of the named function(s). For example: + + f :: forall a. [a] -> [a] + f (x:xs) = xs ++ [ x :: a ] + +The "forall a" brings "a" into scope in +the definition of "f". + +This only happens if the quantification in f's type +signature is explicit. For example: + + g :: [a] -> [a] + g (x:xs) = xs ++ [ x :: a ] + +This program will be rejected, because "a" does not scope +over the definition of "f", so "x::a" +means "x::forall a. a" by Haskell's usual implicit +quantification rules. + + + + Where a pattern type signature can occur @@ -2977,10 +3098,12 @@ in f4's scope. +Pattern type signatures are completely orthogonal to ordinary, separate +type signatures. The two can be used independently or together. - + Result type signatures @@ -3165,7 +3288,7 @@ class to the new type: As a result of this extension, all derived instances in newtype -declarations are treated uniformly (and implemented just by reusing + declarations are treated uniformly (and implemented just by reusing the dictionary for the representation type), except Show and Read, which really behave differently for the newtype and its representation. @@ -3246,6 +3369,14 @@ then we would not have been able to derive an instance for the classes usually have one "main" parameter for which deriving new instances is most interesting. +Lastly, all of this applies only for classes other than +Read, Show, Typeable, +and Data, for which the built-in derivation applies (section +4.3.3. of the Haskell Report). +(For the standard classes Eq, Ord, +Ix, and Bounded it is immaterial whether +the standard method is used or the one described here.) + @@ -4191,6 +4322,31 @@ Assertion failures can be caught, see the documentation for the . + + INCLUDE pragma + + The INCLUDE pragma is for specifying the names + of C header files that should be #include'd into + the C source code generated by the compiler for the current module (if + compiling via C). For example: + + +{-# INCLUDE "foo.h" #-} +{-# INCLUDE <stdio.h> #-} + + The INCLUDE pragma(s) must appear at the top of + your source file with any OPTIONS_GHC + pragma(s). + + An INCLUDE pragma is the preferred alternative + to the option (), because the + INCLUDE pragma is understood by other + compilers. Yet another alternative is to add the include file to each + foreign import declaration in your code, but we + don't recommend using this approach with GHC. + + INLINE and NOINLINE pragmas @@ -4364,16 +4520,19 @@ key_function :: Int -> String -> (Bool, Double) - OPTIONS pragma - OPTIONS + OPTIONS_GHC pragma + OPTIONS_GHC - pragmaOPTIONS + pragmaOPTIONS_GHC - The OPTIONS pragma is used to specify + The OPTIONS_GHC pragma is used to specify additional options that are given to the compiler when compiling this source file. See for details. + + Previous versions of GHC accepted OPTIONS rather + than OPTIONS_GHC, but that is now deprecated.