X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=9ea3332463d109f0aa2f22a185701c66147837d0;hb=11b33eaeaef39fcba8ee9258213068ed90362aa7;hp=161371b8c3ed65b5e109d83212444a9578ea77ff;hpb=92b30c6bd5123897b154aa158a0cd05b8b76f67a;p=ghc-hetmet.git
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 161371b..9ea3332 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -3,8 +3,9 @@
language, GHCextensions, GHC
As with all known Haskell systems, GHC implements some extensions to
-the language. They are all enabled by options; by default GHC
-understands only plain Haskell 98.
+the language. They can all be enabled or disabled by commandline flags
+or language pragmas. By default GHC understands the most recent Haskell
+version it supports, plus a handful of extensions.
@@ -39,8 +40,7 @@ documentation describes all the libraries that come with GHC.
The language option flags control what variation of the language are
- permitted. Leaving out all of them gives you standard Haskell
- 98.
+ permitted.Language options can be controlled in two ways:
@@ -439,10 +439,10 @@ Indeed, the bindings can even be recursive.
'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.
+ any Haskell 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 ##
+ any non-negative Haskell integer lexeme followed by ##
is a Word#. 3.2# has type Float#.3.2## has type Double#
@@ -450,43 +450,6 @@ Indeed, the bindings can even be recursive.
-
- New qualified operator syntax
-
- A new syntax for referencing qualified operators is
- planned to be introduced by Haskell', and is enabled in GHC
- with
- the
- option. In the new syntax, the prefix form of a qualified
- operator is
- written module.(symbol)
- (in Haskell 98 this would
- be (module.symbol)),
- and the infix form is
- written `module.(symbol)`
- (in Haskell 98 this would
- be `module.symbol`.
- For example:
-
- add x y = Prelude.(+) x y
- subtract y = (`Prelude.(-)` y)
-
- The new form of qualified operators is intended to regularise
- the syntax by eliminating odd cases
- like Prelude... For example,
- when NewQualifiedOperators is on, it is possible to
- write the enumerated sequence [Monday..]
- without spaces, whereas in Haskell 98 this would be a
- reference to the operator ‘.‘
- from module Monday.
-
- When is on, the old Haskell
- 98 syntax for qualified operators is not accepted, so this
- option may cause existing Haskell 98 code to break.
-
-
-
-
@@ -2471,7 +2434,8 @@ declarations. Define your own instances!
Declaring data types with explicit constructor signatures
-GHC allows you to declare an algebraic data type by
+When the GADTSyntax extension is enabled,
+GHC allows you to declare an algebraic data type by
giving the type signatures of constructors explicitly. For example:
data Maybe a where
@@ -4041,18 +4005,21 @@ The willingness to be overlapped or incoherent is a property of
the instance declaration itself, controlled by the
presence or otherwise of the
and flags when that module is
-being defined. Neither flag is required in a module that imports and uses the
-instance declaration. Specifically, during the lookup process:
+being defined. Specifically, during the lookup process:
-An instance declaration is ignored during the lookup process if (a) a more specific
-match is found, and (b) the instance declaration was compiled with
-. The flag setting for the
-more-specific instance does not matter.
+If the constraint being looked up matches two instance declarations IA and IB,
+and
+
+IB is a substitution instance of IA (but not vice versa);
+that is, IB is strictly more specific than IA
+either IA or IB was compiled with
+
+then the less-specific instance IA is ignored.
Suppose an instance declaration does not match the constraint being looked up, but
-does unify with it, so that it might match when the constraint is further
+does unify with it, so that it might match when the constraint is further
instantiated. Usually GHC will regard this as a reason for not committing to
some other constraint. But if the instance declaration was compiled with
, GHC will skip the "does-it-unify?"
@@ -4062,18 +4029,6 @@ check for that declaration.
These rules make it possible for a library author to design a library that relies on
overlapping instances without the library client having to know.
-
-If an instance declaration is compiled without
-,
-then that instance can never be overlapped. This could perhaps be
-inconvenient. Perhaps the rule should instead say that the
-overlapping instance declaration should be compiled in
-this way, rather than the overlapped one. Perhaps overlap
-at a usage site should be permitted regardless of how the instance declarations
-are compiled, if the flag is
-used at the usage site. (Mind you, the exact usage site can occasionally be
-hard to pin down.) We are interested to receive feedback on these points.
-The flag implies the
flag, but not vice versa.
@@ -5771,9 +5726,6 @@ for rank-2 types.
Impredicative polymorphism
-NOTE: the impredicative-polymorphism feature is deprecated in GHC 6.12, and
-will be removed or replaced in GHC 6.14.
-
GHC supports impredicative polymorphism,
enabled with .
This means
@@ -5896,7 +5848,7 @@ signature is explicit. For example:
g (x:xs) = xs ++ [ x :: a ]
This program will be rejected, because "a" does not scope
-over the definition of "f", so "x::a"
+over the definition of "g", so "x::a"
means "x::forall a. a" by Haskell's usual implicit
quantification rules.
@@ -5932,7 +5884,7 @@ type variables, in the annotated expression. For example:
f = runST ( (op >>= \(x :: STRef s Int) -> g x) :: forall s. ST s Bool )
-Here, the type signature forall a. ST s Bool brings the
+Here, the type signature forall s. ST s Bool brings the
type variable s into scope, in the annotated expression
(op >>= \(x :: STRef s Int) -> g x).
@@ -7712,27 +7664,48 @@ itself, so an INLINE pragma is always ignored.
INLINABLE pragma
-An INLINABLE pragma works very like an INLINE pragma, except that:
+An {-# INLINABLE f #-} pragma on a
+function f has the following behaviour:
-INLINE says "please inline me", but INLINABLE says "feel free to inline me; use your
+While INLINE says "please inline me", the INLINABLE
+says "feel free to inline me; use your
discretion". In other words the choice is left to GHC, which uses the same
-rules as for pragma-free functions. Unlike INLINE, That decision is made at
+rules as for pragma-free functions. Unlike INLINE, that decision is made at
the call site, and
will therefore be affected by the inlining threshold, optimisation level etc.
-Like INLINE, the INLINABLE pragma retains a copy of the original RHS for
+Like INLINE, the INLINABLE pragma retains a
+copy of the original RHS for
inlining purposes, and persists it in the interface file, regardless of
the size of the RHS.
+
-If you use the special function inline ()
-to force inlining at a
-call site, you will get a copy of the the original RHS.
-Indeed, if you intend to use inline f it
-is a good idea to mark the definition of f INLINABLE,
+One way to use INLINABLE is in conjunction with
+the special function inline ().
+The call inline f tries very hard to inline f.
+To make sure that f can be inlined,
+it is a good idea to mark the definition
+of f as INLINABLE,
so that GHC guarantees to expose an unfolding regardless of how big it is.
+Moreover, by annotating f as INLINABLE,
+you ensure that f's original RHS is inlined, rather than
+whatever random optimised version of f GHC's optimiser
+has produced.
+
+
+
+The INLINABLE pragma also works with SPECIALISE:
+if you mark function f as INLINABLE, then
+you can subsequently SPECIALISE in another module
+(see ).
+
+
+Unlike INLINE, it is OK to use
+an INLINABLE pragma on a recursive function.
+The principal reason do to so to allow later use of SPECIALISE
@@ -7995,6 +7968,9 @@ RULE with a somewhat-complex left-hand side (try it yourself), so it might not f
well. If you use this kind of specialisation, let us know how well it works.
+
+ SPECIALIZE INLINE
+
A SPECIALIZE pragma can optionally be followed with a
INLINE or NOINLINE pragma, optionally
followed by a phase, as described in .
@@ -8023,6 +7999,66 @@ specialisation, whose body is also inlined. The result is a type-based
unrolling of the indexing function.Warning: you can make GHC diverge by using SPECIALISE INLINE
on an ordinarily-recursive function.
+
+
+SPECIALIZE for imported functions
+
+
+Generally, you can only give a SPECIALIZE pragma
+for a function defined in the same module.
+However if a function f is given an INLINABLE
+pragma at its definition site, then it can subequently be specialised by
+importing modules (see ).
+For example
+
+module Map( lookup, blah blah ) where
+ lookup :: Ord key => [(key,a)] -> key -> Maybe a
+ lookup = ...
+ {-# INLINABLE lookup #-}
+
+module Client where
+ import Map( lookup )
+
+ data T = T1 | T2 deriving( Eq, Ord )
+ {-# SPECIALISE lookup :: [(T,a)] -> T -> Maybe a
+
+Here, lookup is declared INLINABLE, but
+it cannot be specialised for type T at its definition site,
+because that type does not exist yet. Instead a client module can define T
+and then specialise lookup at that type.
+
+
+Moreover, every module that imports Client (or imports a module
+that imports Client, transitively) will "see", and make use of,
+the specialised version of lookup. You don't need to put
+a SPECIALIZE pragma in every module.
+
+
+Moreover you often don't even need the SPECIALIZE pragma in the
+first place. When compiling a module M,
+GHC's optimiser (with -O) automatically considers each top-level
+overloaded function declared in M, and specialises it
+for the different types at which it is called in M. The optimiser
+also considers each imported
+INLINABLE overloaded function, and specialises it
+for the different types at which it is called in M.
+So in our example, it would be enough for lookup to
+be called at type T:
+
+module Client where
+ import Map( lookup )
+
+ data T = T1 | T2 deriving( Eq, Ord )
+
+ findT1 :: [(T,a)] -> Maybe a
+ findT1 m = lookup m T1 -- A call of lookup at type T
+
+However, sometimes there are no such calls, in which case the
+pragma can be useful.
+
+
+
+Obselete SPECIALIZE syntaxNote: In earlier versions of GHC, it was possible to provide your own
specialised function for a given type:
@@ -8033,6 +8069,7 @@ on an ordinarily-recursive function.
This feature has been removed, as it is now subsumed by the
RULES pragma (see ).
+
@@ -8157,7 +8194,7 @@ Here is an example:
Use the debug flag to see what rules fired.
If you need more information, then shows you
-each individual rule firing in detail.
+each individual rule firing and also shows what the code looks like before and after the rewrite.
@@ -8742,7 +8779,8 @@ If you add you get a more detailed listing.
- Use to see in great detail what rules are being fired.
+ Use or
+to see in great detail what rules are being fired.
If you add you get a still more detailed listing.
@@ -8879,7 +8917,7 @@ An example will give the idea:
- import Generics
+ import Data.Generics
class Bin a where
toBin :: a -> [Int]
@@ -8899,7 +8937,7 @@ An example will give the idea:
This class declaration explains how toBin and fromBin
work for arbitrary data types. They do so by giving cases for unit, product, and sum,
-which are defined thus in the library module Generics:
+which are defined thus in the library module Data.Generics:
data Unit = Unit
@@ -8921,14 +8959,16 @@ where clause and over-ride whichever methods you please.
To use generics you need to
- Use the flags (to enable the extra syntax),
- (to generate extra per-data-type code),
- and (to make the Generics library
- available.
+
+ Use the flags (to enable the
+ extra syntax and generate extra per-data-type code),
+ and (to make the
+ Data.Generics module available.
+
- Import the module Generics from the
- lang package. This import brings into
+ Import the module Data.Generics from the
+ syb package. This import brings into
scope the data types Unit,
:*:, and :+:. (You
don't need this import if you don't mention these types