X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;ds=sidebyside;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=ddbd2ec0aa434c05d8a64ed3f55d449a3714615f;hb=14f9af49db1672e023ac8d8c506b42bc5400a787;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..ddbd2ec 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.
@@ -7712,27 +7667,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 +7971,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 +8002,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 +8072,7 @@ on an ordinarily-recursive function.
This feature has been removed, as it is now subsumed by the
RULES pragma (see ).
+
@@ -8157,7 +8197,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 +8782,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.