</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
+ <literal>zipWith</literal>-like functionality. See <xref
+ linkend="parallel-list-comprehensions">.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>Foreign calling:</term>
<listitem>
<para>Just what it sounds like. We provide
<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
"<literal>Prelude.fromInteger 1</literal>", which is what
the Haskell Report specifies. So the
<option>-fno-implicit-prelude</option> flag causes the
- following pieces of built-in syntax to refer to whatever
- is in scope, not the Prelude versions:</para>
+ following pieces of built-in syntax to refer to <emphasis>whatever
+ is in scope</emphasis>, not the Prelude versions:</para>
<itemizedlist>
<listitem>
<listitem>
<para>In an n+k pattern, the standard Prelude
- <literal>Ord</literal> class is used for comparison,
+ <literal>Ord</literal> class is still used for comparison,
but the necessary subtraction uses whatever
"<literal>(-)</literal>" is in scope (not
"<literal>Prelude.(-)</literal>").</para>
</listitem>
</itemizedlist>
+ <para>Note: Negative literals, such as <literal>-3</literal>, are
+ specified by (a careful reading of) the Haskell Report as
+ meaning <literal>Prelude.negate (Prelude.fromInteger 3)</literal>.
+ However, GHC deviates from this slightly, and treats them as meaning
+ <literal>fromInteger (-3)</literal>. One particular effect of this
+ slightly-non-standard reading is that there is no difficulty with
+ the literal <literal>-2147483648</literal> at type <literal>Int</literal>;
+ it means <literal>fromInteger (-2147483648)</literal>. The strict interpretation
+ would be <literal>negate (fromInteger 2147483648)</literal>,
+ and the call to <literal>fromInteger</literal> would overflow
+ (at type <literal>Int</literal>, remember).
+ </para>
+
</listitem>
</varlistentry>
</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>
</para>
</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>
+ <sect1 id="parallel-list-comprehensions">
+ <title>Parallel List Comprehensions</title>
+ <indexterm><primary>list comprehensions</primary><secondary>parallel</secondary>
+ </indexterm>
+ <indexterm><primary>parallel list comprehensions</primary>
+ </indexterm>
-<para>The following sections also give some hints and tips on the use
-of the foreign function interface in GHC.</para>
+ <para>Parallel list comprehensions are a natural extension to list
+ comprehensions. List comprehensions can be thought of as a nice
+ syntax for writing maps and filters. Parallel comprehensions
+ extend this to include the zipWith family.</para>
-<sect2 id="glasgow-foreign-headers">
-<title>Using function headers
-</title>
+ <para>A parallel list comprehension has multiple independent
+ branches of qualifier lists, each separated by a `|' symbol. For
+ example, the following zips together two lists:</para>
-<para>
-<indexterm><primary>C calls, function headers</primary></indexterm>
-</para>
+<programlisting>
+ [ (x, y) | x <- xs | y <- ys ]
+</programlisting>
-<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>The behavior of parallel list comprehensions follows that of
+ zip, in that the resulting list will have the same length as the
+ shortest branch.</para>
-<para>
-For example,
-</para>
+ <para>We can define parallel list comprehensions by translation to
+ regular comprehensions. Here's the basic idea:</para>
-<para>
+ <para>Given a parallel comprehension of the form: </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);
+ [ e | p1 <- e11, p2 <- e12, ...
+ | q1 <- e21, q2 <- e22, ...
+ ...
+ ]
</programlisting>
-</para>
- <para>The types <literal>HsInt</literal>,
- <literal>HsForeignObj</literal> etc. are described in <xref
- linkend="sec-mapping-table">.</para>
+ <para>This will be translated to: </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>
+<programlisting>
+ [ e | ((p1,p2), (q1,q2), ...) <- zipN [(p1,p2) | p1 <- e11, p2 <- e12, ...]
+ [(q1,q2) | q1 <- e21, q2 <- e22, ...]
+ ...
+ ]
+</programlisting>
-</sect2>
+ <para>where `zipN' is the appropriate zip for the given number of
+ branches.</para>
-</sect1>
+ </sect1>
<sect1 id="multi-param-type-classes">
<title>Multi-parameter type classes
</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
any operator starting in a colon as an infix type constructor). Also note that
the type constructors are not exactly as in the paper (Unit instead of 1, etc).
Finally, note that the syntax of the type patterns in the class declaration
-uses "<literal>{|</literal>" and "<literal>{|</literal>" brackets; curly braces
+uses "<literal>{|</literal>" and "<literal>|}</literal>" brackets; curly braces
alone would ambiguous when they appear on right hand sides (an extension we
anticipate wanting).
</para>
<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