</term>
<listitem>
<para>This option enables the language extension defined in the
- Haskell 98 Foreign Function Interface Addendum plus deprecated
- syntax of previous versions of the FFI for backwards
- compatibility.</para>
+ Haskell 98 Foreign Function Interface Addendum.</para>
<para>New reserved words: <literal>foreign</literal>.</para>
</listitem>
<varlistentry>
<term>
- <option>-fno-monomorphism-restriction</option>,<option>-fno-monomorphism-restriction</option>:
+ <option>-fno-monomorphism-restriction</option>,<option>-fno-mono-pat-binds</option>:
</term>
<listitem>
<para> These two flags control how generalisation is done.
</varlistentry>
<varlistentry>
+ <term><option>-foverloaded-strings</option></term>
+ <listitem>
+ <para>Enables overloaded string literals (see <xref
+ linkend="overloaded-strings"/>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-fscoped-type-variables</option></term>
<listitem>
<para>Enables lexically-scoped type variables (see <xref
</sect1>
<!-- UNBOXED TYPES AND PRIMITIVE OPERATIONS -->
-<!-- included from primitives.sgml -->
-<!-- &primitives; -->
<sect1 id="primitives">
<title>Unboxed types and primitive operations</title>
linkend="search-path"/>.</para>
<para>GHC comes with a large collection of libraries arranged
- hierarchically; see the accompanying library documentation.
- There is an ongoing project to create and maintain a stable set
- of <quote>core</quote> libraries used by several Haskell
- compilers, and the libraries that GHC comes with represent the
- current status of that project. For more details, see <ulink
- url="http://www.haskell.org/~simonmar/libraries/libraries.html">Haskell
- Libraries</ulink>.</para>
-
+ hierarchically; see the accompanying <ulink
+ url="../libraries/index.html">library
+ documentation</ulink>. More libraries to install are available
+ from <ulink
+ url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>.</para>
</sect2>
<!-- ====================== PATTERN GUARDS ======================= -->
</para>
<programlisting>
-clunky env var1 var1 = case lookup env var1 of
+clunky env var1 var2 = case lookup env var1 of
Nothing -> fail
Just val1 -> case lookup env var2 of
Nothing -> fail
</para>
<programlisting>
-clunky env var1 var1
+clunky env var1 var2
| Just val1 <- lookup env var1
, Just val2 <- lookup env var2
= val1 + val2
you should be all right.</para>
</sect2>
-</sect1>
+<sect2 id="postfix-operators">
+<title>Postfix operators</title>
-<!-- TYPE SYSTEM EXTENSIONS -->
-<sect1 id="type-extensions">
-<title>Type system extensions</title>
+<para>
+GHC allows a small extension to the syntax of left operator sections, which
+allows you to define postfix operators. The extension is this: the left section
+<programlisting>
+ (e !)
+</programlisting>
+is equivalent (from the point of view of both type checking and execution) to the expression
+<programlisting>
+ ((!) e)
+</programlisting>
+(for any expression <literal>e</literal> and operator <literal>(!)</literal>.
+The strict Haskell 98 interpretation is that the section is equivalent to
+<programlisting>
+ (\y -> (!) e y)
+</programlisting>
+That is, the operator must be a function of two arguments. GHC allows it to
+take only one argument, and that in turn allows you to write the function
+postfix.
+</para>
+<para>Since this extension goes beyond Haskell 98, it should really be enabled
+by a flag; but in fact it is enabled all the time. (No Haskell 98 programs
+change their behaviour, of course.)
+</para>
+<para>The extension does not extend to the left-hand side of function
+definitions; you must define such a function in prefix form.</para>
+</sect2>
-<sect2>
-<title>Data types and type synonyms</title>
+</sect1>
+
+
+<!-- TYPE SYSTEM EXTENSIONS -->
+<sect1 id="data-type-extensions">
+<title>Extensions to data types and type synonyms</title>
-<sect3 id="nullary-types">
+<sect2 id="nullary-types">
<title>Data types with no constructors</title>
<para>With the <option>-fglasgow-exts</option> flag, GHC lets you declare
<para>Syntactically, the declaration lacks the "= constrs" part. The
type can be parameterised over types of any kind, but if the kind is
not <literal>*</literal> then an explicit kind annotation must be used
-(see <xref linkend="sec-kinding"/>).</para>
+(see <xref linkend="kinding"/>).</para>
<para>Such data types have only one value, namely bottom.
Nevertheless, they can be useful when defining "phantom types".</para>
-</sect3>
+</sect2>
-<sect3 id="infix-tycons">
+<sect2 id="infix-tycons">
<title>Infix type constructors, classes, and type variables</title>
<para>
</itemizedlist>
</para>
-</sect3>
+</sect2>
-<sect3 id="type-synonyms">
+<sect2 id="type-synonyms">
<title>Liberalised type synonyms</title>
<para>
</programlisting>
because GHC does not allow unboxed tuples on the left of a function arrow.
</para>
-</sect3>
+</sect2>
-<sect3 id="existential-quantification">
+<sect2 id="existential-quantification">
<title>Existentially quantified data constructors
</title>
quite a bit of object-oriented-like programming this way.
</para>
-<sect4 id="existential">
+<sect3 id="existential">
<title>Why existential?
</title>
adding a new existential quantification construct.
</para>
-</sect4>
+</sect3>
-<sect4>
+<sect3>
<title>Type classes</title>
<para>
universal quantification earlier.
</para>
-</sect4>
+</sect3>
-<sect4>
+<sect3 id="existential-records">
<title>Record Constructors</title>
<para>
Here <literal>tag</literal> is a public field, with a well-typed selector
function <literal>tag :: Counter a -> a</literal>. The <literal>self</literal>
type is hidden from the outside; any attempt to apply <literal>_this</literal>,
-<literal>_inc</literal> or <literal>_output</literal> as functions will raise a
+<literal>_inc</literal> or <literal>_display</literal> as functions will raise a
compile-time error. In other words, <emphasis>GHC defines a record selector function
only for fields whose type does not mention the existentially-quantified variables</emphasis>.
(This example used an underscore in the fields for which record selectors
display (inc (inc counterB)) -- prints "##"
</programlisting>
-In GADT declarations (see <xref linkend="gadt"/>), the explicit
-<literal>forall</literal> may be omitted. For example, we can express
-the same <literal>Counter a</literal> using GADT:
-
-<programlisting>
-data Counter a where
- NewCounter { _this :: self
- , _inc :: self -> self
- , _display :: self -> IO ()
- , tag :: a
- }
- :: Counter a
-</programlisting>
-
At the moment, record update syntax is only supported for Haskell 98 data types,
so the following function does <emphasis>not</emphasis> work:
</para>
-</sect4>
+</sect3>
-<sect4>
+<sect3>
<title>Restrictions</title>
<para>
You can't use <literal>deriving</literal> to define instances of a
data type with existentially quantified data constructors.
-Reason: in most cases it would not make sense. For example:#
+Reason: in most cases it would not make sense. For example:;
<programlisting>
data T = forall a. MkT [a] deriving( Eq )
</para>
-</sect4>
</sect3>
+</sect2>
+
+<!-- ====================== Generalised algebraic data types ======================= -->
+
+<sect2 id="gadt-style">
+<title>Declaring data types with explicit constructor signatures</title>
+
+<para>GHC allows you to declare an algebraic data type by
+giving the type signatures of constructors explicitly. For example:
+<programlisting>
+ data Maybe a where
+ Nothing :: Maybe a
+ Just :: a -> Maybe a
+</programlisting>
+The form is called a "GADT-style declaration"
+because Generalised Algebraic Data Types, described in <xref linkend="gadt"/>,
+can only be declared using this form.</para>
+<para>Notice that GADT-style syntax generalises existential types (<xref linkend="existential-quantification"/>).
+For example, these two declarations are equivalent:
+<programlisting>
+ data Foo = forall a. MkFoo a (a -> Bool)
+ data Foo' where { MKFoo :: a -> (a->Bool) -> Foo' }
+</programlisting>
+</para>
+<para>Any data type that can be declared in standard Haskell-98 syntax
+can also be declared using GADT-style syntax.
+The choice is largely stylistic, but GADT-style declarations differ in one important respect:
+they treat class constraints on the data constructors differently.
+Specifically, if the constructor is given a type-class context, that
+context is made available by pattern matching. For example:
+<programlisting>
+ data Set a where
+ MkSet :: Eq a => [a] -> Set a
+
+ makeSet :: Eq a => [a] -> Set a
+ makeSet xs = MkSet (nub xs)
+
+ insert :: a -> Set a -> Set a
+ insert a (MkSet as) | a `elem` as = MkSet as
+ | otherwise = MkSet (a:as)
+</programlisting>
+A use of <literal>MkSet</literal> as a constructor (e.g. in the definition of <literal>makeSet</literal>)
+gives rise to a <literal>(Eq a)</literal>
+constraint, as you would expect. The new feature is that pattern-matching on <literal>MkSet</literal>
+(as in the definition of <literal>insert</literal>) makes <emphasis>available</emphasis> an <literal>(Eq a)</literal>
+context. In implementation terms, the <literal>MkSet</literal> constructor has a hidden field that stores
+the <literal>(Eq a)</literal> dictionary that is passed to <literal>MkSet</literal>; so
+when pattern-matching that dictionary becomes available for the right-hand side of the match.
+In the example, the equality dictionary is used to satisfy the equality constraint
+generated by the call to <literal>elem</literal>, so that the type of
+<literal>insert</literal> itself has no <literal>Eq</literal> constraint.
+</para>
+<para>This behaviour contrasts with Haskell 98's peculiar treament of
+contexts on a data type declaration (Section 4.2.1 of the Haskell 98 Report).
+In Haskell 98 the defintion
+<programlisting>
+ data Eq a => Set' a = MkSet' [a]
+</programlisting>
+gives <literal>MkSet'</literal> the same type as <literal>MkSet</literal> above. But instead of
+<emphasis>making available</emphasis> an <literal>(Eq a)</literal> constraint, pattern-matching
+on <literal>MkSet'</literal> <emphasis>requires</emphasis> an <literal>(Eq a)</literal> constraint!
+GHC faithfully implements this behaviour, odd though it is. But for GADT-style declarations,
+GHC's behaviour is much more useful, as well as much more intuitive.</para>
+<para>
+For example, a possible application of GHC's behaviour is to reify dictionaries:
+<programlisting>
+ data NumInst a where
+ MkNumInst :: Num a => NumInst a
+
+ intInst :: NumInst Int
+ intInst = MkNumInst
+
+ plus :: NumInst a -> a -> a -> a
+ plus MkNumInst p q = p + q
+</programlisting>
+Here, a value of type <literal>NumInst a</literal> is equivalent
+to an explicit <literal>(Num a)</literal> dictionary.
+</para>
+
+<para>
+The rest of this section gives further details about GADT-style data
+type declarations.
+
+<itemizedlist>
+<listitem><para>
+The result type of each data constructor must begin with the type constructor being defined.
+If the result type of all constructors
+has the form <literal>T a1 ... an</literal>, where <literal>a1 ... an</literal>
+are distinct type variables, then the data type is <emphasis>ordinary</emphasis>;
+otherwise is a <emphasis>generalised</emphasis> data type (<xref linkend="gadt"/>).
+</para></listitem>
+
+<listitem><para>
+The type signature of
+each constructor is independent, and is implicitly universally quantified as usual.
+Different constructors may have different universally-quantified type variables
+and different type-class constraints.
+For example, this is fine:
+<programlisting>
+ data T a where
+ T1 :: Eq b => b -> T b
+ T2 :: (Show c, Ix c) => c -> [c] -> T c
+</programlisting>
+</para></listitem>
+
+<listitem><para>
+Unlike a Haskell-98-style
+data type declaration, the type variable(s) in the "<literal>data Set a where</literal>" header
+have no scope. Indeed, one can write a kind signature instead:
+<programlisting>
+ data Set :: * -> * where ...
+</programlisting>
+or even a mixture of the two:
+<programlisting>
+ data Foo a :: (* -> *) -> * where ...
+</programlisting>
+The type variables (if given) may be explicitly kinded, so we could also write the header for <literal>Foo</literal>
+like this:
+<programlisting>
+ data Foo a (b :: * -> *) where ...
+</programlisting>
+</para></listitem>
+
+
+<listitem><para>
+You can use strictness annotations, in the obvious places
+in the constructor type:
+<programlisting>
+ data Term a where
+ Lit :: !Int -> Term Int
+ If :: Term Bool -> !(Term a) -> !(Term a) -> Term a
+ Pair :: Term a -> Term b -> Term (a,b)
+</programlisting>
+</para></listitem>
+
+<listitem><para>
+You can use a <literal>deriving</literal> clause on a GADT-style data type
+declaration. For example, these two declarations are equivalent
+<programlisting>
+ data Maybe1 a where {
+ Nothing1 :: Maybe1 a ;
+ Just1 :: a -> Maybe1 a
+ } deriving( Eq, Ord )
+
+ data Maybe2 a = Nothing2 | Just2 a
+ deriving( Eq, Ord )
+</programlisting>
+</para></listitem>
+
+<listitem><para>
+You can use record syntax on a GADT-style data type declaration:
+
+<programlisting>
+ data Person where
+ Adult { name :: String, children :: [Person] } :: Person
+ Child { name :: String } :: Person
+</programlisting>
+As usual, for every constructor that has a field <literal>f</literal>, the type of
+field <literal>f</literal> must be the same (modulo alpha conversion).
+</para>
+<para>
+At the moment, record updates are not yet possible with GADT-style declarations,
+so support is limited to record construction, selection and pattern matching.
+For exmaple
+<programlisting>
+ aPerson = Adult { name = "Fred", children = [] }
+
+ shortName :: Person -> Bool
+ hasChildren (Adult { children = kids }) = not (null kids)
+ hasChildren (Child {}) = False
+</programlisting>
+</para></listitem>
+
+<listitem><para>
+As in the case of existentials declared using the Haskell-98-like record syntax
+(<xref linkend="existential-records"/>),
+record-selector functions are generated only for those fields that have well-typed
+selectors.
+Here is the example of that section, in GADT-style syntax:
+<programlisting>
+data Counter a where
+ NewCounter { _this :: self
+ , _inc :: self -> self
+ , _display :: self -> IO ()
+ , tag :: a
+ }
+ :: Counter a
+</programlisting>
+As before, only one selector function is generated here, that for <literal>tag</literal>.
+Nevertheless, you can still use all the field names in pattern matching and record construction.
+</para></listitem>
+</itemizedlist></para>
+</sect2>
+
+<sect2 id="gadt">
+<title>Generalised Algebraic Data Types (GADTs)</title>
+
+<para>Generalised Algebraic Data Types generalise ordinary algebraic data types
+by allowing constructors to have richer return types. Here is an example:
+<programlisting>
+ data Term a where
+ Lit :: Int -> Term Int
+ Succ :: Term Int -> Term Int
+ IsZero :: Term Int -> Term Bool
+ If :: Term Bool -> Term a -> Term a -> Term a
+ Pair :: Term a -> Term b -> Term (a,b)
+</programlisting>
+Notice that the return type of the constructors is not always <literal>Term a</literal>, as is the
+case with ordinary data types. This generality allows us to
+write a well-typed <literal>eval</literal> function
+for these <literal>Terms</literal>:
+<programlisting>
+ eval :: Term a -> a
+ eval (Lit i) = i
+ eval (Succ t) = 1 + eval t
+ eval (IsZero t) = eval t == 0
+ eval (If b e1 e2) = if eval b then eval e1 else eval e2
+ eval (Pair e1 e2) = (eval e1, eval e2)
+</programlisting>
+The key point about GADTs is that <emphasis>pattern matching causes type refinement</emphasis>.
+For example, in the right hand side of the equation
+<programlisting>
+ eval :: Term a -> a
+ eval (Lit i) = ...
+</programlisting>
+the type <literal>a</literal> is refined to <literal>Int</literal>. That's the whole point!
+A precise specification of the type rules is beyond what this user manual aspires to,
+but the design closely follows that described in
+the paper <ulink
+url="http://research.microsoft.com/%7Esimonpj/papers/gadt/index.htm">Simple
+unification-based type inference for GADTs</ulink>,
+(ICFP 2006).
+The general principle is this: <emphasis>type refinement is only carried out
+based on user-supplied type annotations</emphasis>.
+So if no type signature is supplied for <literal>eval</literal>, no type refinement happens,
+and lots of obscure error messages will
+occur. However, the refinement is quite general. For example, if we had:
+<programlisting>
+ eval :: Term a -> a -> a
+ eval (Lit i) j = i+j
+</programlisting>
+the pattern match causes the type <literal>a</literal> to be refined to <literal>Int</literal> (because of the type
+of the constructor <literal>Lit</literal>), and that refinement also applies to the type of <literal>j</literal>, and
+the result type of the <literal>case</literal> expression. Hence the addition <literal>i+j</literal> is legal.
+</para>
+<para>
+These and many other examples are given in papers by Hongwei Xi, and
+Tim Sheard. There is a longer introduction
+<ulink url="http://haskell.org/haskellwiki/GADT">on the wiki</ulink>,
+and Ralf Hinze's
+<ulink url="http://www.informatik.uni-bonn.de/~ralf/publications/With.pdf">Fun with phantom types</ulink> also has a number of examples. Note that papers
+may use different notation to that implemented in GHC.
+</para>
+<para>
+The rest of this section outlines the extensions to GHC that support GADTs.
+<itemizedlist>
+<listitem><para>
+A GADT can only be declared using GADT-style syntax (<xref linkend="gadt-style"/>);
+the old Haskell-98 syntax for data declarations always declares an ordinary data type.
+The result type of each constructor must begin with the type constructor being defined,
+but for a GADT the arguments to the type constructor can be arbitrary monotypes.
+For example, in the <literal>Term</literal> data
+type above, the type of each constructor must end with <literal>Term ty</literal>, but
+the <literal>ty</literal> may not be a type variable (e.g. the <literal>Lit</literal>
+constructor).
+</para></listitem>
+
+<listitem><para>
+You cannot use a <literal>deriving</literal> clause for a GADT; only for
+an ordianary data type.
+</para></listitem>
+
+<listitem><para>
+As mentioned in <xref linkend="gadt-style"/>, record syntax is supported.
+For example:
+<programlisting>
+ data Term a where
+ Lit { val :: Int } :: Term Int
+ Succ { num :: Term Int } :: Term Int
+ Pred { num :: Term Int } :: Term Int
+ IsZero { arg :: Term Int } :: Term Bool
+ Pair { arg1 :: Term a
+ , arg2 :: Term b
+ } :: Term (a,b)
+ If { cnd :: Term Bool
+ , tru :: Term a
+ , fls :: Term a
+ } :: Term a
+</programlisting>
+However, for GADTs there is the following additional constraint:
+every constructor that has a field <literal>f</literal> must have
+the same result type (modulo alpha conversion)
+Hence, in the above example, we cannot merge the <literal>num</literal>
+and <literal>arg</literal> fields above into a
+single name. Although their field types are both <literal>Term Int</literal>,
+their selector functions actually have different types:
+
+<programlisting>
+ num :: Term Int -> Term Int
+ arg :: Term Bool -> Term Int
+</programlisting>
+</para></listitem>
+
+</itemizedlist>
+</para>
</sect2>
+<!-- ====================== End of Generalised algebraic data types ======================= -->
+<sect2 id="deriving-typeable">
+<title>Deriving clause for classes <literal>Typeable</literal> and <literal>Data</literal></title>
+
+<para>
+Haskell 98 allows the programmer to add "<literal>deriving( Eq, Ord )</literal>" to a data type
+declaration, to generate a standard instance declaration for classes specified in the <literal>deriving</literal> clause.
+In Haskell 98, the only classes that may appear in the <literal>deriving</literal> clause are the standard
+classes <literal>Eq</literal>, <literal>Ord</literal>,
+<literal>Enum</literal>, <literal>Ix</literal>, <literal>Bounded</literal>, <literal>Read</literal>, and <literal>Show</literal>.
+</para>
+<para>
+GHC extends this list with two more classes that may be automatically derived
+(provided the <option>-fglasgow-exts</option> flag is specified):
+<literal>Typeable</literal>, and <literal>Data</literal>. These classes are defined in the library
+modules <literal>Data.Typeable</literal> and <literal>Data.Generics</literal> respectively, and the
+appropriate class must be in scope before it can be mentioned in the <literal>deriving</literal> clause.
+</para>
+<para>An instance of <literal>Typeable</literal> can only be derived if the
+data type has seven or fewer type parameters, all of kind <literal>*</literal>.
+The reason for this is that the <literal>Typeable</literal> class is derived using the scheme
+described in
+<ulink url="http://research.microsoft.com/%7Esimonpj/papers/hmap/gmap2.ps">
+Scrap More Boilerplate: Reflection, Zips, and Generalised Casts
+</ulink>.
+(Section 7.4 of the paper describes the multiple <literal>Typeable</literal> classes that
+are used, and only <literal>Typeable1</literal> up to
+<literal>Typeable7</literal> are provided in the library.)
+In other cases, there is nothing to stop the programmer writing a <literal>TypableX</literal>
+class, whose kind suits that of the data type constructor, and
+then writing the data type instance by hand.
+</para>
+</sect2>
+
+<sect2 id="newtype-deriving">
+<title>Generalised derived instances for newtypes</title>
+
+<para>
+When you define an abstract type using <literal>newtype</literal>, you may want
+the new type to inherit some instances from its representation. In
+Haskell 98, you can inherit instances of <literal>Eq</literal>, <literal>Ord</literal>,
+<literal>Enum</literal> and <literal>Bounded</literal> by deriving them, but for any
+other classes you have to write an explicit instance declaration. For
+example, if you define
+
+<programlisting>
+ newtype Dollars = Dollars Int
+</programlisting>
+
+and you want to use arithmetic on <literal>Dollars</literal>, you have to
+explicitly define an instance of <literal>Num</literal>:
+
+<programlisting>
+ instance Num Dollars where
+ Dollars a + Dollars b = Dollars (a+b)
+ ...
+</programlisting>
+All the instance does is apply and remove the <literal>newtype</literal>
+constructor. It is particularly galling that, since the constructor
+doesn't appear at run-time, this instance declaration defines a
+dictionary which is <emphasis>wholly equivalent</emphasis> to the <literal>Int</literal>
+dictionary, only slower!
+</para>
+
+
+<sect3> <title> Generalising the deriving clause </title>
+<para>
+GHC now permits such instances to be derived instead, so one can write
+<programlisting>
+ newtype Dollars = Dollars Int deriving (Eq,Show,Num)
+</programlisting>
+
+and the implementation uses the <emphasis>same</emphasis> <literal>Num</literal> dictionary
+for <literal>Dollars</literal> as for <literal>Int</literal>. Notionally, the compiler
+derives an instance declaration of the form
+
+<programlisting>
+ instance Num Int => Num Dollars
+</programlisting>
+
+which just adds or removes the <literal>newtype</literal> constructor according to the type.
+</para>
+<para>
+
+We can also derive instances of constructor classes in a similar
+way. For example, suppose we have implemented state and failure monad
+transformers, such that
+
+<programlisting>
+ instance Monad m => Monad (State s m)
+ instance Monad m => Monad (Failure m)
+</programlisting>
+In Haskell 98, we can define a parsing monad by
+<programlisting>
+ type Parser tok m a = State [tok] (Failure m) a
+</programlisting>
+
+which is automatically a monad thanks to the instance declarations
+above. With the extension, we can make the parser type abstract,
+without needing to write an instance of class <literal>Monad</literal>, via
+
+<programlisting>
+ newtype Parser tok m a = Parser (State [tok] (Failure m) a)
+ deriving Monad
+</programlisting>
+In this case the derived instance declaration is of the form
+<programlisting>
+ instance Monad (State [tok] (Failure m)) => Monad (Parser tok m)
+</programlisting>
+
+Notice that, since <literal>Monad</literal> is a constructor class, the
+instance is a <emphasis>partial application</emphasis> 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
+declaration.
+</para>
+<para>
+
+We can even derive instances of multi-parameter classes, provided the
+newtype is the last class parameter. In this case, a ``partial
+application'' of the class appears in the <literal>deriving</literal>
+clause. For example, given the class
+
+<programlisting>
+ class StateMonad s m | m -> s where ...
+ instance Monad m => StateMonad s (State s m) where ...
+</programlisting>
+then we can derive an instance of <literal>StateMonad</literal> for <literal>Parser</literal>s by
+<programlisting>
+ newtype Parser tok m a = Parser (State [tok] (Failure m) a)
+ deriving (Monad, StateMonad [tok])
+</programlisting>
+
+The derived instance is obtained by completing the application of the
+class to the new type:
+
+<programlisting>
+ instance StateMonad [tok] (State [tok] (Failure m)) =>
+ StateMonad [tok] (Parser tok m)
+</programlisting>
+</para>
+<para>
+
+As a result of this extension, all derived instances in newtype
+ declarations are treated uniformly (and implemented just by reusing
+the dictionary for the representation type), <emphasis>except</emphasis>
+<literal>Show</literal> and <literal>Read</literal>, which really behave differently for
+the newtype and its representation.
+</para>
+</sect3>
+
+<sect3> <title> A more precise specification </title>
+<para>
+Derived instance declarations are constructed as follows. Consider the
+declaration (after expansion of any type synonyms)
+
+<programlisting>
+ newtype T v1...vn = T' (t vk+1...vn) deriving (c1...cm)
+</programlisting>
+
+where
+ <itemizedlist>
+<listitem><para>
+ The <literal>ci</literal> are partial applications of
+ classes of the form <literal>C t1'...tj'</literal>, where the arity of <literal>C</literal>
+ is exactly <literal>j+1</literal>. That is, <literal>C</literal> lacks exactly one type argument.
+</para></listitem>
+<listitem><para>
+ The <literal>k</literal> is chosen so that <literal>ci (T v1...vk)</literal> is well-kinded.
+</para></listitem>
+<listitem><para>
+ The type <literal>t</literal> is an arbitrary type.
+</para></listitem>
+<listitem><para>
+ The type variables <literal>vk+1...vn</literal> do not occur in <literal>t</literal>,
+ nor in the <literal>ci</literal>, and
+</para></listitem>
+<listitem><para>
+ None of the <literal>ci</literal> is <literal>Read</literal>, <literal>Show</literal>,
+ <literal>Typeable</literal>, or <literal>Data</literal>. 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.
+</para></listitem>
+</itemizedlist>
+Then, for each <literal>ci</literal>, the derived instance
+declaration is:
+<programlisting>
+ instance ci t => ci (T v1...vk)
+</programlisting>
+As an example which does <emphasis>not</emphasis> work, consider
+<programlisting>
+ newtype NonMonad m s = NonMonad (State s m s) deriving Monad
+</programlisting>
+Here we cannot derive the instance
+<programlisting>
+ instance Monad (State s m) => Monad (NonMonad m)
+</programlisting>
+
+because the type variable <literal>s</literal> occurs in <literal>State s m</literal>,
+and so cannot be "eta-converted" away. It is a good thing that this
+<literal>deriving</literal> clause is rejected, because <literal>NonMonad m</literal> is
+not, in fact, a monad --- for the same reason. Try defining
+<literal>>>=</literal> with the correct type: you won't be able to.
+</para>
+<para>
+
+Notice also that the <emphasis>order</emphasis> of class parameters becomes
+important, since we can only derive instances for the last one. If the
+<literal>StateMonad</literal> class above were instead defined as
+
+<programlisting>
+ class StateMonad m s | m -> s where ...
+</programlisting>
+
+then we would not have been able to derive an instance for the
+<literal>Parser</literal> type above. We hypothesise that multi-parameter
+classes usually have one "main" parameter for which deriving new
+instances is most interesting.
+</para>
+<para>Lastly, all of this applies only for classes other than
+<literal>Read</literal>, <literal>Show</literal>, <literal>Typeable</literal>,
+and <literal>Data</literal>, for which the built-in derivation applies (section
+4.3.3. of the Haskell Report).
+(For the standard classes <literal>Eq</literal>, <literal>Ord</literal>,
+<literal>Ix</literal>, and <literal>Bounded</literal> it is immaterial whether
+the standard method is used or the one described here.)
+</para>
+</sect3>
+
+</sect2>
+
+<sect2 id="stand-alone-deriving">
+<title>Stand-alone deriving declarations</title>
+
+<para>
+GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by <literal>-fglasgow-exts</literal>:
+<programlisting>
+ data Foo a = Bar a | Baz String
+
+ derive instance Eq (Foo a)
+</programlisting>
+The token "<literal>derive</literal>" is a keyword only when followed by "<literal>instance</literal>";
+you can use it as a variable name elsewhere.</para>
+<para>The stand-alone syntax is generalised for newtypes in exactly the same
+way that ordinary <literal>deriving</literal> clauses are generalised (<xref linkend="newtype-deriving"/>).
+For example:
+<programlisting>
+ newtype Foo a = MkFoo (State Int a)
+
+ derive instance MonadState Int Foo
+</programlisting>
+GHC always treats the <emphasis>last</emphasis> parameter of the instance
+(<literal>Foo</literal> in this exmample) as the type whose instance is being derived.
+</para>
+
+</sect2>
+
+</sect1>
+
+
+<!-- TYPE SYSTEM EXTENSIONS -->
+<sect1 id="other-type-extensions">
+<title>Other type system extensions</title>
+
<sect2 id="multi-param-type-classes">
<title>Class declarations</title>
following rules:
<orderedlist>
<listitem><para>
-For each assertion in the context:
+The Paterson Conditions: for each assertion in the context
<orderedlist>
<listitem><para>No type variable has more occurrences in the assertion than in the head</para></listitem>
<listitem><para>The assertion has fewer constructors and variables (taken together
</orderedlist>
</para></listitem>
-<listitem><para>The coverage condition. For each functional dependency,
+<listitem><para>The Coverage Condition. For each functional dependency,
<replaceable>tvs</replaceable><subscript>left</subscript> <literal>-></literal>
<replaceable>tvs</replaceable><subscript>right</subscript>, of the class,
every type variable in
</orderedlist>
These restrictions ensure that context reduction terminates: each reduction
step makes the problem smaller by at least one
-constructor. For example, the following would make the type checker
-loop if it wasn't excluded:
-<programlisting>
- instance C a => C a where ...
-</programlisting>
+constructor. Both the Paterson Conditions and the Coverage Condition are lifted
+if you give the <option>-fallow-undecidable-instances</option>
+flag (<xref linkend="undecidable-instances"/>).
+You can find lots of background material about the reason for these
+restrictions in the paper <ulink
+url="http://research.microsoft.com/%7Esimonpj/papers/fd%2Dchr/">
+Understanding functional dependencies via Constraint Handling Rules</ulink>.
+</para>
+<para>
For example, these are OK:
<programlisting>
instance C Int [a] -- Multiple parameters
convenient to have a "default instance" declaration that applies if
something more specific does not:
<programlisting>
- instance C a where
- op = ... -- Default
-</programlisting>
-</para>
-<para>You can find lots of background material about the reason for these
-restrictions in the paper <ulink
-url="http://research.microsoft.com/%7Esimonpj/papers/fd%2Dchr/">
-Understanding functional dependencies via Constraint Handling Rules</ulink>.
+ instance C a where
+ op = ... -- Default
+</programlisting>
</para>
</sect3>
Nevertheless, GHC allows you to experiment with more liberal rules. If you use
the experimental flag <option>-fallow-undecidable-instances</option>
<indexterm><primary>-fallow-undecidable-instances
-option</primary></indexterm>, you can use arbitrary
-types in both an instance context and instance head. Termination is ensured by having a
+option</primary></indexterm>, both the Paterson Conditions and the Coverage Condition
+(described in <xref linkend="instance-rules"/>) are lifted. Termination is ensured by having a
fixed-depth recursion stack. If you exceed the stack depth you get a
sort of backtrace, and the opportunity to increase the stack depth
with <option>-fcontext-stack=</option><emphasis>N</emphasis>.
</para>
</sect3>
-<sect3 id="hoist">
-<title>For-all hoisting</title>
-<para>
-It is often convenient to use generalised type synonyms (see <xref linkend="type-synonyms"/>) at the right hand
-end of an arrow, thus:
-<programlisting>
- type Discard a = forall b. a -> b -> a
-
- g :: Int -> Discard Int
- g x y z = x+y
-</programlisting>
-Simply expanding the type synonym would give
-<programlisting>
- g :: Int -> (forall b. Int -> b -> Int)
-</programlisting>
-but GHC "hoists" the <literal>forall</literal> to give the isomorphic type
-<programlisting>
- g :: forall b. Int -> Int -> b -> Int
-</programlisting>
-In general, the rule is this: <emphasis>to determine the type specified by any explicit
-user-written type (e.g. in a type signature), GHC expands type synonyms and then repeatedly
-performs the transformation:</emphasis>
-<programlisting>
- <emphasis>type1</emphasis> -> forall a1..an. <emphasis>context2</emphasis> => <emphasis>type2</emphasis>
-==>
- forall a1..an. <emphasis>context2</emphasis> => <emphasis>type1</emphasis> -> <emphasis>type2</emphasis>
-</programlisting>
-(In fact, GHC tries to retain as much synonym information as possible for use in
-error messages, but that is a usability issue.) This rule applies, of course, whether
-or not the <literal>forall</literal> comes from a synonym. For example, here is another
-valid way to write <literal>g</literal>'s type signature:
-<programlisting>
- g :: Int -> Int -> forall b. b -> Int
-</programlisting>
-</para>
-<para>
-When doing this hoisting operation, GHC eliminates duplicate constraints. For
-example:
-<programlisting>
- type Foo a = (?x::Int) => Bool -> a
- g :: Foo (Foo Int)
-</programlisting>
-means
-<programlisting>
- g :: (?x::Int) => Bool -> Bool -> Int
-</programlisting>
-</para>
-</sect3>
</sect2>
================ END OF Linear Implicit Parameters commented out -->
-<sect2 id="sec-kinding">
+<sect2 id="kinding">
<title>Explicitly-kinded quantification</title>
<para>
g2 :: (forall a. Eq a => [a] -> a -> Bool) -> Int -> Int
f3 :: ((forall a. a->a) -> Int) -> Bool -> Bool
+
+ f4 :: Int -> (forall a. a -> a)
</programlisting>
Here, <literal>f1</literal> and <literal>g1</literal> are rank-1 types, and
can be written in standard Haskell (e.g. <literal>f1 :: a->b->a</literal>).
In particular, a forall-type (also called a "type scheme"),
including an operational type class context, is legal:
<itemizedlist>
-<listitem> <para> On the left of a function arrow </para> </listitem>
-<listitem> <para> On the right of a function arrow (see <xref linkend="hoist"/>) </para> </listitem>
+<listitem> <para> On the left or right (see <literal>f4</literal>, for example)
+of a function arrow </para> </listitem>
<listitem> <para> As the argument of a constructor, or type of a field, in a data type declaration. For
example, any of the <literal>f1,f2,f3,g1,g2</literal> above would be valid
field type signatures.</para> </listitem>
<listitem> <para> As the type of an implicit parameter </para> </listitem>
<listitem> <para> In a pattern type signature (see <xref linkend="scoped-type-variables"/>) </para> </listitem>
</itemizedlist>
-There is one place you cannot put a <literal>forall</literal>:
-you cannot instantiate a type variable with a forall-type. So you cannot
-make a forall-type the argument of a type constructor. So these types are illegal:
-<programlisting>
- x1 :: [forall a. a->a]
- x2 :: (forall a. a->a, Int)
- x3 :: Maybe (forall a. a->a)
-</programlisting>
Of course <literal>forall</literal> becomes a keyword; you can't use <literal>forall</literal> as
a type variable any more!
</para>
A <emphasis>lexically scoped type variable</emphasis> can be bound by:
<itemizedlist>
<listitem><para>A declaration type signature (<xref linkend="decl-type-sigs"/>)</para></listitem>
+<listitem><para>An expression type signature (<xref linkend="exp-type-sigs"/>)</para></listitem>
<listitem><para>A pattern type signature (<xref linkend="pattern-type-sigs"/>)</para></listitem>
<listitem><para>Class and instance declarations (<xref linkend="cls-inst-scoped-tyvars"/>)</para></listitem>
</itemizedlist>
</para>
</sect3>
+<sect3 id="exp-type-sigs">
+<title>Expression type signatures</title>
+
+<para>An expression type signature that has <emphasis>explicit</emphasis>
+quantification (using <literal>forall</literal>) brings into scope the
+explicitly-quantified
+type variables, in the annotated expression. For example:
+<programlisting>
+ f = runST ( (op >>= \(x :: STRef s Int) -> g x) :: forall s. ST s Bool )
+</programlisting>
+Here, the type signature <literal>forall a. ST s Bool</literal> brings the
+type variable <literal>s</literal> into scope, in the annotated expression
+<literal>(op >>= \(x :: STRef s Int) -> g x)</literal>.
+</para>
+
+</sect3>
+
<sect3 id="pattern-type-sigs">
<title>Pattern type signatures</title>
<para>
For example:
<programlisting>
-- f and g assume that 'a' is already in scope
- f = \(x::Int, y) -> x
+ f = \(x::Int, y::a) -> x
g (x::a) = x
h ((x,y) :: (Int,Bool)) = (y,x)
</programlisting>
<!-- ==================== Commented out part about result type signatures
<sect3 id="result-type-sigs">
-<title>Result type signatures</title>
-
-<para>
-The result type of a function, lambda, or case expression alternative can be given a signature, thus:
-
-<programlisting>
- {- f assumes that 'a' is already in scope -}
- f x y :: [a] = [x,y,x]
-
- g = \ x :: [Int] -> [3,4]
-
- h :: forall a. [a] -> a
- h xs = case xs of
- (y:ys) :: a -> y
-</programlisting>
-The final <literal>:: [a]</literal> after the patterns of <literal>f</literal> gives the type of
-the result of the function. Similarly, the body of the lambda in the RHS of
-<literal>g</literal> is <literal>[Int]</literal>, and the RHS of the case
-alternative in <literal>h</literal> is <literal>a</literal>.
-</para>
-<para> A result type signature never brings new type variables into scope.</para>
-<para>
-There are a couple of syntactic wrinkles. First, notice that all three
-examples would parse quite differently with parentheses:
-<programlisting>
- {- f assumes that 'a' is already in scope -}
- f x (y :: [a]) = [x,y,x]
-
- g = \ (x :: [Int]) -> [3,4]
-
- h :: forall a. [a] -> a
- h xs = case xs of
- ((y:ys) :: a) -> y
-</programlisting>
-Now the signature is on the <emphasis>pattern</emphasis>; and
-<literal>h</literal> would certainly be ill-typed (since the pattern
-<literal>(y:ys)</literal> cannot have the type <literal>a</literal>.
-
-Second, to avoid ambiguity, the type after the “<literal>::</literal>” in a result
-pattern signature on a lambda or <literal>case</literal> must be atomic (i.e. a single
-token or a parenthesised type of some sort). To see why,
-consider how one would parse this:
-<programlisting>
- \ x :: a -> b -> x
-</programlisting>
-</para>
-</sect3>
-
- -->
-
-<sect3 id="cls-inst-scoped-tyvars">
-<title>Class and instance declarations</title>
-<para>
-
-The type variables in the head of a <literal>class</literal> or <literal>instance</literal> declaration
-scope over the methods defined in the <literal>where</literal> part. For example:
-
-
-<programlisting>
- class C a where
- op :: [a] -> a
-
- op xs = let ys::[a]
- ys = reverse xs
- in
- head ys
-</programlisting>
-</para>
-</sect3>
-
-</sect2>
-
-<sect2 id="deriving-typeable">
-<title>Deriving clause for classes <literal>Typeable</literal> and <literal>Data</literal></title>
-
-<para>
-Haskell 98 allows the programmer to add "<literal>deriving( Eq, Ord )</literal>" to a data type
-declaration, to generate a standard instance declaration for classes specified in the <literal>deriving</literal> clause.
-In Haskell 98, the only classes that may appear in the <literal>deriving</literal> clause are the standard
-classes <literal>Eq</literal>, <literal>Ord</literal>,
-<literal>Enum</literal>, <literal>Ix</literal>, <literal>Bounded</literal>, <literal>Read</literal>, and <literal>Show</literal>.
-</para>
-<para>
-GHC extends this list with two more classes that may be automatically derived
-(provided the <option>-fglasgow-exts</option> flag is specified):
-<literal>Typeable</literal>, and <literal>Data</literal>. These classes are defined in the library
-modules <literal>Data.Typeable</literal> and <literal>Data.Generics</literal> respectively, and the
-appropriate class must be in scope before it can be mentioned in the <literal>deriving</literal> clause.
-</para>
-<para>An instance of <literal>Typeable</literal> can only be derived if the
-data type has seven or fewer type parameters, all of kind <literal>*</literal>.
-The reason for this is that the <literal>Typeable</literal> class is derived using the scheme
-described in
-<ulink url="http://research.microsoft.com/%7Esimonpj/papers/hmap/gmap2.ps">
-Scrap More Boilerplate: Reflection, Zips, and Generalised Casts
-</ulink>.
-(Section 7.4 of the paper describes the multiple <literal>Typeable</literal> classes that
-are used, and only <literal>Typeable1</literal> up to
-<literal>Typeable7</literal> are provided in the library.)
-In other cases, there is nothing to stop the programmer writing a <literal>TypableX</literal>
-class, whose kind suits that of the data type constructor, and
-then writing the data type instance by hand.
-</para>
-</sect2>
-
-<sect2 id="newtype-deriving">
-<title>Generalised derived instances for newtypes</title>
-
-<para>
-When you define an abstract type using <literal>newtype</literal>, you may want
-the new type to inherit some instances from its representation. In
-Haskell 98, you can inherit instances of <literal>Eq</literal>, <literal>Ord</literal>,
-<literal>Enum</literal> and <literal>Bounded</literal> by deriving them, but for any
-other classes you have to write an explicit instance declaration. For
-example, if you define
-
-<programlisting>
- newtype Dollars = Dollars Int
-</programlisting>
-
-and you want to use arithmetic on <literal>Dollars</literal>, you have to
-explicitly define an instance of <literal>Num</literal>:
-
-<programlisting>
- instance Num Dollars where
- Dollars a + Dollars b = Dollars (a+b)
- ...
-</programlisting>
-All the instance does is apply and remove the <literal>newtype</literal>
-constructor. It is particularly galling that, since the constructor
-doesn't appear at run-time, this instance declaration defines a
-dictionary which is <emphasis>wholly equivalent</emphasis> to the <literal>Int</literal>
-dictionary, only slower!
-</para>
-
-
-<sect3> <title> Generalising the deriving clause </title>
-<para>
-GHC now permits such instances to be derived instead, so one can write
-<programlisting>
- newtype Dollars = Dollars Int deriving (Eq,Show,Num)
-</programlisting>
-
-and the implementation uses the <emphasis>same</emphasis> <literal>Num</literal> dictionary
-for <literal>Dollars</literal> as for <literal>Int</literal>. Notionally, the compiler
-derives an instance declaration of the form
-
-<programlisting>
- instance Num Int => Num Dollars
-</programlisting>
-
-which just adds or removes the <literal>newtype</literal> constructor according to the type.
-</para>
-<para>
-
-We can also derive instances of constructor classes in a similar
-way. For example, suppose we have implemented state and failure monad
-transformers, such that
-
-<programlisting>
- instance Monad m => Monad (State s m)
- instance Monad m => Monad (Failure m)
-</programlisting>
-In Haskell 98, we can define a parsing monad by
-<programlisting>
- type Parser tok m a = State [tok] (Failure m) a
-</programlisting>
-
-which is automatically a monad thanks to the instance declarations
-above. With the extension, we can make the parser type abstract,
-without needing to write an instance of class <literal>Monad</literal>, via
-
-<programlisting>
- newtype Parser tok m a = Parser (State [tok] (Failure m) a)
- deriving Monad
-</programlisting>
-In this case the derived instance declaration is of the form
-<programlisting>
- instance Monad (State [tok] (Failure m)) => Monad (Parser tok m)
-</programlisting>
-
-Notice that, since <literal>Monad</literal> is a constructor class, the
-instance is a <emphasis>partial application</emphasis> 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
-declaration.
-</para>
-<para>
-
-We can even derive instances of multi-parameter classes, provided the
-newtype is the last class parameter. In this case, a ``partial
-application'' of the class appears in the <literal>deriving</literal>
-clause. For example, given the class
-
-<programlisting>
- class StateMonad s m | m -> s where ...
- instance Monad m => StateMonad s (State s m) where ...
-</programlisting>
-then we can derive an instance of <literal>StateMonad</literal> for <literal>Parser</literal>s by
-<programlisting>
- newtype Parser tok m a = Parser (State [tok] (Failure m) a)
- deriving (Monad, StateMonad [tok])
-</programlisting>
-
-The derived instance is obtained by completing the application of the
-class to the new type:
-
-<programlisting>
- instance StateMonad [tok] (State [tok] (Failure m)) =>
- StateMonad [tok] (Parser tok m)
-</programlisting>
-</para>
-<para>
-
-As a result of this extension, all derived instances in newtype
- declarations are treated uniformly (and implemented just by reusing
-the dictionary for the representation type), <emphasis>except</emphasis>
-<literal>Show</literal> and <literal>Read</literal>, which really behave differently for
-the newtype and its representation.
-</para>
-</sect3>
+<title>Result type signatures</title>
-<sect3> <title> A more precise specification </title>
<para>
-Derived instance declarations are constructed as follows. Consider the
-declaration (after expansion of any type synonyms)
+The result type of a function, lambda, or case expression alternative can be given a signature, thus:
-<programlisting>
- newtype T v1...vn = T' (t vk+1...vn) deriving (c1...cm)
-</programlisting>
+<programlisting>
+ {- f assumes that 'a' is already in scope -}
+ f x y :: [a] = [x,y,x]
-where
- <itemizedlist>
-<listitem><para>
- The type <literal>t</literal> is an arbitrary type
-</para></listitem>
-<listitem><para>
- The <literal>vk+1...vn</literal> are type variables which do not occur in
- <literal>t</literal>, and
-</para></listitem>
-<listitem><para>
- The <literal>ci</literal> are partial applications of
- classes of the form <literal>C t1'...tj'</literal>, where the arity of <literal>C</literal>
- is exactly <literal>j+1</literal>. That is, <literal>C</literal> lacks exactly one type argument.
-</para></listitem>
-<listitem><para>
- None of the <literal>ci</literal> is <literal>Read</literal>, <literal>Show</literal>,
- <literal>Typeable</literal>, or <literal>Data</literal>. 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.
-</para></listitem>
-</itemizedlist>
-Then, for each <literal>ci</literal>, the derived instance
-declaration is:
-<programlisting>
- instance ci (t vk+1...v) => ci (T v1...vp)
+ g = \ x :: [Int] -> [3,4]
+
+ h :: forall a. [a] -> a
+ h xs = case xs of
+ (y:ys) :: a -> y
</programlisting>
-where <literal>p</literal> is chosen so that <literal>T v1...vp</literal> is of the
-right <emphasis>kind</emphasis> for the last parameter of class <literal>Ci</literal>.
+The final <literal>:: [a]</literal> after the patterns of <literal>f</literal> gives the type of
+the result of the function. Similarly, the body of the lambda in the RHS of
+<literal>g</literal> is <literal>[Int]</literal>, and the RHS of the case
+alternative in <literal>h</literal> is <literal>a</literal>.
</para>
+<para> A result type signature never brings new type variables into scope.</para>
<para>
+There are a couple of syntactic wrinkles. First, notice that all three
+examples would parse quite differently with parentheses:
+<programlisting>
+ {- f assumes that 'a' is already in scope -}
+ f x (y :: [a]) = [x,y,x]
-As an example which does <emphasis>not</emphasis> work, consider
-<programlisting>
- newtype NonMonad m s = NonMonad (State s m s) deriving Monad
-</programlisting>
-Here we cannot derive the instance
-<programlisting>
- instance Monad (State s m) => Monad (NonMonad m)
-</programlisting>
+ g = \ (x :: [Int]) -> [3,4]
-because the type variable <literal>s</literal> occurs in <literal>State s m</literal>,
-and so cannot be "eta-converted" away. It is a good thing that this
-<literal>deriving</literal> clause is rejected, because <literal>NonMonad m</literal> is
-not, in fact, a monad --- for the same reason. Try defining
-<literal>>>=</literal> with the correct type: you won't be able to.
+ h :: forall a. [a] -> a
+ h xs = case xs of
+ ((y:ys) :: a) -> y
+</programlisting>
+Now the signature is on the <emphasis>pattern</emphasis>; and
+<literal>h</literal> would certainly be ill-typed (since the pattern
+<literal>(y:ys)</literal> cannot have the type <literal>a</literal>.
+
+Second, to avoid ambiguity, the type after the “<literal>::</literal>” in a result
+pattern signature on a lambda or <literal>case</literal> must be atomic (i.e. a single
+token or a parenthesised type of some sort). To see why,
+consider how one would parse this:
+<programlisting>
+ \ x :: a -> b -> x
+</programlisting>
</para>
+</sect3>
+
+ -->
+
+<sect3 id="cls-inst-scoped-tyvars">
+<title>Class and instance declarations</title>
<para>
-Notice also that the <emphasis>order</emphasis> of class parameters becomes
-important, since we can only derive instances for the last one. If the
-<literal>StateMonad</literal> class above were instead defined as
+The type variables in the head of a <literal>class</literal> or <literal>instance</literal> declaration
+scope over the methods defined in the <literal>where</literal> part. For example:
-<programlisting>
- class StateMonad m s | m -> s where ...
-</programlisting>
-then we would not have been able to derive an instance for the
-<literal>Parser</literal> type above. We hypothesise that multi-parameter
-classes usually have one "main" parameter for which deriving new
-instances is most interesting.
-</para>
-<para>Lastly, all of this applies only for classes other than
-<literal>Read</literal>, <literal>Show</literal>, <literal>Typeable</literal>,
-and <literal>Data</literal>, for which the built-in derivation applies (section
-4.3.3. of the Haskell Report).
-(For the standard classes <literal>Eq</literal>, <literal>Ord</literal>,
-<literal>Ix</literal>, and <literal>Bounded</literal> it is immaterial whether
-the standard method is used or the one described here.)
+<programlisting>
+ class C a where
+ op :: [a] -> a
+
+ op xs = let ys::[a]
+ ys = reverse xs
+ in
+ head ys
+</programlisting>
</para>
</sect3>
</sect2>
+
<sect2 id="typing-binds">
<title>Generalised typing of mutually recursive bindings</title>
</para>
</sect2>
-</sect1>
-<!-- ==================== End of type system extensions ================= -->
-
-<!-- ====================== Generalised algebraic data types ======================= -->
-
-<sect1 id="gadt">
-<title>Generalised Algebraic Data Types</title>
+<sect2 id="overloaded-strings">
+<title>Overloaded string literals
+</title>
-<para>Generalised Algebraic Data Types (GADTs) generalise ordinary algebraic data types by allowing you
-to give the type signatures of constructors explicitly. For example:
+<para>
+GHC supports <emphasis>overloaded string literals</emphasis>. Normally a
+string literal has type <literal>String</literal>, but with overloaded string
+literals enabled (with <literal>-foverloaded-strings</literal>)
+ a string literal has type <literal>(IsString a) => a</literal>.
+</para>
+<para>
+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.
+</para>
+<para>
+The class <literal>IsString</literal> is defined as:
<programlisting>
- data Term a where
- Lit :: Int -> Term Int
- Succ :: Term Int -> Term Int
- IsZero :: Term Int -> Term Bool
- If :: Term Bool -> Term a -> Term a -> Term a
- Pair :: Term a -> Term b -> Term (a,b)
+class IsString a where
+ fromString :: String -> a
</programlisting>
-Notice that the return type of the constructors is not always <literal>Term a</literal>, as is the
-case with ordinary vanilla data types. Now we can write a well-typed <literal>eval</literal> function
-for these <literal>Terms</literal>:
+The only predefined instance is the obvious one to make strings work as usual:
<programlisting>
- eval :: Term a -> a
- eval (Lit i) = i
- eval (Succ t) = 1 + eval t
- eval (IsZero t) = eval t == 0
- eval (If b e1 e2) = if eval b then eval e1 else eval e2
- eval (Pair e1 e2) = (eval e1, eval e2)
+instance IsString [Char] where
+ fromString cs = cs
</programlisting>
-These and many other examples are given in papers by Hongwei Xi, and Tim Sheard.
+The class <literal>IsString</literal> 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 <literal>GHC.Exts</literal>.
</para>
<para>
-The rest of this section outlines the extensions to GHC that support GADTs.
-It is far from comprehensive, but the design closely follows that described in
-the paper <ulink
-url="http://research.microsoft.com/%7Esimonpj/papers/gadt/index.htm">Simple
-unification-based type inference for GADTs</ulink>,
-which appeared in ICFP 2006.
+Haskell's defaulting mechanism is extended to cover string literals, when <option>-foverloaded-strings</option> is specified.
+Specifically:
<itemizedlist>
<listitem><para>
- Data type declarations have a 'where' form, as exemplified above. The type signature of
-each constructor is independent, and is implicitly universally quantified as usual. Unlike a normal
-Haskell data type declaration, the type variable(s) in the "<literal>data Term a where</literal>" header
-have no scope. Indeed, one can write a kind signature instead:
-<programlisting>
- data Term :: * -> * where ...
-</programlisting>
-or even a mixture of the two:
-<programlisting>
- data Foo a :: (* -> *) -> * where ...
-</programlisting>
-The type variables (if given) may be explicitly kinded, so we could also write the header for <literal>Foo</literal>
-like this:
-<programlisting>
- data Foo a (b :: * -> *) where ...
-</programlisting>
-</para></listitem>
-
-<listitem><para>
-There are no restrictions on the type of the data constructor, except that the result
-type must begin with the type constructor being defined. For example, in the <literal>Term</literal> data
-type above, the type of each constructor must end with <literal> ... -> Term ...</literal>.
+Each type in a default declaration must be an
+instance of <literal>Num</literal> <emphasis>or</emphasis> of <literal>IsString</literal>.
</para></listitem>
<listitem><para>
-You can use record syntax on a GADT-style data type declaration:
-
-<programlisting>
- data Term a where
- Lit { val :: Int } :: Term Int
- Succ { num :: Term Int } :: Term Int
- Pred { num :: Term Int } :: Term Int
- IsZero { arg :: Term Int } :: Term Bool
- Pair { arg1 :: Term a
- , arg2 :: Term b
- } :: Term (a,b)
- If { cnd :: Term Bool
- , tru :: Term a
- , fls :: Term a
- } :: Term a
-</programlisting>
-For every constructor that has a field <literal>f</literal>, (a) the type of
-field <literal>f</literal> must be the same; and (b) the
-result type of the constructor must be the same; both modulo alpha conversion.
-Hence, in our example, we cannot merge the <literal>num</literal> and <literal>arg</literal>
-fields above into a
-single name. Although their field types are both <literal>Term Int</literal>,
-their selector functions actually have different types:
-
-<programlisting>
- num :: Term Int -> Term Int
- arg :: Term Bool -> Term Int
-</programlisting>
-
-At the moment, record updates are not yet possible with GADT, so support is
-limited to record construction, selection and pattern matching:
-
-<programlisting>
- someTerm :: Term Bool
- someTerm = IsZero { arg = Succ { num = Lit { val = 0 } } }
-
- eval :: Term a -> a
- eval Lit { val = i } = i
- eval Succ { num = t } = eval t + 1
- eval Pred { num = t } = eval t - 1
- eval IsZero { arg = t } = eval t == 0
- eval Pair { arg1 = t1, arg2 = t2 } = (eval t1, eval t2)
- eval t@If{} = if eval (cnd t) then eval (tru t) else eval (fls t)
-</programlisting>
-
+The standard defaulting rule (<ulink url="http://haskell.org/onlinereport/decls.html#sect4.3.4">Haskell Report, Section 4.3.4</ulink>)
+is extended thus: defaulting applies when all the unresolved constraints involve standard classes
+<emphasis>or</emphasis> <literal>IsString</literal>; and at least one is a numeric class
+<emphasis>or</emphasis> <literal>IsString</literal>.
</para></listitem>
-
-<listitem><para>
-You can use strictness annotations, in the obvious places
-in the constructor type:
+</itemizedlist>
+</para>
+<para>
+A small example:
<programlisting>
- data Term a where
- Lit :: !Int -> Term Int
- If :: Term Bool -> !(Term a) -> !(Term a) -> Term a
- Pair :: Term a -> Term b -> Term (a,b)
-</programlisting>
-</para></listitem>
+module Main where
-<listitem><para>
-You can use a <literal>deriving</literal> clause on a GADT-style data type
-declaration, but only if the data type could also have been declared in
-Haskell-98 syntax. For example, these two declarations are equivalent
-<programlisting>
- data Maybe1 a where {
- Nothing1 :: Maybe a ;
- Just1 :: a -> Maybe a
- } deriving( Eq, Ord )
+import GHC.Exts( IsString(..) )
- data Maybe2 a = Nothing2 | Just2 a
- deriving( Eq, Ord )
-</programlisting>
-This simply allows you to declare a vanilla Haskell-98 data type using the
-<literal>where</literal> form without losing the <literal>deriving</literal> clause.
-</para></listitem>
+newtype MyString = MyString String deriving (Eq, Show)
+instance IsString MyString where
+ fromString = MyString
-<listitem><para>
-Pattern matching causes type refinement. For example, in the right hand side of the equation
-<programlisting>
- eval :: Term a -> a
- eval (Lit i) = ...
-</programlisting>
-the type <literal>a</literal> is refined to <literal>Int</literal>. (That's the whole point!)
-A precise specification of the type rules is beyond what this user manual aspires to, but there is a paper
-about the ideas: "Wobbly types: practical type inference for generalised algebraic data types", on Simon PJ's home page.</para>
+greet :: MyString -> MyString
+greet "hello" = "world"
+greet other = other
-<para> The general principle is this: <emphasis>type refinement is only carried out based on user-supplied type annotations</emphasis>.
-So if no type signature is supplied for <literal>eval</literal>, no type refinement happens, and lots of obscure error messages will
-occur. However, the refinement is quite general. For example, if we had:
-<programlisting>
- eval :: Term a -> a -> a
- eval (Lit i) j = i+j
+main = do
+ print $ greet "hello"
+ print $ greet "fool"
</programlisting>
-the pattern match causes the type <literal>a</literal> to be refined to <literal>Int</literal> (because of the type
-of the constructor <literal>Lit</literal>, and that refinement also applies to the type of <literal>j</literal>, and
-the result type of the <literal>case</literal> expression. Hence the addition <literal>i+j</literal> is legal.
</para>
-</listitem>
-</itemizedlist>
+<para>
+Note that deriving <literal>Eq</literal> is necessary for the pattern matching
+to work since it gets translated into an equality comparison.
</para>
+</sect2>
-<para>Notice that GADTs generalise existential types. For example, these two declarations are equivalent:
-<programlisting>
- data T a = forall b. MkT b (b->a)
- data T' a where { MKT :: b -> (b->a) -> T' a }
-</programlisting>
-</para>
</sect1>
-
-<!-- ====================== End of Generalised algebraic data types ======================= -->
-
+<!-- ==================== End of type system extensions ================= -->
+
<!-- ====================== TEMPLATE HASKELL ======================= -->
<sect1 id="template-haskell">
(It would make sense to do so, but it's hard to implement.)
</para></listitem>
+ <listitem><para>
+ Furthermore, you can only run a function at compile time if it is imported
+ from another module <emphasis>that is not part of a mutually-recursive group of modules
+ that includes the module currently being compiled</emphasis>. For example, when compiling module A,
+ you can only run Template Haskell functions imported from B if B does not import A (directly or indirectly).
+ The reason should be clear: to run B we must compile and run A, but we are currently type-checking A.
+ </para></listitem>
+
<listitem><para>
The flag <literal>-ddump-splices</literal> shows the expansion of all top-level splices as they happen.
</para></listitem>
<!-- ==================== BANG PATTERNS ================= -->
-<sect1 id="sec-bang-patterns">
+<sect1 id="bang-patterns">
<title>Bang patterns
<indexterm><primary>Bang patterns</primary></indexterm>
</title>
Bang patterns are enabled by the flag <option>-fbang-patterns</option>.
</para>
-<sect2 id="sec-bang-patterns-informal">
+<sect2 id="bang-patterns-informal">
<title>Informal description of bang patterns
</title>
<para>
</sect2>
-<sect2 id="sec-bang-patterns-sem">
+<sect2 id="bang-patterns-sem">
<title>Syntax and semantics
</title>
<para>
</programlisting>
Is this a definition of the infix function "<literal>(!)</literal>",
or of the "<literal>f</literal>" with a bang pattern? GHC resolves this
-ambiguity inf favour of the latter. If you want to define
+ambiguity in favour of the latter. If you want to define
<literal>(!)</literal> with bang-patterns enabled, you have to do so using
prefix notation:
<programlisting>
<!-- ==================== ASSERTIONS ================= -->
-<sect1 id="sec-assertions">
+<sect1 id="assertions">
<title>Assertions
<indexterm><primary>Assertions</primary></indexterm>
</title>
<listitem>
<para>
- <function>length</function>
-</para>
-</listitem>
-<listitem>
-
-<para>
<function>++</function> (on its first argument)
</para>
</listitem>
GHCziBase.ZMZN GHCziBase.Char -> GHCziBase.ZMZN GHCziBase.Cha
r) ->
tpl2})
- (%note "foo"
+ (%note "bar"
eta);
</programlisting>
described in this section. All are exported by
<literal>GHC.Exts</literal>.</para>
+<sect2> <title>The <literal>seq</literal> function </title>
+<para>
+The function <literal>seq</literal> is as described in the Haskell98 Report.
+<programlisting>
+ seq :: a -> b -> b
+</programlisting>
+It evaluates its first argument to head normal form, and then returns its
+second argument as the result. The reason that it is documented here is
+that, despite <literal>seq</literal>'s polymorphism, its
+second argument can have an unboxed type, or
+can be an unboxed tuple; for example <literal>(seq x 4#)</literal>
+or <literal>(seq x (# p,q #))</literal>. This requires <literal>b</literal>
+to be instantiated to an unboxed type, which is not usually allowed.
+</para>
+</sect2>
+
<sect2> <title>The <literal>inline</literal> function </title>
<para>
The <literal>inline</literal> function is somewhat experimental.
look strict in <literal>y</literal> which would defeat the whole
purpose of <literal>par</literal>.
</para>
+<para>
+Like <literal>seq</literal>, the argument of <literal>lazy</literal> can have
+an unboxed type.
+</para>
+
</sect2>
<sect2> <title>The <literal>unsafeCoerce#</literal> function </title>
well-typed, but where Haskell's type system is not expressive enough to prove
that it is well typed.
</para>
+<para>
+The argument to <literal>unsafeCoerce#</literal> can have unboxed types,
+although extremely bad things will happen if you coerce a boxed type
+to an unboxed type.
+</para>
+
</sect2>
+
</sect1>
<sect1 id="generic-classes">
<title>Generic classes</title>
- <para>(Note: support for generic classes is currently broken in
- GHC 5.02).</para>
-
<para>
The ideas behind this extension are described in detail in "Derivable type classes",
Ralf Hinze and Simon Peyton Jones, Haskell Workshop, Montreal Sept 2000, pp94-105.
projects / ghc-hetmet.git / blobdiff