X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=e42bf79f92c05e92f107443407b2ea941fca2fde;hp=0cd97c23261bad4d42179468150c856fa0404d9f;hb=0edaca4834b511ac2c58fea3734a75cc52ac5c50;hpb=137f52f48d24fa580ed38c6c923644b3f2daabbf diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml index 0cd97c2..e42bf79 100644 --- a/docs/users_guide/glasgow_exts.xml +++ b/docs/users_guide/glasgow_exts.xml @@ -92,7 +92,7 @@ documentation describes all the libraries that come with GHC. Haskell 98 described in , except where otherwise noted. We are trying to move away from this portmanteau flag, - and towards enabling features individaully. + and towards enabling features individually. New reserved words: forall (only in types), mdo. @@ -290,6 +290,17 @@ documentation describes all the libraries that come with GHC. + + + + Enables quasiquotation (see ). + + Syntax stolen: + [:varid|. + + + @@ -319,10 +330,10 @@ it is always correct! It is also intended for processing into text. Indeed, the result of such processing is part of the description of the External + url="http://www.haskell.org/ghc/docs/papers/core.ps.gz">External Core language. So that document is a good place to look for a type-set version. -We would be very happy if someone wanted to volunteer to produce an SGML +We would be very happy if someone wanted to volunteer to produce an XML back end to the program that processes primops.txt so that we could include the results here in the User Guide. @@ -742,7 +753,7 @@ view :: Type -> TypeView The representation of Typ is held abstract, permitting implementations -to use a fancy representation (e.g., hash-consing to managage sharing). +to use a fancy representation (e.g., hash-consing to manage sharing). Without view patterns, using this signature a little inconvenient: @@ -1058,6 +1069,166 @@ This name is not supported by GHC. branches. + + + + + Generalised (SQL-Like) List Comprehensions + list comprehensionsgeneralised + + extended list comprehensions + + group + sql + + + Generalised list comprehensions are a further enhancement to the + list comprehension syntatic sugar to allow operations such as sorting + and grouping which are familiar from SQL. They are fully described in the + paper + Comprehensive comprehensions: comprehensions with "order by" and "group by", + except that the syntax we use differs slightly from the paper. +Here is an example: + +employees = [ ("Simon", "MS", 80) +, ("Erik", "MS", 100) +, ("Phil", "Ed", 40) +, ("Gordon", "Ed", 45) +, ("Paul", "Yale", 60)] + +output = [ (the dept, sum salary) +| (name, dept, salary) <- employees +, then group by dept +, then sortWith by (sum salary) +, then take 5 ] + +In this example, the list output would take on + the value: + + +[("Yale", 60), ("Ed", 85), ("MS", 180)] + + +There are three new keywords: group, by, and using. +(The function sortWith is not a keyword; it is an ordinary +function that is exported by GHC.Exts.) + +There are five new forms of comprehension qualifier, +all introduced by the (existing) keyword then: + + + + +then f + + + This statement requires that f have the type + forall a. [a] -> [a]. You can see an example of it's use in the + motivating example, as this form is used to apply take 5. + + + + + + + +then f by e + + + This form is similar to the previous one, but allows you to create a function + which will be passed as the first argument to f. As a consequence f must have + the type forall a. (a -> t) -> [a] -> [a]. As you can see + from the type, this function lets f "project out" some information + from the elements of the list it is transforming. + + An example is shown in the opening example, where sortWith + is supplied with a function that lets it find out the sum salary + for any item in the list comprehension it transforms. + + + + + + + +then group by e using f + + + This is the most general of the grouping-type statements. In this form, + f is required to have type forall a. (a -> t) -> [a] -> [[a]]. + As with the then f by e case above, the first argument + is a function supplied to f by the compiler which lets it compute e on every + element of the list being transformed. However, unlike the non-grouping case, + f additionally partitions the list into a number of sublists: this means that + at every point after this statement, binders occurring before it in the comprehension + refer to lists of possible values, not single values. To help understand + this, let's look at an example: + + +-- This works similarly to groupWith in GHC.Exts, but doesn't sort its input first +groupRuns :: Eq b => (a -> b) -> [a] -> [[a]] +groupRuns f = groupBy (\x y -> f x == f y) + +output = [ (the x, y) +| x <- ([1..3] ++ [1..2]) +, y <- [4..6] +, then group by x using groupRuns ] + + + This results in the variable output taking on the value below: + + +[(1, [4, 5, 6]), (2, [4, 5, 6]), (3, [4, 5, 6]), (1, [4, 5, 6]), (2, [4, 5, 6])] + + + Note that we have used the the function to change the type + of x from a list to its original numeric type. The variable y, in contrast, is left + unchanged from the list form introduced by the grouping. + + + + + + +then group by e + + + This form of grouping is essentially the same as the one described above. However, + since no function to use for the grouping has been supplied it will fall back on the + groupWith function defined in + GHC.Exts. This + is the form of the group statement that we made use of in the opening example. + + + + + + + +then group using f + + + With this form of the group statement, f is required to simply have the type + forall a. [a] -> [[a]], which will be used to group up the + comprehension so far directly. An example of this form is as follows: + + +output = [ x +| y <- [1..5] +, x <- "hello" +, then group using inits] + + + This will yield a list containing every prefix of the word "hello" written out 5 times: + + +["","h","he","hel","hell","hello","helloh","hellohe","hellohel","hellohell","hellohello","hellohelloh",...] + + + + + + @@ -1125,7 +1296,7 @@ This name is not supported by GHC. In all cases (apart from arrow notation), the static semantics should be that of the desugared form, -even if that is a little unexpected. For emample, the +even if that is a little unexpected. For example, the static semantics of the literal 368 is exactly that of fromInteger (368::Integer); it's fine for fromInteger to have any of the types: @@ -1366,11 +1537,12 @@ For example, in a let, it applies in the right-hand sides of other let-bindings and the body of the letC. Or, in recursive do expressions (), the local fixity -declarations of aA let statement scope over other +declarations of a let statement scope over other statements in the group, just as the bound name does. -Moreover, a local fixity declatation *must* accompany a local binding of + +Moreover, a local fixity declaration *must* accompany a local binding of that name: it is not possible to revise the fixity of name bound elsewhere, as in @@ -1379,6 +1551,7 @@ let infixr 9 $ in ... Because local fixity declarations are technically Haskell 98, no flag is necessary to enable them. + @@ -1658,7 +1831,7 @@ apply fn to val to get a boolean. For e -What this allows us to do is to package heterogenous values +What this allows us to do is to package heterogeneous values together with a bunch of functions that manipulate them, and then treat that collection of packages in a uniform manner. You can express quite a bit of object-oriented-like programming this way. @@ -2039,9 +2212,9 @@ like this: data NumInst a = Num a => MkNumInst (NumInst a) -Notice that, unlike the situation when declaring an existental, there is +Notice that, unlike the situation when declaring an existential, there is no forall, because the Num constrains the -data type's univerally quantified type variable a. +data type's universally quantified type variable a. A constructor may have both universal and existential type variables: for example, the following two declarations are equivalent: @@ -2233,14 +2406,14 @@ the result type of the case expression. Hence the addition < These and many other examples are given in papers by Hongwei Xi, and Tim Sheard. There is a longer introduction -on the wiki, +on the wiki, and Ralf Hinze's Fun with phantom types also has a number of examples. Note that papers may use different notation to that implemented in GHC. The rest of this section outlines the extensions to GHC that support GADTs. The extension is enabled with -. +. The flag also sets . A GADT can only be declared using GADT-style syntax (); @@ -2609,8 +2782,8 @@ the standard method is used or the one described here.) This section, and the next one, documents GHC's type-class extensions. There's lots of background in the paper Type -classes: exploring the design space (Simon Peyton Jones, Mark +url="http://research.microsoft.com/~simonpj/Papers/type-class-design-space/">Type +classes: exploring the design space (Simon Peyton Jones, Mark Jones, Erik Meijer). @@ -2701,7 +2874,7 @@ GHC lifts this restriction (flag ). 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, . @@ -3401,7 +3574,7 @@ instance of Num or of IsString< -The standard defaulting rule (Haskell Report, Section 4.3.4) +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. @@ -3477,8 +3650,8 @@ in GHC, you can give the foralls if you want. See a is "reachable" if it appears +in the same constraint as either a type variable free in type, or another reachable type variable. A value with a type that does not obey this reachability restriction cannot be used without introducing @@ -4081,7 +4254,7 @@ it has rank-2 types on the left of a function arrow. GHC has three flags to control higher-rank types: - : data constructors (only) can have polymorphic argment types. + : data constructors (only) can have polymorphic argument types. : any function (including data constructors) can have a rank-2 type. @@ -4341,7 +4514,9 @@ for rank-2 types. Impredicative polymorphism -GHC supports impredicative polymorphism. This means +GHC supports impredicative polymorphism, +enabled with . +This means that you can call a polymorphic function at a polymorphic type, and parameterise data structures over polymorphic types. For example: @@ -4382,7 +4557,7 @@ a type for ys; a major benefit of scoped type variables is th it becomes possible to do so. Lexically-scoped type variables are enabled by -. +. This flag implies . Note: GHC 6.6 contains substantial changes to the way that scoped type variables work, compared to earlier releases. Read this section @@ -4417,9 +4592,9 @@ A lexically scoped type variable can be bound by: In Haskell, a programmer-written type signature is implicitly quantified over its free type variables (Section +url="http://www.haskell.org/onlinereport/decls.html#sect4.1.2">Section 4.1.2 -of the Haskel Report). +of the Haskell Report). Lexically scoped type variables affect this implicit quantification rules as follows: any type variable that is in scope is not universally quantified. For example, if type variable a is in scope, @@ -4440,7 +4615,7 @@ then 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: +type variables, in the definition of the named function. For example: f :: forall a. [a] -> [a] f (x:xs) = xs ++ [ x :: a ] @@ -4448,7 +4623,9 @@ type variables, in the definition of the named function(s). For example: The "forall a" brings "a" into scope in the definition of "f". -This only happens if the quantification in f's type +This only happens if: + + The quantification in f's type signature is explicit. For example: g :: [a] -> [a] @@ -4458,6 +4635,26 @@ 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. + + The signature gives a type for a function binding or a bare variable binding, +not a pattern binding. +For example: + + f1 :: forall a. [a] -> [a] + f1 (x:xs) = xs ++ [ x :: a ] -- OK + + f2 :: forall a. [a] -> [a] + f2 = \(x:xs) -> xs ++ [ x :: a ] -- OK + + f3 :: forall a. [a] -> [a] + Just f3 = Just (\(x:xs) -> xs ++ [ x :: a ]) -- Not OK! + +The binding for f3 is a pattern binding, and so its type signature +does not bring a into scope. However f1 is a +function binding, and f2 binds a bare variable; in both cases +the type signature brings a into scope. + + @@ -4495,8 +4692,8 @@ already in scope (i.e. bound by the enclosing context), matters are simple: the signature simply constrains the type of the pattern in the obvious way. -Unlike expression and declaration type signatures, pattern type signatures are not implictly generalised. -The pattern in a patterm binding may only mention type variables +Unlike expression and declaration type signatures, pattern type signatures are not implicitly generalised. +The pattern in a pattern binding may only mention type variables that are already in scope. For example: f :: forall a. [a] -> (Int, [a]) @@ -4635,18 +4832,18 @@ scope over the methods defined in the where part. For exampl The Haskell Report specifies that a group of bindings (at top level, or in a let or where) should be sorted into strongly-connected components, and then type-checked in dependency order -(Haskell +(Haskell Report, Section 4.5.1). As each group is type-checked, any binders of the group that have an explicit type signature are put in the type environment with the specified polymorphic type, and all others are monomorphic until the group is generalised -(Haskell Report, Section 4.5.2). +(Haskell Report, Section 4.5.2). Following a suggestion of Mark Jones, in his paper -Typing Haskell in +Typing Haskell in Haskell, GHC implements a more general scheme. If is specified: @@ -4707,7 +4904,7 @@ Currently, only the former are fully implemented, while we are still working on the latter. As a result, the specification of the language extension is also still to some degree in flux. Hence, a more detailed description of the language extension and its use is currently available -from the Haskell +from the Haskell wiki page on type families. The material will be moved to this user's guide when it has stabilised. @@ -4735,7 +4932,7 @@ Template Meta-programming for Haskell" (Proc Haskell Workshop 2002). There is a Wiki page about -Template Haskell at +Template Haskell at http://www.haskell.org/haskellwiki/Template_Haskell, and that is the best place to look for further details. You may also @@ -4801,6 +4998,15 @@ Wiki page. + A quasi-quotation can appear in either a pattern context or an + expression context and is also written in Oxford brackets: + + [:varid| ... |], + where the "..." is an arbitrary string; a full description of the + quasi-quotation facility is given in . + + + A name can be quoted with either one or two prefix single quotes: 'f has type Name, and names the function f. @@ -4811,14 +5017,14 @@ Wiki page. That is, ''thing interprets thing in a type context. - These Names can be used to construct Template Haskell expressions, patterns, delarations etc. They + These Names can be used to construct Template Haskell expressions, patterns, declarations etc. They may also be given as an argument to the reify function. -(Compared to the original paper, there are many differnces of detail. +(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. @@ -4840,9 +5046,13 @@ Type splices are not implemented, and neither are pattern splices or quotations. - Furthermore, you can only run a function at compile time if it is imported + You can only run a function at compile time if it is imported from another module that is not part of a mutually-recursive group of modules - that includes the module currently being compiled. For example, when compiling module A, + that includes the module currently being compiled. Furthermore, all of the modules of + the mutually-recursive group must be reachable by non-SOURCE imports from the module where the + splice is to be run. + + For example, when compiling module A, you can only run Template Haskell functions imported from B if B does not import A (directly or indirectly). The reason should be clear: to run B we must compile and run A, but we are currently type-checking A. @@ -4970,6 +5180,124 @@ The basic idea is to compile the program twice: + Template Haskell Quasi-quotation +Quasi-quotation allows patterns and expressions to be written using +programmer-defined concrete syntax; the motivation behind the extension and +several examples are documented in +"Why It's +Nice to be Quoted: Quasiquoting for Haskell" (Proc Haskell Workshop +2007). The example below shows how to write a quasiquoter for a simple +expression language. + + +In the example, the quasiquoter expr is bound to a value of +type Language.Haskell.TH.Quote.QuasiQuoter which contains two +functions for quoting expressions and patterns, respectively. The first argument +to each quoter is the (arbitrary) string enclosed in the Oxford brackets. The +context of the quasi-quotation statement determines which of the two parsers is +called: if the quasi-quotation occurs in an expression context, the expression +parser is called, and if it occurs in a pattern context, the pattern parser is +called. + + +Note that in the example we make use of an antiquoted +variable n, indicated by the syntax 'int:n +(this syntax for anti-quotation was defined by the parser's +author, not by GHC). This binds n to the +integer value argument of the constructor IntExpr when +pattern matching. Please see the referenced paper for further details regarding +anti-quotation as well as the description of a technique that uses SYB to +leverage a single parser of type String -> a to generate both +an expression parser that returns a value of type Q Exp and a +pattern parser that returns a value of type Q Pat. + + +In general, a quasi-quote has the form +[$quoter| string |]. +The quoter must be the name of an imported quoter; it +cannot be an arbitrary expression. The quoted string +can be arbitrary, and may contain newlines. + + +Quasiquoters must obey the same stage restrictions as Template Haskell, e.g., in +the example, expr cannot be defined +in Main.hs where it is used, but must be imported. + + + + +{- Main.hs -} +module Main where + +import Expr + +main :: IO () +main = do { print $ eval [$expr|1 + 2|] + ; case IntExpr 1 of + { [$expr|'int:n|] -> print n + ; _ -> return () + } + } + + +{- Expr.hs -} +module Expr where + +import qualified Language.Haskell.TH as TH +import Language.Haskell.TH.Quasi + +data Expr = IntExpr Integer + | AntiIntExpr String + | BinopExpr BinOp Expr Expr + | AntiExpr String + deriving(Show, Typeable, Data) + +data BinOp = AddOp + | SubOp + | MulOp + | DivOp + deriving(Show, Typeable, Data) + +eval :: Expr -> Integer +eval (IntExpr n) = n +eval (BinopExpr op x y) = (opToFun op) (eval x) (eval y) + where + opToFun AddOp = (+) + opToFun SubOp = (-) + opToFun MulOp = (*) + opToFun DivOp = div + +expr = QuasiQuoter parseExprExp parseExprPat + +-- Parse an Expr, returning its representation as +-- either a Q Exp or a Q Pat. See the referenced paper +-- for how to use SYB to do this by writing a single +-- parser of type String -> Expr instead of two +-- separate parsers. + +parseExprExp :: String -> Q Exp +parseExprExp ... + +parseExprPat :: String -> Q Pat +parseExprPat ... + + +Now run the compiler: + + +$ ghc --make -XQuasiQuotes Main.hs -o main + + +Run "main" and here is your output: + + +$ ./main +3 +1 + + + + @@ -5558,7 +5886,7 @@ prefix notation: (!) f x = 3 The semantics of Haskell pattern matching is described in +url="http://www.haskell.org/onlinereport/exps.html#sect3.17.2"> Section 3.17.2 of the Haskell Report. To this description add one extra item 10, saying: Matching @@ -5568,7 +5896,7 @@ the pattern !pat against a value v behaves v -Similarly, in Figure 4 of +Similarly, in Figure 4 of Section 3.17.3, add a new case (t): case v of { !pat -> e; _ -> e' } @@ -5576,7 +5904,7 @@ case v of { !pat -> e; _ -> e' } That leaves let expressions, whose translation is given in -Section +Section 3.12 of the Haskell Report. In the translation box, first apply @@ -5894,7 +6222,7 @@ key_function :: Int -> String -> (Bool, Double) function "f" has a number of other effects: -No funtions are inlined into f. Otherwise +No functions are inlined into f. Otherwise GHC might inline a big function into f's right hand side, making f big; and then inline f blindly. @@ -5983,7 +6311,7 @@ exactly what you asked for, no more and no less. there was no pragma). - "INLINE[~k] f" means: be willing to inline + "NOINLINE[~k] f" means: be willing to inline f until phase k, but from phase k onwards do not inline it. @@ -6214,14 +6542,14 @@ data T = T {-# UNPACK #-} !(Int,Int) will store the two Ints directly in the T constructor, by flattening the pair. - Multi-level unpacking is also supported: + Multi-level unpacking is also supported: data T = T {-# UNPACK #-} !S data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int - will store two unboxed Int#s + will store two unboxed Int#s directly in the T constructor. The unpacker can see through newtypes, too. @@ -6235,6 +6563,15 @@ data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int constructor field. + + SOURCE pragma + + SOURCE + The {-# SOURCE #-} pragma is used only in import declarations, + to break a module loop. It is described in detail in . + + + @@ -6250,7 +6587,7 @@ data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int The programmer can specify rewrite rules as part of the source program (in a pragma). GHC applies these rewrite rules wherever it can, provided (a) the flag () is on, -and (b) the flag +and (b) the flag () is not specified, and (c) the () flag is active. @@ -6859,7 +7196,7 @@ g x = show x - However, when external for is generated (via + However, when external core is generated (via ), there will be Notes attached to the expressions show and x. The core function declaration for f is: @@ -7171,7 +7508,7 @@ carried out at let and where bindings. Haskell's monomorphism restriction (see -Section +Section 4.5.5 of the Haskell Report) can be completely switched off by @@ -7210,6 +7547,7 @@ standard behaviour. ;;; Local Variables: *** ;;; mode: xml *** ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** + ;;; ispell-local-dictionary: "british" *** ;;; End: *** -->