X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=da6a125eb4a6cf30872ec2ee74d608eb19e8b203;hb=f81df3c6e23b8d7d02eacca3d40974a45c7eb6d6;hp=4d9a9773f88cd5075148b56a5166bea7d0e1889d;hpb=d9236c265896d65ae4f1d4f4a240d8c0ffbce6f3;p=ghc-hetmet.git diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml index 4d9a977..da6a125 100644 --- a/docs/users_guide/glasgow_exts.xml +++ b/docs/users_guide/glasgow_exts.xml @@ -1916,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> @@ -1932,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. @@ -1986,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) @@ -2032,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. @@ -2148,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 @@ -2940,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 @@ -4155,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 @@ -4275,24 +4322,27 @@ Template Meta-programming for Haskell" (Proc Haskell Workshop 2002). There is a Wiki page about Template Haskell at -http://www.haskell.org/th/, and that is the best place to look for +http://www.haskell.org/haskellwiki/Template_Haskell, and that is the best place to look for further details. You may also consult the online Haskell library reference material -(search for the type ExpQ). -[Temporary: many changes to the original design are described in - "http://research.microsoft.com/~simonpj/tmp/notes2.ps". -Not all of these changes are in GHC 6.6.] +(look for module Language.Haskell.TH). +Many changes to the original design are described in + +Notes on Template Haskell version 2. +Not all of these changes are in GHC, however. - The first example from that paper is set out below as a worked example to help get you started. + The first example from that paper is set out below () +as a worked example to help get you started. -The documentation here describes the realisation in GHC. (It's rather sketchy just now; -Tim Sheard is going to expand it.) +The documentation here describes the realisation of Template Haskell in GHC. It is not detailed enough to +understand Template Haskell; see the +Wiki page. @@ -4318,41 +4368,47 @@ Tim Sheard is going to expand it.) an expression; the spliced expression must have type Q Exp - a list of top-level declarations; ; the spliced expression must have type Q [Dec] - [Planned, but not implemented yet.] a - type; the spliced expression must have type Q Typ. + a list of top-level declarations; the spliced expression must have type Q [Dec] - (Note that the syntax for a declaration splice uses "$" not "splice" as in - the paper. Also the type of the enclosed expression must be Q [Dec], not [Q Dec] - as in the paper.) - + + Inside a splice you can can only call functions defined in imported modules, + not functions defined elsewhere in the same module. A expression quotation is written in Oxford brackets, thus: [| ... |], where the "..." is an expression; - the quotation has type Expr. + the quotation has type Q Exp. [d| ... |], where the "..." is a list of top-level declarations; the quotation has type Q [Dec]. [t| ... |], where the "..." is a type; - the quotation has type Type. + the quotation has type Q Typ. - Reification is written thus: + A name can be quoted with either one or two prefix single quotes: - reifyDecl T, where T is a type constructor; this expression - has type Dec. - reifyDecl C, where C is a class; has type Dec. - reifyType f, where f is an identifier; has type Typ. - Still to come: fixities - - + 'f has type Name, and names the function f. + Similarly 'C has type Name and names the data constructor C. + In general 'thing interprets thing in an expression context. + + ''T has type Name, and names the type constructor T. + That is, ''thing interprets thing in a type context. + + + These Names can be used to construct Template Haskell expressions, patterns, delarations etc. They + may also be given as an argument to the reify function. + +(Compared to the original paper, there are many differnces 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. + Using Template Haskell @@ -4395,7 +4451,7 @@ Tim Sheard is going to expand it.) - A Template Haskell Worked Example + A Template Haskell Worked Example To help you get over the confidence barrier, try out this skeletal worked example. First cut and paste the two modules below into "Main.hs" and "Printf.hs": @@ -4435,15 +4491,15 @@ parse s = [ L s ] -- Generate Haskell source code from a parsed representation -- of the format string. This code will be spliced into -- the module which calls "pr", at compile time. -gen :: [Format] -> ExpQ +gen :: [Format] -> Q Exp gen [D] = [| \n -> show n |] gen [S] = [| \s -> s |] gen [L s] = stringE s -- Here we generate the Haskell code for the splice -- from an input format string. -pr :: String -> ExpQ -pr s = gen (parse s) +pr :: String -> Q Exp +pr s = gen (parse s) Now run the compiler (here we are a Cygwin prompt on Windows):