X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=5d1b5cf5f053bf3a3435740f51ee0a7a1c88d3f0;hp=dee62f469352e2cc6995d9fcf8e0f7eb6c9127a7;hb=432b9c9322181a3644083e3c19b7e240d90659e7;hpb=177b31ca6ebe01f8011926e30c4ac7ee32791753 diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml index dee62f4..5d1b5cf 100644 --- a/docs/users_guide/glasgow_exts.xml +++ b/docs/users_guide/glasgow_exts.xml @@ -38,19 +38,20 @@ documentation describes all the libraries that come with GHC. extensionsoptions controlling - The language option flag control what variation of the language are + The language option flags control what variation of the language are permitted. Leaving out all of them gives you standard Haskell 98. - Generally speaking, all the language options are introduced by "", - e.g. . - - - All the language options can be turned off by using the prefix ""; - e.g. "". - - Language options recognised by Cabal can also be enabled using the LANGUAGE pragma, - thus {-# LANGUAGE TemplateHaskell #-} (see >). + Language options can be controlled in two ways: + + Every language option can switched on by a command-line flag "" + (e.g. ), and switched off by the flag ""; + (e.g. ). + + Language options recognised by Cabal can also be enabled using the LANGUAGE pragma, + thus {-# LANGUAGE TemplateHaskell #-} (see ). + + The flag @@ -209,22 +210,20 @@ in a top-level binding. 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: +non-top-level) pattern binding, but you must make any such pattern-match +strict. For example, rather than: data Foo = Foo Int Int# 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 +you must write: data Foo = Foo Int Int# - f x = case ..rhs.. of { (Foo a b, w) -> ..body.. } + f x = let !(Foo a b, w) = ..rhs.. in ..body.. +since b has type Int#. @@ -334,6 +333,75 @@ Indeed, the bindings can even be recursive. Syntactic extensions + + Unicode syntax + The language + extension + enables Unicode characters to be used to stand for certain ASCII + character sequences. The following alternatives are provided: + + + + + + ASCII + Unicode alternative + Code point + Name + + + + + :: + :: + 0x2237 + PROPORTION + + + + + => + ⇒ + 0x21D2 + RIGHTWARDS DOUBLE ARROW + + + + + forall + ∀ + 0x2200 + FOR ALL + + + + + -> + → + 0x2192 + RIGHTWARDS ARROW + + + + + <- + ← + 0x2190 + LEFTWARDS ARROW + + + + + .. + … + 0x22EF + MIDLINE HORIZONTAL ELLIPSIS + + + + + + The magic hash The language extension allows "#" as a @@ -390,7 +458,7 @@ Indeed, the bindings can even be recursive. the syntax by eliminating odd cases like Prelude... For example, when NewQualifiedOperators is on, it is possible to - write the enerated sequence [Monday..] + write the enumerated sequence [Monday..] without spaces, whereas in Haskell 98 this would be a reference to the operator ‘.‘ from module Monday. @@ -938,6 +1006,7 @@ This name is not supported by GHC. paper Comprehensive comprehensions: comprehensions with "order by" and "group by", except that the syntax we use differs slightly from the paper. +The extension is enabled with the flag . Here is an example: employees = [ ("Simon", "MS", 80) @@ -1232,7 +1301,7 @@ it is not clear which of the two types is intended. Haskell 98 regards all four as ambiguous, but with the - flag, GHC will accept + flag, GHC will accept the former two. The rules are precisely the same as those for instance declarations in Haskell 98, where the method names on the left-hand side of the method bindings in an instance declaration refer unambiguously @@ -1990,15 +2059,28 @@ main = do display (inc (inc counterB)) -- prints "##" -At the moment, record update syntax is only supported for Haskell 98 data types, -so the following function does not work: - +Record update syntax is supported for existentials (and GADTs): --- This is invalid; use explicit NewCounter instead for now setTag :: Counter a -> a -> Counter a setTag obj t = obj{ tag = t } +The rule for record update is this: +the types of the updated fields may +mention only the universally-quantified type variables +of the data constructor. For GADTs, the field may mention only types +that appear as a simple type-variable argument in the constructor's result +type. For example: + +data T a b where { T1 { f1::a, f2::b, f3::(b,c) } :: T a b } -- c is existential +upd1 t x = t { f1=x } -- OK: upd1 :: T a b -> a' -> T a' b +upd2 t x = t { f3=x } -- BAD (f3's type mentions c, which is + -- existentially quantified) +data G a b where { G1 { g1::a, g2::c } :: G a [c] } +upd3 g x = g { g1=x } -- OK: upd3 :: G a b -> c -> G c b +upd4 g x = g { g2=x } -- BAD (f2's type mentions c, which is not a simple + -- type-variable argument in G1's result type) + @@ -2270,16 +2352,46 @@ otherwise is a generalised data type ( +As with other type signatures, you can give a single signature for several data constructors. +In this example we give a single signature for T1 and T2: + + data T a where + T1,T2 :: a -> T a + T3 :: T a + + + + The type signature of each constructor is independent, and is implicitly universally quantified as usual. -Different constructors may have different universally-quantified type variables -and different type-class constraints. -For example, this is fine: +In particular, the type variable(s) in the "data T a where" header +have no scope, and different constructors may have different universally-quantified type variables: + + data T a where -- The 'a' has no scope + T1,T2 :: b -> T b -- Means forall b. b -> T b + T3 :: T a -- Means forall a. T a + + + + +A constructor signature may mention type class constraints, which can differ for +different constructors. For example, this is fine: data T a where - T1 :: Eq b => b -> T b + T1 :: Eq b => b -> b -> T b T2 :: (Show c, Ix c) => c -> [c] -> T c +When patten matching, these constraints are made available to discharge constraints +in the body of the match. For example: + + f :: T a -> String + f (T1 x y) | x==y = "yes" + | otherwise = "no" + f (T2 a b) = show a + +Note that f is not overloaded; the Eq constraint arising +from the use of == is discharged by the pattern match on T1 +and similarly the Show constraint arising from the use of show. @@ -2291,12 +2403,12 @@ have no scope. Indeed, one can write a kind signature instead: or even a mixture of the two: - data Foo a :: (* -> *) -> * where ... + data Bar a :: (* -> *) -> * where ... The type variables (if given) may be explicitly kinded, so we could also write the header for Foo like this: - data Foo a (b :: * -> *) where ... + data Bar a (b :: * -> *) where ... @@ -2327,27 +2439,48 @@ declaration. For example, these two declarations are equivalent +The type signature may have quantified type variables that do not appear +in the result type: + + data Foo where + MkFoo :: a -> (a->Bool) -> Foo + Nil :: Foo + +Here the type variable a does not appear in the result type +of either constructor. +Although it is universally quantified in the type of the constructor, such +a type variable is often called "existential". +Indeed, the above declaration declares precisely the same type as +the data Foo in . + +The type may contain a class context too, of course: + + data Showable where + MkShowable :: Show a => a -> Showable + + + + You can use record syntax on a GADT-style data type declaration: data Person where - Adult { name :: String, children :: [Person] } :: Person - Child { name :: String } :: Person + Adult :: { name :: String, children :: [Person] } -> Person + Child :: Show a => { name :: !String, funny :: a } -> Person As usual, for every constructor that has a field f, the type of field f must be the same (modulo alpha conversion). - - -At the moment, record updates are not yet possible with GADT-style declarations, -so support is limited to record construction, selection and pattern matching. -For example - - aPerson = Adult { name = "Fred", children = [] } +The Child constructor above shows that the signature +may have a context, existentially-quantified variables, and strictness annotations, +just as in the non-record case. (NB: the "type" that follows the double-colon +is not really a type, because of the record syntax and strictness annotations. +A "type" of this form can appear only in a constructor signature.) + - shortName :: Person -> Bool - hasChildren (Adult { children = kids }) = not (null kids) - hasChildren (Child {}) = False - + +Record updates are allowed with GADT-style declarations, +only fields that have the following property: the type of the field +mentions no existential type variables. @@ -2599,7 +2732,7 @@ GHC always treats the last parameter of the instance -Deriving clause for classes <literal>Typeable</literal> and <literal>Data</literal> +Deriving clause for extra classes (<literal>Typeable</literal>, <literal>Data</literal>, etc) Haskell 98 allows the programmer to add "deriving( Eq, Ord )" to a data type @@ -2609,11 +2742,11 @@ classes Eq, Ord, Enum, Ix, Bounded, Read, and Show. -GHC extends this list with two more classes that may be automatically derived -(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. +GHC extends this list with several more classes that may be automatically derived: + + With , you can derive instances of the classes +Typeable, and Data, defined in the library +modules Data.Typeable and Data.Generics respectively. An instance of Typeable can only be derived if the data type has seven or fewer type parameters, all of kind *. @@ -2629,6 +2762,26 @@ In other cases, there is nothing to stop the programmer writing a Typab class, whose kind suits that of the data type constructor, and then writing the data type instance by hand. + + + With , you can derive instances of +the class Functor, +defined in GHC.Base. + + + With , you can derive instances of +the class Foldable, +defined in Data.Foldable. + + + With , you can derive instances of +the class Traversable, +defined in Data.Traversable. + + +In each case the appropriate class must be in scope before it +can be mentioned in the deriving clause. + @@ -3847,37 +4000,71 @@ data instance GMap (Either a b) v = GMapEither (GMap a v) (GMap b v) can be any number. - Data and newtype instance declarations are only legit when an - appropriate family declaration is in scope - just like class instances - require the class declaration to be visible. Moreover, each instance + Data and newtype instance declarations are only permitted when an + appropriate family declaration is in scope - just as a class instance declaratoin + requires the class declaration to be visible. Moreover, each instance declaration has to conform to the kind determined by its family declaration. This implies that the number of parameters of an instance declaration matches the arity determined by the kind of the family. - Although, all data families are declared with - the data keyword, instances can be - either data or newtypes, or a mix - of both. + A data family instance declaration can use the full exprssiveness of + ordinary data or newtype declarations: + + Although, a data family is introduced with + the keyword "data", a data family instance can + use either data or newtype. For example: + +data family T a +data instance T Int = T1 Int | T2 Bool +newtype instance T Char = TC Bool + + + A data instance can use GADT syntax for the data constructors, + and indeed can define a GADT. For example: + +data family G a b +data instance G [a] b where + G1 :: c -> G [Int] b + G2 :: G [a] Bool + + + You can use a deriving clause on a + data instance or newtype instance + declaration. + + + + + Even if type families are defined as toplevel declarations, functions - that perform different computations for different family instances still + that perform different computations for different family instances may still need to be defined as methods of type classes. In particular, the following is not possible: data family T a data instance T Int = A data instance T Char = B -nonsence :: T a -> Int -nonsence A = 1 -- WRONG: These two equations together... -nonsence B = 2 -- ...will produce a type error. +foo :: T a -> Int +foo A = 1 -- WRONG: These two equations together... +foo B = 2 -- ...will produce a type error. + +Instead, you would have to write foo as a class operation, thus: + +class C a where + foo :: T a -> Int +instance Foo Int where + foo A = 1 +instance Foo Char where + foo B = 2 - Given the functionality provided by GADTs (Generalised Algebraic Data + (Given the functionality provided by GADTs (Generalised Algebraic Data Types), it might seem as if a definition, such as the above, should be feasible. However, type families are - in contrast to GADTs - are open; i.e., new instances can always be added, possibly in other modules. Supporting pattern matching across different data instances - would require a form of extensible case construct. + would require a form of extensible case construct.) @@ -5309,9 +5496,13 @@ f xs = ys ++ ys ys :: [a] ys = reverse xs -The type signature for f brings the type variable a into scope; it scopes over -the entire definition of f. -In particular, it is in scope at the type signature for ys. +The type signature for f brings the type variable a into scope, +because of the explicit forall (). +The type variables bound by a forall scope over +the entire definition of the accompanying value declaration. +In this example, the type variable a scopes over the whole +definition of f, including over +the type signature for ys. In Haskell 98 it is not possible to declare a type for ys; a major benefit of scoped type variables is that it becomes possible to do so. @@ -5712,6 +5903,8 @@ Wiki page. an expression; the spliced expression must 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] @@ -5760,7 +5953,7 @@ Wiki page. (Compared to the original paper, there are many differences of detail. The syntax for a declaration splice uses "$" not "splice". The type of the enclosed expression must be Q [Dec], not [Q Dec]. -Type splices are not implemented, and neither are pattern splices or quotations. +Pattern splices and quotations are not implemented.) @@ -5977,7 +6170,7 @@ main = do { print $ eval [$expr|1 + 2|] module Expr where import qualified Language.Haskell.TH as TH -import Language.Haskell.TH.Quasi +import Language.Haskell.TH.Quote data Expr = IntExpr Integer | AntiIntExpr String @@ -6561,13 +6754,24 @@ Because the preprocessor targets Haskell (rather than Core), Bang patterns GHC supports an extension of pattern matching called bang -patterns. Bang patterns are under consideration for Haskell Prime. +patterns, written !pat. +Bang patterns are under consideration for Haskell Prime. The Haskell prime feature description contains more discussion and examples than the material below. +The key change is the addition of a new rule to the +semantics of pattern matching in the Haskell 98 report. +Add new bullet 10, saying: Matching the pattern !pat +against a value v behaves as follows: + +if v is bottom, the match diverges +otherwise, pat is matched against v + + + Bang patterns are enabled by the flag . @@ -6598,9 +6802,40 @@ A bang only really has an effect if it precedes a variable or wild-card pattern: f3 !(x,y) = [x,y] f4 (x,y) = [x,y] -Here, f3 and f4 are identical; putting a bang before a pattern that +Here, f3 and f4 are identical; +putting a bang before a pattern that forces evaluation anyway does nothing. - + + +There is one (apparent) exception to this general rule that a bang only +makes a difference when it precedes a variable or wild-card: a bang at the +top level of a let or where +binding makes the binding strict, regardless of the pattern. For example: + +let ![x,y] = e in b + +is a strict binding: operationally, it evaluates e, matches +it against the pattern [x,y], and then evaluates b. +(We say "apparent" exception because the Right Way to think of it is that the bang +at the top of a binding is not part of the pattern; rather it +is part of the syntax of the binding.) +Nested bangs in a pattern binding behave uniformly with all other forms of +pattern matching. For example + +let (!x,[y]) = e in b + +is equivalent to this: + +let { t = case e of (x,[y]) -> x `seq` (x,y) + x = fst t + y = snd t } +in b + +The binding is lazy, but when either x or y is +evaluated by b the entire pattern is matched, including forcing the +evaluation of x. + + Bang patterns work in case expressions too, of course: g5 x = let y = f x in body @@ -6610,18 +6845,6 @@ g7 x = case f x of { !y -> body } The functions g5 and g6 mean exactly the same thing. But g7 evaluates (f x), binds y to the result, and then evaluates body. - -Bang patterns work in let and where -definitions too. For example: - -let ![x,y] = e in b - -is a strict pattern: operationally, it evaluates e, matches -it against the pattern [x,y], and then evaluates b -The "!" should not be regarded as part of the pattern; after all, -in a function argument ![x,y] means the -same as [x,y]. Rather, the "!" -is part of the syntax of let bindings. @@ -6807,14 +7030,31 @@ Assertion failures can be caught, see the documentation for the word. The various values for word that GHC understands are described in the following sections; any pragma encountered with an - unrecognised word is (silently) + unrecognised word is ignored. The layout rule applies in pragmas, so the closing #-} should start in a column to the right of the opening {-#. - Certain pragmas are file-header pragmas. A file-header - pragma must precede the module keyword in the file. + Certain pragmas are file-header pragmas: + + + A file-header + pragma must precede the module keyword in the file. + + There can be as many file-header pragmas as you please, and they can be - preceded or followed by comments. + preceded or followed by comments. + + + File-header pragmas are read once only, before + pre-processing the file (e.g. with cpp). + + + The file-header pragmas are: {-# LANGUAGE #-}, + {-# OPTIONS_GHC #-}, and + {-# INCLUDE #-}. + + + LANGUAGE pragma @@ -7122,6 +7362,83 @@ happen. + + ANN pragmas + + GHC offers the ability to annotate various code constructs with additional + data by using three pragmas. This data can then be inspected at a later date by + using GHC-as-a-library. + + + Annotating values + + ANN + + Any expression that has both Typeable and Data instances may be attached to a top-level value + binding using an ANN pragma. In particular, this means you can use ANN + to annotate data constructors (e.g. Just) as well as normal values (e.g. take). + By way of example, to annotate the function foo with the annotation Just "Hello" + you would do this: + + +{-# ANN foo (Just "Hello") #-} +foo = ... + + + + A number of restrictions apply to use of annotations: + + The binder being annotated must be at the top level (i.e. no nested binders) + The binder being annotated must be declared in the current module + The expression you are annotating with must have a type with Typeable and Data instances + The Template Haskell staging restrictions apply to the + expression being annotated with, so for example you cannot run a function from the module being compiled. + + To be precise, the annotation {-# ANN x e #-} is well staged if and only if $(e) would be + (disregarding the usual type restrictions of the splice syntax, and the usual restriction on splicing inside a splice - $([|1|]) is fine as an annotation, albeit redundant). + + + If you feel strongly that any of these restrictions are too onerous, + please give the GHC team a shout. + + + However, apart from these restrictions, many things are allowed, including expressions which are not fully evaluated! + Annotation expressions will be evaluated by the compiler just like Template Haskell splices are. So, this annotation is fine: + + +{-# ANN f SillyAnnotation { foo = (id 10) + $([| 20 |]), bar = 'f } #-} +f = ... + + + + + Annotating types + + ANN type + ANN + + You can annotate types with the ANN pragma by using the type keyword. For example: + + +{-# ANN type Foo (Just "A `Maybe String' annotation") #-} +data Foo = ... + + + + + Annotating modules + + ANN module + ANN + + You can annotate modules with the ANN pragma by using the module keyword. For example: + + +{-# ANN module (Just "A `Maybe String' annotation") #-} + + + + LINE pragma @@ -8026,7 +8343,7 @@ r) -> Special built-in functions GHC has a few built-in functions with special behaviour. These are now described in the module GHC.Prim +url="../libraries/ghc-prim/GHC-Prim.html">GHC.Prim in the library documentation.