X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=ba18faf1403e2a895bf238cd693f7a02cd875998;hb=b2020bada0e177105bf0fd3259850b9d645f1995;hp=5a4c46584a729c96406e4eda390f111fc4bb2f97;hpb=9d1247b3dad4fe152503dafa995fa06428e1a04b;p=ghc-hetmet.git
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 5a4c465..ba18faf 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -52,263 +52,27 @@ documentation describes all the libraries that come with GHC.
Language options recognised by Cabal can also be enabled using the LANGUAGE pragma,
thus {-# LANGUAGE TemplateHaskell #-} (see >).
- Turning on an option that enables special syntax
- might cause working Haskell 98 code to fail
- to compile, perhaps because it uses a variable name which has
- become a reserved word. So, together with each option below, we
- list the special syntax which is enabled by this option. We use
- notation and nonterminal names from the Haskell 98 lexical syntax
- (see the Haskell 98 Report). There are two classes of special
- syntax:
-
-
-
- New reserved words and symbols: character sequences
- which are no longer available for use as identifiers in the
- program.
-
-
- Other special syntax: sequences of characters that have
- a different meaning when this particular option is turned
- on.
-
-
-
- We are only listing syntax changes here that might affect
- existing working programs (i.e. "stolen" syntax). Many of these
- extensions will also enable new context-free syntax, but in all
- cases programs written to use the new syntax would not be
- compilable without the option enabled.
-
-
-
-
-
- :
+ The flag :
-
-
- This simultaneously enables all of the extensions to
- Haskell 98 described in , except where otherwise
- noted. We are trying to move away from this portmanteau flag,
- and towards enabling features individually.
-
- New reserved words: forall (only in
- types), mdo.
-
- Other syntax stolen:
- varid{#},
- char#,
- string#,
- integer#,
- float#,
- float##,
- (#, #),
- |), {|.
-
- Implies these specific language options:
+ simultaneously enables the following extensions:
,
,
,
,
- .
-
-
-
-
-
- :
-
-
-
- This option enables the language extension defined in the
- Haskell 98 Foreign Function Interface Addendum.
-
- New reserved words: foreign.
-
-
-
-
-
- ,:
-
-
- These two flags control how generalisation is done.
- See .
-
-
-
-
-
-
- :
-
-
-
- Use GHCi's extended default rules in a regular module ().
- Independent of the
- flag.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- See . Only relevant
- if you also use .
-
-
-
-
-
-
-
-
-
- See . Only relevant if
- you also use .
-
-
-
-
-
-
-
-
-
- See . Independent of
- .
-
- New reserved words/symbols: rec,
- proc, -<,
- >-, -<<,
- >>-.
-
- Other syntax stolen: (|,
- |).
-
-
-
-
-
-
-
-
-
- See . Independent of
- .
-
-
-
-
-
-
- -XNoImplicitPrelude
- option GHC normally imports
- Prelude.hi files for you. If you'd
- rather it didn't, then give it a
- option. The idea is
- that you can then import a Prelude of your own. (But don't
- call it Prelude; the Haskell module
- namespace is flat, and you must not conflict with any
- Prelude module.)
-
- 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]
- still means Prelude.[] Int; tuples
- continue to refer to the standard Prelude tuples; the
- translation for list comprehensions continues to use
- Prelude.map etc.
-
- However, does
- change the handling of certain built-in syntax: see .
-
-
-
-
-
-
- Enables implicit parameters (see ). Currently also implied by
- .
-
- Syntax stolen:
- ?varid,
- %varid.
-
-
-
-
-
-
- Enables overloaded string literals (see ).
-
-
-
-
-
-
- Enables lexically-scoped type variables (see ). Implied by
- .
-
-
-
-
-
-
- Enables Template Haskell (see ). This flag must
- be given explicitly; it is no longer implied by
- .
-
- Syntax stolen: [|,
- [e|, [p|,
- [d|, [t|,
- $(,
- $varid.
-
-
-
-
-
-
- Enables quasiquotation (see ).
-
- Syntax stolen:
- [:varid|.
-
-
+ .
+ Enabling these options is the only
+ effect of -fglasgow-exts
+ We are trying to move away from this portmanteau flag,
+ and towards enabling features individually.
- Unboxed types and primitive operations
-GHC is built on a raft of primitive data types and operations.
+GHC is built on a raft of primitive data types and operations;
+"primitive" in the sense that they cannot be defined in Haskell itself.
While you really can use this stuff to write fast code,
we generally find it a lot less painful, and more satisfying in the
long run, to use higher-level language features and libraries. With
@@ -316,28 +80,21 @@ While you really can use this stuff to write fast code,
unboxed version in any case. And if it isn't, we'd like to know
about it.
-We do not currently have good, up-to-date documentation about the
-primitives, perhaps because they are mainly intended for internal use.
-There used to be a long section about them here in the User Guide, but it
-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
-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.
-
-Indeed,
-the result of such processing is part of the description of the
- 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 XML
-back end to the program that processes primops.txt so that
-we could include the results here in the User Guide.
-
-What follows here is a brief summary of some main points.
+All these primitive data types and operations are exported by the
+library GHC.Prim, for which there is
+detailed online documentation.
+(This documentation is generated from the file compiler/prelude/primops.txt.pp.)
+
+
+If you want to mention any of the primitive data types or operations in your
+program, you must first import GHC.Prim to bring them
+into scope. Many of them have names ending in "#", and to mention such
+names you need the extension ().
+
+
+The primops make extensive use of unboxed types
+and unboxed tuples, which
+we briefly summarise here. Unboxed types
@@ -366,26 +123,15 @@ would use in C: Int# (long int),
know and love—usually one instruction.
- For some primitive types we have special syntax for literals.
-Anything that would be an integer lexeme followed by a
-# is an Int# literal, e.g.
-32# and -0x3A#. Likewise,
-any non-negative integer literal followed by
-## is a Word# literal.
-Likewise, any floating point literal followed by a
-# is a Float# literal, and
-followed by ## is a
-Double#. Finally, a string literal followed by a
-#, e.g. "foo"#,
-is a Addr# literal.
-
-
Primitive (unboxed) types cannot be defined in Haskell, and are
therefore built into the language and compiler. Primitive types are
always unlifted; that is, a value of a primitive type cannot be
-bottom. We use the convention that primitive types, values, and
-operations have a # suffix.
+bottom. We use the convention (but it is only a convention)
+that primitive types, values, and
+operations have a # suffix (see ).
+For some primitive types we have special syntax for literals, also
+described in the same section.
@@ -562,8 +308,40 @@ Indeed, the bindings can even be recursive.
Syntactic extensions
+
+ The magic hash
+ The language extension allows "#" as a
+ postfix modifier to identifiers. Thus, "x#" is a valid variable, and "T#" is
+ a valid type constructor or data constructor.
+
+ The hash sign does not change sematics at all. We tend to use variable
+ names ending in "#" for unboxed values or types (e.g. Int#),
+ but there is no requirement to do so; they are just plain ordinary variables.
+ Nor does the extension bring anything into scope.
+ For example, to bring Int# into scope you must
+ import GHC.Prim (see );
+ the extension
+ then allows you to refer to the Int#
+ that is now in scope.
+ The also enables some new forms of literals (see ):
+
+ 'x'# has type Char#
+ "foo"# has type Addr#
+ 3# has type Int#. In general,
+ any Haskell 98 integer lexeme followed by a # is an Int# literal, e.g.
+ -0x3A# as well as 32#.
+ 3## has type Word#. In general,
+ any non-negative Haskell 98 integer lexeme followed by ##
+ is a Word#.
+ 3.2# has type Float#.
+ 3.2## has type Double#
+
+
+
+
+
Hierarchical Modules
@@ -1247,21 +1025,28 @@ output = [ x
-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
+Rebindable syntax and the implicit Prelude import
+
+ -XNoImplicitPrelude
+ option GHC normally imports
+ Prelude.hi files for you. If you'd
+ rather it didn't, then give it a
+ option. The idea is
+ that you can then import a Prelude of your own. (But don't
+ call it Prelude; the Haskell module
+ namespace is flat, and you must not conflict with any
+ Prelude module.)
+
+ Suppose you are importing a Prelude of your own
+ in order 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
+ So the
+ flag also causes
the following pieces of built-in syntax to refer to
whatever is in scope, not the Prelude
versions:
-
An integer literal 368 means
@@ -1410,7 +1195,7 @@ records from different modules that use the same field name.
-Record puns are enabled by the flag -XRecordPuns.
+Record puns are enabled by the flag -XNamedFieldPuns.
@@ -1568,6 +1353,167 @@ necessary to enable them.
+
+ Package-qualified imports
+
+ With the flag, GHC allows
+ import declarations to be qualified by the package name that the
+ module is intended to be imported from. For example:
+
+
+import "network" Network.Socket
+
+
+ would import the module Network.Socket from
+ the package network (any version). This may
+ be used to disambiguate an import when the same module is
+ available from multiple packages, or is present in both the
+ current package being built and an external package.
+
+ Note: you probably don't need to use this feature, it was
+ added mainly so that we can build backwards-compatible versions of
+ packages when APIs change. It can lead to fragile dependencies in
+ the common case: modules occasionally move from one package to
+ another, rendering any package-qualified imports broken.
+
+
+
+Summary of stolen syntax
+
+ Turning on an option that enables special syntax
+ might cause working Haskell 98 code to fail
+ to compile, perhaps because it uses a variable name which has
+ become a reserved word. This section lists the syntax that is
+ "stolen" by language extensions.
+ We use
+ notation and nonterminal names from the Haskell 98 lexical syntax
+ (see the Haskell 98 Report).
+ We only list syntax changes here that might affect
+ existing working programs (i.e. "stolen" syntax). Many of these
+ extensions will also enable new context-free syntax, but in all
+ cases programs written to use the new syntax would not be
+ compilable without the option enabled.
+
+There are two classes of special
+ syntax:
+
+
+
+ New reserved words and symbols: character sequences
+ which are no longer available for use as identifiers in the
+ program.
+
+
+ Other special syntax: sequences of characters that have
+ a different meaning when this particular option is turned
+ on.
+
+
+
+The following syntax is stolen:
+
+
+
+
+ forall
+ forall
+
+
+ Stolen (in types) by: ,
+ ,
+ ,
+ ,
+ ,
+
+
+
+
+
+
+ mdo
+ mdo
+
+
+ Stolen by: ,
+
+
+
+
+
+ foreign
+ foreign
+
+
+ Stolen by: ,
+
+
+
+
+
+ rec,
+ proc, -<,
+ >-, -<<,
+ >>-, and (|,
+ |) brackets
+ proc
+
+
+ Stolen by: ,
+
+
+
+
+
+ ?varid,
+ %varid
+ implicit parameters
+
+
+ Stolen by: ,
+
+
+
+
+
+ [|,
+ [e|, [p|,
+ [d|, [t|,
+ $(,
+ $varid
+ Template Haskell
+
+
+ Stolen by: ,
+
+
+
+
+
+ [:varid|
+ quasi-quotation
+
+
+ Stolen by: ,
+
+
+
+
+
+ varid{#},
+ char#,
+ string#,
+ integer#,
+ float#,
+ float##,
+ (#, #),
+
+
+ Stolen by: ,
+
+
+
+
+
@@ -1668,9 +1614,12 @@ to be written infix, very much like expressions. More specifically:
Liberalised type synonyms
-Type synonyms are like macros at the type level, and
+Type synonyms are like macros at the type level, but Haskell 98 imposes many rules
+on individual synonym declarations.
+With the extension,
GHC does validity checking on types only after expanding type synonyms.
-That means that GHC can be very much more liberal about type synonyms than Haskell 98:
+That means that GHC can be very much more liberal about type synonyms than Haskell 98.
+
You can write a forall (including overloading)
in a type synonym, thus:
@@ -1687,7 +1636,8 @@ in a type synonym, thus:
-You can write an unboxed tuple in a type synonym:
+If you also use ,
+you can write an unboxed tuple in a type synonym:
type Pr = (# Int, Int #)
@@ -2436,11 +2386,17 @@ The result type of each constructor must begin with the type constructor being d
but for a GADT the arguments to the type constructor can be arbitrary monotypes.
For example, in the Term data
type above, the type of each constructor must end with Term ty, but
-the ty may not be a type variable (e.g. the Lit
+the ty need not be a type variable (e.g. the Lit
constructor).
+It's is permitted to declare an ordinary algebraic data type using GADT-style syntax.
+What makes a GADT into a GADT is not the syntax, but rather the presence of data constructors
+whose result type is not just T a b.
+
+
+
You cannot use a deriving clause for a GADT; only for
an ordinary data type.
@@ -2476,6 +2432,23 @@ their selector functions actually have different types:
+
+When pattern-matching against data constructors drawn from a GADT,
+for example in a case expression, the following rules apply:
+
+The type of the scrutinee must be rigid.
+The type of the entire case expression must be rigid.
+The type of any free variable mentioned in any of
+the case alternatives must be rigid.
+
+A type is "rigid" if it is completely known to the compiler at its binding site. The easiest
+way to ensure that a variable a rigid type is to give it a type signature.
+For more precise details see
+Simple unification-based type inference for GADTs
+. The criteria implemented by GHC are given in the Appendix.
+
+
+
@@ -2533,9 +2506,27 @@ The syntax is identical to that of an ordinary instance declaration apart from (
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 .
+attached to a data type declaration.)
+
+A deriving instance declaration
+must obey the same rules concerning form and termination as ordinary instance declarations,
+controlled by the same flags; see .
+
+
+Unlike a deriving
+declaration attached to a data declaration, the instance can be more specific
+than the data type (assuming you also use
+-XFlexibleInstances, ). Consider
+for example
+
+ data Foo a = Bar a | Baz String
+
+ deriving instance Eq a => Eq (Foo [a])
+ deriving instance Eq a => Eq (Foo (Maybe a))
+
+This will generate a derived instance for (Foo [a]) and (Foo (Maybe a)),
+but other types such as (Foo (Int,Bool)) will not be an instance of Eq.
+The stand-alone syntax is generalised for newtypes in exactly the same
way that ordinary deriving clauses are generalised ().
@@ -3251,7 +3242,7 @@ corresponding type in the instance declaration.
These restrictions ensure that context reduction terminates: each reduction
step makes the problem smaller by at least one
constructor. Both the Paterson Conditions and the Coverage Condition are lifted
-if you give the
+if you give the
flag ().
You can find lots of background material about the reason for these
restrictions in the paper f, so GHC had to
check that f has the specified type.
Suppose instead we do not give a type signature, asking GHC to infer
it instead. In this case, GHC will refrain from
-simplifying the constraint C Int [Int] (for the same reason
+simplifying the constraint C Int [b] (for the same reason
as before) but, rather than rejecting the program, it will infer the type
- f :: C Int b => [b] -> [b]
+ f :: C Int [b] => [b] -> [b]
That postpones the question of which instance to pick to the
call site for f
by which time more is known about the type b.
+You can write this type signature yourself if you use the
+
+flag.
+
+
+Exactly the same situation can arise in instance declarations themselves. Suppose we have
+
+ class Foo a where
+ f :: a -> a
+ instance Foo [b] where
+ f x = ...
+
+and, as before, the constraint C Int [b] arises from f's
+right hand side. GHC will reject the instance, complaining as before that it does not know how to resolve
+the constraint C Int [b], because it matches more than one instance
+declaration. The solution is to postpone the choice by adding the constraint to the context
+of the instance declaration, thus:
+
+ instance C Int [b] => Foo [b] where
+ f x = ...
+
+(You need to do this.)
The willingness to be overlapped or incoherent is a property of
@@ -3631,9 +3644,11 @@ to work since it gets translated into an equality comparison.
The context of a type signature
-Unlike Haskell 98, constraints in types do not have to be of
-the form (class type-variable) or
-(class (type-variable type-variable ...)). Thus,
+The flag lifts the Haskell 98 restriction
+that the type-class constraints in a type signature must have the
+form (class type-variable) or
+(class (type-variable type-variable ...)).
+With
these type signatures are perfectly OK
g :: Eq [a] => ...
@@ -5329,6 +5344,8 @@ For more details, see
“Generalising Monads to Arrows”,
John Hughes, in Science of Computer Programming 37,
pp67–111, May 2000.
+The paper that introduced arrows: a friendly introduction, motivated with
+programming examples.
@@ -5336,6 +5353,7 @@ pp67–111, May 2000.
“A New Notation for Arrows”,
Ross Paterson, in ICFP, Sep 2001.
+Introduced the notation described here.
@@ -5347,17 +5365,42 @@ Palgrave, 2003.
-
-and the arrows web page at
+
+
+“Programming with Arrows”,
+John Hughes, in 5th International Summer School on
+Advanced Functional Programming,
+Lecture Notes in Computer Science vol. 3622,
+Springer, 2004.
+This paper includes another introduction to the notation,
+with practical examples.
+
+
+
+
+
+“Type and Translation Rules for Arrow Notation in GHC”,
+Ross Paterson and Simon Peyton Jones, September 16, 2004.
+A terse enumeration of the formal rules used
+(extracted from comments in the source code).
+
+
+
+
+
+The arrows web page at
http://www.haskell.org/arrows/.
+
+
+
+
With the flag, GHC supports the arrow
-notation described in the second of these papers.
-What follows is a brief introduction to the notation;
-it won't make much sense unless you've read Hughes's paper.
-This notation is translated to ordinary Haskell,
-using combinators from the
+notation described in the second of these papers,
+translating it using combinators from the
Control.Arrow
module.
+What follows is a brief introduction to the notation;
+it won't make much sense unless you've read Hughes's paper.
The extension adds a new kind of expression for defining arrows:
@@ -5631,7 +5674,8 @@ We could define our own operator
untilA :: ArrowChoice a => a e () -> a e Bool -> a e ()
untilA body cond = proc x ->
- if cond x then returnA -< ()
+ b <- cond -< x
+ if b then returnA -< ()
else do
body -< x
untilA body cond -< x
@@ -6144,56 +6188,63 @@ Assertion failures can be caught, see the documentation for the
don't recommend using this approach with GHC.
-
- DEPRECATED pragma
- DEPRECATED
-
+
+ WARNING and DEPRECATED pragmas
+ WARNING
+ DEPRECATED
- The DEPRECATED pragma lets you specify that a particular
- function, class, or type, is deprecated. There are two
- forms.
+ The WARNING pragma allows you to attach an arbitrary warning
+ to a particular function, class, or type.
+ A DEPRECATED pragma lets you specify that
+ a particular function, class, or type is deprecated.
+ There are two ways of using these pragmas.
- You can deprecate an entire module thus:
+ You can work on an entire module thus:
module Wibble {-# DEPRECATED "Use Wobble instead" #-} where
...
+ Or:
+
+ module Wibble {-# WARNING "This is an unstable interface." #-} where
+ ...
+When you compile any module that import
Wibble, GHC will print the specified
message.
- You can deprecate a function, class, type, or data constructor, with the
- following top-level declaration:
+ You can attach a warning to a function, class, type, or data constructor, with the
+ following top-level declarations:
{-# DEPRECATED f, C, T "Don't use these" #-}
+ {-# WARNING unsafePerformIO "This is unsafe; I hope you know what you're doing" #-}
When you compile any module that imports and uses any
of the specified entities, GHC will print the specified
message.
- You can only deprecate entities declared at top level in the module
+ You can only attach to entities declared at top level in the module
being compiled, and you can only use unqualified names in the list of
- entities being deprecated. A capitalised name, such as T
+ entities. A capitalised name, such as T
refers to either the type constructor Tor the data constructor T, or both if
- both are in scope. If both are in scope, there is currently no way to deprecate
- one without the other (c.f. fixities ).
+ both are in scope. If both are in scope, there is currently no way to
+ specify one without the other (c.f. fixities
+ ).
- Any use of the deprecated item, or of anything from a deprecated
- module, will be flagged with an appropriate message. However,
- deprecations are not reported for
- (a) uses of a deprecated function within its defining module, and
- (b) uses of a deprecated function in an export list.
+ Warnings and deprecations are not reported for
+ (a) uses within the defining module, and
+ (b) uses in an export list.
The latter reduces spurious complaints within a library
in which one module gathers together and re-exports
the exports of several others.
You can suppress the warnings with the flag
- .
+ .
@@ -6607,15 +6658,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
-() is not specified, and (c) the
- ()
-flag is active.
-
-
-
+(in a pragma).
Here is an example:
@@ -6735,17 +6778,40 @@ variables it mentions, though of course they need to be in scope.
- Rules are automatically exported from a module, just as instance declarations are.
+ All rules are implicitly exported from the module, and are therefore
+in force in any module that imports the module that defined the rule, directly
+or indirectly. (That is, if A imports B, which imports C, then C's rules are
+in force when compiling A.) The situation is very similar to that for instance
+declarations.
+
+
+
+Inside a RULE "forall" is treated as a keyword, regardless of
+any other flag settings. Furthermore, inside a RULE, the language extension
+ is automatically enabled; see
+.
+
+
+
+
+
+Like other pragmas, RULE pragmas are always checked for scope errors, and
+are typechecked. Typechecking means that the LHS and RHS of a rule are typechecked,
+and must have the same type. However, rules are only enabled
+if the flag is
+on (see ).
+
+
-
+Semantics
@@ -6753,9 +6819,17 @@ From a semantic point of view:
-
-Rules are only applied if you use the flag.
+Rules are enabled (that is, used during optimisation)
+by the flag.
+This flag is implied by , and may be switched
+off (as usual) by .
+(NB: enabling without
+may not do what you expect, though, because without GHC
+ignores all optimisation information in interface files;
+see , .)
+Note that is an optimisation flag, and
+has no effect on parsing or typechecking.
@@ -6772,14 +6846,6 @@ expression by substituting for the pattern variables.
- The LHS and RHS of a rule are typechecked, and must have the
-same type.
-
-
-
-
-
-
GHC makes absolutely no attempt to verify that the LHS and RHS
of a rule have the same meaning. That is undecidable in general, and
infeasible in most interesting cases. The responsibility is entirely the programmer's!
@@ -6872,17 +6938,6 @@ pragma on f, to ensure
that it is not inlined until its RULEs have had a chance to fire.
-
-
-
- All rules are implicitly exported from the module, and are therefore
-in force in any module that imports the module that defined the rule, directly
-or indirectly. (That is, if A imports B, which imports C, then C's rules are
-in force when compiling A.) The situation is very similar to that for instance
-declarations.
-
-
-