</varlistentry>
<varlistentry>
+ <term>Data types with no constructors</term>
+ <listitem>
+ <para>See <xref LinkEnd="nullary-types">.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>Parallel list comprehensions</term>
<listitem>
<para>An extension to the list comprehension syntax to support
<varlistentry>
<term>Generic classes:</term>
<listitem>
+ <para>(Note: support for generic classes is currently broken
+ in GHC 5.02).</para>
+
<para>Generic class declarations allow you to define a class
whose methods say how to work over an arbitrary data type.
Then it's really easy to make any new type into an instance of
</sect1>
+<sect1 id="nullary-types">
+<title>Data types with no constructors</title>
+
+<para>With the <option>-fglasgow-exts</option> flag, GHC lets you declare
+a data type with no constructors. For example:</para>
+<programlisting>
+ data S -- S :: *
+ data T a -- T :: * -> *
+</programlisting>
+<para>Syntactically, the declaration lacks the "= constrs" part. The
+type can be parameterised, but only over ordinary types, of kind *; since
+Haskell does not have kind signatures, you cannot parameterise over higher-kinded
+types.</para>
+
+<para>Such data types have only one value, namely bottom.
+Nevertheless, they can be useful when defining "phantom types".</para>
+</sect1>
+
<sect1 id="pattern-guards">
<title>Pattern guards</title>
</sect1>
- <sect1 id="sec-ffi">
- <title>The foreign interface</title>
-
- <para>The foreign interface consists of the following components:</para>
-
- <itemizedlist>
- <listitem>
- <para>The Foreign Function Interface language specification
- (included in this manual, in <xref linkend="ffi">).</para>
- </listitem>
-
- <listitem>
- <para>The <literal>Foreign</literal> module (see <xref
- linkend="sec-Foreign">) collects together several interfaces
- which are useful in specifying foreign language
- interfaces, including the following:</para>
-
- <itemizedlist>
- <listitem>
- <para>The <literal>ForeignObj</literal> module (see <xref
- linkend="sec-ForeignObj">), for managing pointers from
- Haskell into the outside world.</para>
- </listitem>
-
- <listitem>
- <para>The <literal>StablePtr</literal> module (see <xref
- linkend="sec-stable-pointers">), for managing pointers
- into Haskell from the outside world.</para>
- </listitem>
-
- <listitem>
- <para>The <literal>CTypes</literal> module (see <xref
- linkend="sec-CTypes">) gives Haskell equivalents for the
- standard C datatypes, for use in making Haskell bindings
- to existing C libraries.</para>
- </listitem>
-
- <listitem>
- <para>The <literal>CTypesISO</literal> module (see <xref
- linkend="sec-CTypesISO">) gives Haskell equivalents for C
- types defined by the ISO C standard.</para>
- </listitem>
-
- <listitem>
- <para>The <literal>Storable</literal> library, for
- primitive marshalling of data types between Haskell and
- the foreign language.</para>
- </listitem>
- </itemizedlist>
-
- </listitem>
- </itemizedlist>
-
-<para>The following sections also give some hints and tips on the use
-of the foreign function interface in GHC.</para>
-
-<sect2 id="glasgow-foreign-headers">
-<title>Using function headers
-</title>
-
-<para>
-<indexterm><primary>C calls, function headers</primary></indexterm>
-</para>
-
-<para>
-When generating C (using the <option>-fvia-C</option> directive), one can assist the
-C compiler in detecting type errors by using the <Command>-#include</Command> directive
-to provide <filename>.h</filename> files containing function headers.
-</para>
-
-<para>
-For example,
-</para>
-
-<para>
-
-<programlisting>
-#include "HsFFI.h"
-
-void initialiseEFS (HsInt size);
-HsInt terminateEFS (void);
-HsForeignObj emptyEFS(void);
-HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x);
-HsInt lookupEFS (HsForeignObj a, HsInt i);
-</programlisting>
-</para>
-
- <para>The types <literal>HsInt</literal>,
- <literal>HsForeignObj</literal> etc. are described in <xref
- linkend="sec-mapping-table">.</para>
-
- <para>Note that this approach is only
- <emphasis>essential</emphasis> for returning
- <literal>float</literal>s (or if <literal>sizeof(int) !=
- sizeof(int *)</literal> on your architecture) but is a Good
- Thing for anyone who cares about writing solid code. You're
- crazy not to do it.</para>
-
-</sect2>
-
-</sect1>
-
<sect1 id="multi-param-type-classes">
<title>Multi-parameter type classes
</title>
</para>
<para>
+ Pattern type signatures are completely orthogonal to ordinary, separate
+type signatures. The two can be used independently or together.
At ordinary type signatures, such as that for <VarName>ys</VarName>, any type variables
mentioned in the type signature <emphasis>that are not in scope</emphasis> are
implicitly universally quantified. (If there are no type variables in
</para>
<sect2>
+<title>What a pattern type signature means</title>
+<para>
+A type variable brought into scope by a pattern type signature is simply
+the name for a type. The restriction they express is that all occurrences
+of the same name mean the same type. For example:
+<programlisting>
+ f :: [Int] -> Int -> Int
+ f (xs::[a]) (y::a) = (head xs + y) :: a
+</programlisting>
+The pattern type signatures on the left hand side of
+<literal>f</literal> express the fact that <literal>xs</literal>
+must be a list of things of some type <literal>a</literal>; and that <literal>y</literal>
+must have this same type. The type signature on the expression <literal>(head xs)</literal>
+specifies that this expression must have the same type <literal>a</literal>.
+<emphasis>There is no requirement that the type named by "<literal>a</literal>" is
+in fact a type variable</emphasis>. Indeed, in this case, the type named by "<literal>a</literal>" is
+<literal>Int</literal>. (This is a slight liberalisation from the original rather complex
+rules, which specified that a pattern-bound type variable should be universally quantified.)
+For example, all of these are legal:</para>
+
+<programlisting>
+ t (x::a) (y::a) = x+y*2
+
+ f (x::a) (y::b) = [x,y] -- a unifies with b
+
+ g (x::a) = x + 1::Int -- a unifies with Int
+
+ h x = let k (y::a) = [x,y] -- a is free in the
+ in k x -- environment
+
+ k (x::a) True = ... -- a unifies with Int
+ k (x::Int) False = ...
+
+ w :: [b] -> [b]
+ w (x::a) = x -- a unifies with [b]
+</programlisting>
+
+</sect2>
+
+<sect2>
<title>Scope and implicit quantification</title>
<para>
<listitem>
<para>
- All the type variables mentioned in the patterns for a single
-function definition equation, that are not already in scope,
-are brought into scope by the patterns. We describe this set as
-the <emphasis>type variables bound by the equation</emphasis>.
-
+All the type variables mentioned in a pattern,
+that are not already in scope,
+are brought into scope by the pattern. We describe this set as
+the <emphasis>type variables bound by the pattern</emphasis>.
+For example:
+<programlisting>
+ f (x::a) = let g (y::(a,b)) = fst y
+ in
+ g (x,True)
+</programlisting>
+The pattern <literal>(x::a)</literal> brings the type variable
+<literal>a</literal> into scope, as well as the term
+variable <literal>x</literal>. The pattern <literal>(y::(a,b))</literal>
+contains an occurrence of the already-in-scope type variable <literal>a</literal>,
+and brings into scope the type variable <literal>b</literal>.
</para>
</listitem>
-<listitem>
+<listitem>
<para>
The type variables thus brought into scope may be mentioned
in ordinary type signatures or pattern type signatures anywhere within
</para>
</listitem>
-<listitem>
+<listitem>
<para>
In ordinary type signatures, any type variable mentioned in the
signature that is in scope is <emphasis>not</emphasis> universally quantified.
</para>
</listitem>
+
<listitem>
<para>
Ordinary type signatures do not bring any new type variables
into scope (except in the type signature itself!). So this is illegal:
-
<programlisting>
f :: a -> a
f x = x::a
</programlisting>
-
It's illegal because <VarName>a</VarName> is not in scope in the body of <function>f</function>,
so the ordinary signature <literal>x::a</literal> is equivalent to <literal>x::forall a.a</literal>;
and that is an incorrect typing.
</para>
</listitem>
-<listitem>
+<listitem>
<para>
There is no implicit universal quantification on pattern type
signatures, nor may one write an explicit <literal>forall</literal> type in a pattern
</para>
</listitem>
-<listitem>
+<listitem>
<para>
The type variables in the head of a <literal>class</literal> or <literal>instance</literal> declaration
</sect2>
<sect2>
-<title>Polymorphism</title>
-
-<para>
-
-<itemizedlist>
-<listitem>
-
-<para>
- Pattern type signatures are completely orthogonal to ordinary, separate
-type signatures. The two can be used independently or together. There is
-no scoping associated with the names of the type variables in a separate type signature.
-
-
-<programlisting>
- f :: [a] -> [a]
- f (xs::[b]) = reverse xs
-</programlisting>
-
-
-</para>
-</listitem>
-<listitem>
-
-<para>
- The function must be polymorphic in the type variables
-bound by all its equations. Operationally, the type variables bound
-by one equation must not:
-
-
-<itemizedlist>
-<listitem>
-
-<para>
- Be unified with a type (such as <literal>Int</literal>, or <literal>[a]</literal>).
-</para>
-</listitem>
-<listitem>
-
-<para>
- Be unified with a type variable free in the environment.
-</para>
-</listitem>
-<listitem>
-
-<para>
- Be unified with each other. (They may unify with the type variables
-bound by another equation for the same function, of course.)
-</para>
-</listitem>
-
-</itemizedlist>
-
-
-For example, the following all fail to type check:
-
-
-<programlisting>
- f (x::a) (y::b) = [x,y] -- a unifies with b
-
- g (x::a) = x + 1::Int -- a unifies with Int
-
- h x = let k (y::a) = [x,y] -- a is free in the
- in k x -- environment
-
- k (x::a) True = ... -- a unifies with Int
- k (x::Int) False = ...
-
- w :: [b] -> [b]
- w (x::a) = x -- a unifies with [b]
-</programlisting>
-
-
-</para>
-</listitem>
-<listitem>
-
-<para>
- The pattern-bound type variable may, however, be constrained
-by the context of the principal type, thus:
-
-
-<programlisting>
- f (x::a) (y::a) = x+y*2
-</programlisting>
-
-
-gets the inferred type: <literal>forall a. Num a => a -> a -> a</literal>.
-</para>
-</listitem>
-
-</itemizedlist>
-
-</para>
-
-</sect2>
-
-<sect2>
<title>Result type signatures</title>
<para>
</sect2>
<sect2>
-<title>Pattern signatures on other constructs</title>
+<title>Where a pattern type signature can occur</title>
<para>
-
+A pattern type signature can occur in any pattern, but there
+are restrictions on pattern bindings:
<itemizedlist>
-<listitem>
+<listitem>
<para>
- A pattern type signature can be on an arbitrary sub-pattern, not
-just on a variable:
+A pattern type signature can be on an arbitrary sub-pattern, not
+ust on a variable:
<programlisting>
Pattern type signatures, including the result part, can be used
in lambda abstractions:
-
<programlisting>
(\ (x::a, y) :: a -> x)
</programlisting>
-
-
-Type variables bound by these patterns must be polymorphic in
-the sense defined above.
-For example:
-
-
-<programlisting>
- f1 (x::c) = f1 x -- ok
- f2 = \(x::c) -> f2 x -- not ok
-</programlisting>
-
-
-Here, <function>f1</function> is OK, but <function>f2</function> is not, because <VarName>c</VarName> gets unified
-with a type variable free in the environment, in this
-case, the type of <function>f2</function>, which is in the environment when
-the lambda abstraction is checked.
-
</para>
</listitem>
<listitem>
case e of { (x::a, y) :: a -> x }
</programlisting>
+</para>
+</listitem>
-The pattern-bound type variables must, as usual,
-be polymorphic in the following sense: each case alternative,
-considered as a lambda abstraction, must be polymorphic.
-Thus this is OK:
-
-
-<programlisting>
- case (True,False) of { (x::a, y) -> x }
-</programlisting>
-
-
-Even though the context is that of a pair of booleans,
-the alternative itself is polymorphic. Of course, it is
-also OK to say:
+<listitem>
+<para>
+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>
- case (True,False) of { (x::Bool, y) -> x }
+ \ x :: a -> b -> x
</programlisting>
</para>
</listitem>
+
<listitem>
<para>
-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:
+ Pattern type signatures can bind existential type variables.
+For example:
<programlisting>
- \ x :: a -> b -> x
+ data T = forall a. MkT [a]
+
+ f :: T -> T
+ f (MkT [t::a]) = MkT t3
+ where
+ t3::[a] = [t,t,t]
</programlisting>
</para>
</listitem>
+
+
<listitem>
<para>
- Pattern type signatures that bind new type variables
+Pattern type signatures that bind new type variables
may not be used in pattern bindings at all.
So this is illegal:
</sect2>
-<sect2>
-<title>Existentials</title>
-
-<para>
-
-<itemizedlist>
-<listitem>
-
-<para>
- Pattern type signatures can bind existential type variables.
-For example:
-
-
-<programlisting>
- data T = forall a. MkT [a]
-
- f :: T -> T
- f (MkT [t::a]) = MkT t3
- where
- t3::[a] = [t,t,t]
-</programlisting>
+</sect1>
-</para>
-</listitem>
+ <sect1 id="pragmas">
+ <title>Pragmas</title>
-</itemizedlist>
+ <indexterm><primary>pragma</primary></indexterm>
-</para>
+ <para>GHC supports several pragmas, or instructions to the
+ compiler placed in the source code. Pragmas don't normally affect
+ the meaning of the program, but they might affect the efficiency
+ of the generated code.</para>
-</sect2>
+ <para>Pragmas all take the form
-</sect1>
+<literal>{-# <replaceable>word</replaceable> ... #-}</literal>
-<sect1 id="pragmas">
-<title>Pragmas
-</title>
-
-<para>
-GHC supports several pragmas, or instructions to the compiler placed
-in the source code. Pragmas don't affect the meaning of the program,
-but they might affect the efficiency of the generated code.
-</para>
+ where <replaceable>word</replaceable> indicates the type of
+ pragma, and is followed optionally by information specific to that
+ type of pragma. Case is ignored in
+ <replaceable>word</replaceable>. The various values for
+ <replaceable>word</replaceable> that GHC understands are described
+ in the following sections; any pragma encountered with an
+ unrecognised <replaceable>word</replaceable> is (silently)
+ ignored.</para>
<sect2 id="inline-pragma">
<title>INLINE pragma
<title>NOINLINE pragma
</title>
-<para>
<indexterm><primary>NOINLINE pragma</primary></indexterm>
-<indexterm><primary>pragma, NOINLINE</primary></indexterm>
-</para>
+<indexterm><primary>pragma</primary><secondary>NOINLINE</secondary></indexterm>
+<indexterm><primary>NOTINLINE pragma</primary></indexterm>
+<indexterm><primary>pragma</primary><secondary>NOTINLINE</secondary></indexterm>
<para>
-The <literal>NOINLINE</literal> pragma does exactly what you'd expect: it stops the
-named function from being inlined by the compiler. You shouldn't ever
-need to do this, unless you're very cautious about code size.
+The <literal>NOINLINE</literal> pragma does exactly what you'd expect:
+it stops the named function from being inlined by the compiler. You
+shouldn't ever need to do this, unless you're very cautious about code
+size.
</para>
+<para><literal>NOTINLINE</literal> is a synonym for
+<literal>NOINLINE</literal> (<literal>NOTINLINE</literal> is specified
+by Haskell 98 as the standard way to disable inlining, so it should be
+used if you want your code to be portable).</para>
+
</sect2>
<sect2 id="specialize-pragma">
</sect2>
+<sect2 id="deprecated-pragma">
+<title>DEPRECATED pragma</title>
+
+<para>
+The DEPRECATED pragma lets you specify that a particular function, class, or type, is deprecated.
+There are two forms.
+</para>
+<itemizedlist>
+<listitem><para>
+You can deprecate an entire module thus:</para>
+<programlisting>
+ module Wibble {-# DEPRECATED "Use Wobble instead" #-} where
+ ...
+</programlisting>
+<para>
+When you compile any module that import <literal>Wibble</literal>, GHC will print
+the specified message.</para>
+</listitem>
+
+<listitem>
+<para>
+You can deprecate a function, class, or type, with the following top-level declaration:
+</para>
+<programlisting>
+ {-# DEPRECATED f, C, T "Don't use these" #-}
+</programlisting>
+<para>
+When you compile any module that imports and uses any of the specifed entities,
+GHC will print the specified message.
+</para>
+</listitem>
+</itemizedlist>
+<para>You can suppress the warnings with the flag <option>-fno-warn-deprecations</option>.</para>
+
+</sect2>
+
</sect1>
<sect1 id="rewrite-rules">
<function>++</function>
</para>
</listitem>
-<listitem>
+<listitem>
<para>
<function>map</function>
</para>
</listitem>
-<listitem>
+<listitem>
<para>
<function>filter</function>
</para>
<function>++</function> (on its first argument)
</para>
</listitem>
+
<listitem>
+<para>
+ <function>foldr</function>
+</para>
+</listitem>
+<listitem>
<para>
<function>map</function>
</para>
<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.
<para>To use generics you need to</para>
<itemizedlist>
<listitem>
- <para>Use the <option>-fgenerics</option> flag.</para>
+ <para>Use the flags <option>-fglasgow-exts</option> (to enable the extra syntax),
+ <option>-fgenerics</option> (to generate extra per-data-type code),
+ and <option>-package lang</option> (to make the <literal>Generics</literal> library
+ available. </para>
</listitem>
<listitem>
<para>Import the module <literal>Generics</literal> from the
<programlisting>
class Foo a where
op1 :: a -> Bool
- op {| a :*: b |} (Inl x) = True
+ op1 {| a :*: b |} (x :*: y) = True
op2 :: a -> Bool
- op {| p :*: q |} (Inr y) = False
+ op2 {| p :*: q |} (x :*: y) = False
</programlisting>
(The reason for this restriction is that we gather all the equations for a particular type consructor
into a single generic instance declaration.)
projects / ghc-hetmet.git / blobdiff