X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fglasgow_exts.sgml;h=12e828495e9ffd697da642fbdf06564b4f41e029;hb=32b472052ded4529534cca0cece640f5c20d5bc8;hp=63fd927ec5b9ab86e02d03a1c2006b7a356a1954;hpb=10b68ffeaa642b8b61b85096052b18227ff3c83b;p=ghc-hetmet.git
diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml
index 63fd927..12e8284 100644
--- a/ghc/docs/users_guide/glasgow_exts.sgml
+++ b/ghc/docs/users_guide/glasgow_exts.sgml
@@ -2,17 +2,19 @@
language, GHCextensions, GHC
As with all known Haskell systems, GHC implements some extensions to
-the language. To use them, you'll need to give a
--fglasgow-exts option option.
+the language. They are all enabled by options; by default GHC
+understands only plain Haskell 98.
-Virtually all of the Glasgow extensions serve to give you access to
-the underlying facilities with which we implement Haskell. Thus, you
-can get at the Raw Iron, if you are willing to write some non-standard
-code at a more primitive level. You need not be “stuck” on
-performance because of the implementation costs of Haskell's
-“high-level” features—you can always code “under” them. In an extreme case, you can write all your time-critical code in C, and then just glue it together with Haskell!
+Some of the Glasgow extensions serve to give you access to the
+underlying facilities with which we implement Haskell. Thus, you can
+get at the Raw Iron, if you are willing to write some non-portable
+code at a more primitive level. You need not be “stuck”
+on performance because of the implementation costs of Haskell's
+“high-level” features—you can always code
+“under” them. In an extreme case, you can write all your
+time-critical code in C, and then just glue it together with Haskell!
@@ -20,8 +22,8 @@ Before you get too carried away working at the lowest level (e.g.,
sloshing MutableByteArray#s around your
program), you may wish to check if there are libraries that provide a
“Haskellised veneer” over the features you want. The
-separate libraries documentation describes all the libraries that come
-with GHC.
+separate libraries
+documentation describes all the libraries that come with GHC.
@@ -35,10 +37,38 @@ with GHC.
extensionsoptions controlling
- These flags control what variation of the language are
+ These flags control what variation of the language are
permitted. Leaving out all of them gives you standard Haskell
98.
+ NB. 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.
+
@@ -49,6 +79,19 @@ with GHC.
Haskell 98 described in , except where otherwise
noted.
+
+ New reserved words: forall (only in
+ types), mdo.
+
+ Other syntax stolen:
+ varid{#},
+ char#,
+ string#,
+ integer#,
+ float#,
+ float##,
+ (#, #),
+ |), {|.
@@ -61,6 +104,8 @@ with GHC.
Haskell 98 Foreign Function Interface Addendum plus deprecated
syntax of previous versions of the FFI for backwards
compatibility.
+
+ New reserved words: foreign.
@@ -103,6 +148,14 @@ with GHC.
See . Independent of
.
+
+ New reserved words/symbols: rec,
+ proc, -<,
+ >-, -<<,
+ >>-.
+
+ Other syntax stolen: (|,
+ |).
@@ -149,6 +202,12 @@ with GHC.
Enables Template Haskell (see ). Currently also implied by
.
+
+ Syntax stolen: [|,
+ [e|, [p|,
+ [d|, [t|,
+ $(,
+ $varid.
@@ -158,6 +217,10 @@ with GHC.
Enables implicit parameters (see ). Currently also implied by
.
+
+ Syntax stolen:
+ ?varid,
+ %varid.
@@ -1435,14 +1498,14 @@ With the GHC lifts this restriction.
The context of a type signature
-Unlike Haskell 1.4, constraints in types do not have to be of
-the form (class type-variables). Thus, these type signatures
-are perfectly OK
+Unlike Haskell 98, constraints in types do not have to be of
+the form (class type-variable) or
+(class (type-variable type-variable ...)). Thus,
+these type signatures are perfectly OK
- f :: Eq (m a) => [m a] -> [m a]
g :: Eq [a] => ...
+ g :: Ord (T a ()) => ...
-This choice recovers principal types, a property that Haskell 1.4 does not have.
GHC imposes the following restrictions on the constraints in a type signature.
@@ -1453,7 +1516,7 @@ Consider the type:
(Here, we write the "foralls" explicitly, although the Haskell source
-language omits them; in Haskell 1.4, all the free type variables of an
+language omits them; in Haskell 98, all the free type variables of an
explicit source-language type signature are universally quantified,
except for the class type variables in a class declaration. However,
in GHC, you can give the foralls if you want. See ).
@@ -1597,9 +1660,9 @@ declarations
instance context2 => C type2 where ...
-
-"overlap" if type1 and type2 unify
-
+"overlap" if type1 and type2 unify.
+
+
However, if you give the command line option
-fallow-overlapping-instances
option then overlapping instance declarations are permitted.
@@ -1684,7 +1747,7 @@ change that decision, at least for Main.)
Type synonyms in the instance head
-Unlike Haskell 1.4, instance heads may use type
+Unlike Haskell 98, instance heads may use type
synonyms. (The instance "head" is the bit after the "=>" in an instance decl.)
As always, using a type synonym is just shorthand for
writing the RHS of the type synonym definition. For example:
@@ -2296,8 +2359,8 @@ the forall is on the left of a function arrrow. As
shows, the polymorphic type on the left of the function arrow can be overloaded.
-The functions f3 and g3 have rank-3 types;
-they have rank-2 types on the left of a function arrow.
+The function f3 has a rank-3 type;
+it has rank-2 types on the left of a function arrow.
GHC allows types of arbitrary rank; you can nest foralls
@@ -2309,7 +2372,7 @@ including an operational type class context, is legal:
On the left of a function arrow On the right of a function arrow (see ) As the argument of a constructor, or type of a field, in a data type declaration. For
-example, any of the f1,f2,f3,g1,g2,g3 above would be valid
+example, any of the f1,f2,f3,g1,g2 above would be valid
field type signatures. As the type of an implicit parameter In a pattern type signature (see )
@@ -3105,17 +3168,24 @@ where
S is a type constructor,
- t1...tk are types,
+ The t1...tk are types,
- vk+1...vn are type variables which do not occur in any of
+ The vk+1...vn are type variables which do not occur in any of
the ti, and
- the ci are partial applications of
+ The ci are partial applications of
classes of the form C t1'...tj', where the arity of C
is exactly j+1. That is, C lacks exactly one type argument.
+
+ None of the ci is Read, Show,
+ Typeable, or Data. These classes
+ should not "look through" the type or its constructor. You can still
+ derive these classes for a newtype, but it happens in the usual way, not
+ via this new mechanism.
+
Then, for each ci, the derived instance
declaration is:
@@ -3177,6 +3247,12 @@ the background to
the main technical innovations is discussed in "
Template Meta-programming for Haskell" (Proc Haskell Workshop 2002).
+The details of the Template Haskell design are still in flux. Make sure you
+consult the online 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.2.]
The first example from that paper is set out below as a worked example to help get you started.
@@ -3282,6 +3358,7 @@ Tim Sheard is going to expand it.)
First cut and paste the two modules below into "Main.hs" and "Printf.hs":
+
{- Main.hs -}
module Main where
@@ -3292,9 +3369,8 @@ import Printf ( pr )
-- generated at compile time by "pr" and splices it into
-- the argument of "putStrLn".
main = putStrLn ( $(pr "Hello") )
-
-
+
{- Printf.hs -}
module Printf where
@@ -3317,14 +3393,14 @@ 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] -> Expr
+gen :: [Format] -> ExpQ
gen [D] = [| \n -> show n |]
gen [S] = [| \s -> s |]
-gen [L s] = string s
+gen [L s] = stringE s
-- Here we generate the Haskell code for the splice
-- from an input format string.
-pr :: String -> Expr
+pr :: String -> ExpQ
pr s = gen (parse s)
@@ -3387,7 +3463,7 @@ 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
-Control.Arrow
+Control.Arrow
module.
@@ -3781,7 +3857,7 @@ a new form keyword.
Although only GHC implements arrow notation directly,
there is also a preprocessor
(available from the
-arrows web page>)
+arrows web page)
that translates arrow notation into Haskell 98
for use with other Haskell systems.
You would still want to check arrow programs with GHC;
@@ -3936,7 +4012,7 @@ Assertion failures can be caught, see the documentation for the
The DEPRECATED pragma lets you specify that a particular
function, class, or type, is deprecated. There are two
- forms.
+ forms.
@@ -3961,7 +4037,15 @@ Assertion failures can be caught, see the documentation for the
message.
-
+ 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.
+ 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
.
@@ -4247,7 +4331,71 @@ of the pragma.
-
+
+ UNPACK pragma
+
+ UNPACK
+
+ The UNPACK indicates to the compiler
+ that it should unpack the contents of a constructor field into
+ the constructor itself, removing a level of indirection. For
+ example:
+
+
+data T = T {-# UNPACK #-} !Float
+ {-# UNPACK #-} !Float
+
+
+ will create a constructor T containing
+ two unboxed floats. This may not always be an optimisation: if
+ the T constructor is scrutinised and the
+ floats passed to a non-strict function for example, they will
+ have to be reboxed (this is done automatically by the
+ compiler).
+
+ Unpacking constructor fields should only be used in
+ conjunction with , in order to expose
+ unfoldings to the compiler so the reboxing can be removed as
+ often as possible. For example:
+
+
+f :: T -> Float
+f (T f1 f2) = f1 + f2
+
+
+ The compiler will avoid reboxing f1
+ and f2 by inlining +
+ on floats, but only when is on.
+
+ Any single-constructor data is eligible for unpacking; for
+ example
+
+
+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:
+
+
+data T = T {-# UNPACK #-} !S
+data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
+
+
+ will store two unboxed Int#s
+ directly in the T constructor. The
+ unpacker can see through newtypes, too.
+
+ If a field cannot be unpacked, you will not get a warning,
+ so it might be an idea to check the generated code with
+ .
+
+ See also the flag,
+ which essentially has the effect of adding
+ {-# UNPACK #-} to every strict
+ constructor field.
+