<varlistentry>
<term>
+ <option>-XMagicHash</option>:
+ </term>
+ <listitem>
+ <para> Allow "#" as a <link linkend="magic-hash">postfix modifier on identifiers</link>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<option>-XMonomorphismRestriction</option>,<option>-XMonoPatBinds</option>:
</term>
<listitem>
<varlistentry>
<term>
+ <option>-XRank2Types</option>
+ <indexterm><primary><option>-XRank2Types</option></primary></indexterm>
+ </term>
+ <term>
+ <option>-XRankNTypes</option>
+ <indexterm><primary><option>-XRankNTypes</option></primary></indexterm>
+ </term>
+ <term>
+ <option>-XPolymorphicComponents</option>
+ <indexterm><primary><option>-XPolymorphicComponents</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para> These flags control higher-rank polymorphism.
+ See <xref linkend="universal-quantification"/>.</para>
+ <para>New reserved words: <literal>forall</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-XLiberalTypeSynonyms</option>
+ <indexterm><primary><option>-XLiberalTypeSynonyms</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para> Allow more liberal type synonyms.
+ See <xref linkend="type-synonyms"/>.</para>
+ <para>New reserved words: <literal>forall</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<option>-XOverlappingInstances</option>
<indexterm><primary><option>-XOverlappingInstances</option></primary></indexterm>
</term>
<indexterm><primary><option>-fcontext-stack</option></primary></indexterm>
</term>
<listitem>
- <para> See <xref linkend="instance-decls"/>. Only relevant
- if you also use <option>-fglasgow-exts</option>.</para>
+ <para> See <xref linkend="instance-decls"/>. </para>
</listitem>
</varlistentry>
<sect1 id="primitives">
<title>Unboxed types and primitive operations</title>
-<para>GHC is built on a raft of primitive data types and operations.
+<para>GHC is built on a raft of primitive data types and operations;
+"primitive" in the sense that they cannot be defined in Haskell itself.
While you really can use this stuff to write fast code,
we generally find it a lot less painful, and more satisfying in the
long run, to use higher-level language features and libraries. With
unboxed version in any case. And if it isn't, we'd like to know
about it.</para>
-<para>We do not currently have good, up-to-date documentation about the
-primitives, perhaps because they are mainly intended for internal use.
-There used to be a long section about them here in the User Guide, but it
-became out of date, and wrong information is worse than none.</para>
-
-<para>The Real Truth about what primitive types there are, and what operations
-work over those types, is held in the file
-<filename>compiler/prelude/primops.txt.pp</filename>.
-This file is used directly to generate GHC's primitive-operation definitions, so
-it is always correct! It is also intended for processing into text.</para>
-
-<para>Indeed,
-the result of such processing is part of the description of the
- <ulink
- url="http://www.haskell.org/ghc/docs/papers/core.ps.gz">External
- Core language</ulink>.
-So that document is a good place to look for a type-set version.
-We would be very happy if someone wanted to volunteer to produce an XML
-back end to the program that processes <filename>primops.txt</filename> so that
-we could include the results here in the User Guide.</para>
-
-<para>What follows here is a brief summary of some main points.</para>
+<para>All these primitive data types and operations are exported by the
+library <literal>GHC.Prim</literal>, for which there is
+<ulink url="../libraries/base/GHC.Prim.html">detailed online documentation</ulink>.
+(This documentation is generated from the file <filename>compiler/prelude/primops.txt.pp</filename>.)
+</para>
+<para>
+If you want to mention any of the primitive data types or operations in your
+program, you must first import <literal>GHC.Prim</literal> to bring them
+into scope. Many of them have names ending in "#", and to mention such
+names you need the <option>-XMagicHash</option> extension (<xref linkend="magic-hash"/>).
+</para>
+
+<para>The primops make extensive use of <link linkend="glasgow-unboxed">unboxed types</link>
+and <link linkend="unboxed-tuples">unboxed tuples</link>, which
+we briefly summarise here. </para>
<sect2 id="glasgow-unboxed">
<title>Unboxed types
know and love—usually one instruction.
</para>
-<para> For some primitive types we have special syntax for literals.
-Anything that would be an integer lexeme followed by a
-<literal>#</literal> is an <literal>Int#</literal> literal, e.g.
-<literal>32#</literal> and <literal>-0x3A#</literal>. Likewise,
-any non-negative integer literal followed by
-<literal>##</literal> is a <literal>Word#</literal> literal.
-Likewise, any floating point literal followed by a
-<literal>#</literal> is a <literal>Float#</literal> literal, and
-followed by <literal>##</literal> is a
-<literal>Double#</literal>. Finally, a string literal followed by a
-<literal>#</literal>, e.g. <literal>"foo"#</literal>,
-is a <literal>Addr#</literal> literal.
-</para>
-
<para>
Primitive (unboxed) types cannot be defined in Haskell, and are
therefore built into the language and compiler. Primitive types are
always unlifted; that is, a value of a primitive type cannot be
-bottom. We use the convention that primitive types, values, and
-operations have a <literal>#</literal> suffix.
+bottom. We use the convention (but it is only a convention)
+that primitive types, values, and
+operations have a <literal>#</literal> suffix (see <xref linkend="magic-hash"/>).
+For some primitive types we have special syntax for literals, also
+described in the <link linkend="magic-hash">same section</link>.
</para>
<para>
<sect1 id="syntax-extns">
<title>Syntactic extensions</title>
+ <sect2 id="magic-hash">
+ <title>The magic hash</title>
+ <para>The language extension <option>-XMagicHash</option> allows "#" as a
+ postfix modifier to identifiers. Thus, "x#" is a valid variable, and "T#" is
+ a valid type constructor or data constructor.</para>
+
+ <para>The hash sign does not change sematics at all. We tend to use variable
+ names ending in "#" for unboxed values or types (e.g. <literal>Int#</literal>),
+ but there is no requirement to do so; they are just plain ordinary variables.
+ Nor does the <option>-XMagicHash</option> extension bring anything into scope.
+ For example, to bring <literal>Int#</literal> into scope you must
+ import <literal>GHC.Prim</literal> (see <xref linkend="primitives"/>);
+ the <option>-XMagicHash</option> extension
+ then allows you to <emphasis>refer</emphasis> to the <literal>Int#</literal>
+ that is now in scope.</para>
+ <para> The <option>-XMagicHash</option> also enables some new forms of literals (see <xref linkend="glasgow-unboxed"/>):
+ <itemizedlist>
+ <listitem><para> <literal>'x'#</literal> has type <literal>Char#</literal></para> </listitem>
+ <listitem><para> <literal>"foo"#</literal> has type <literal>Addr#</literal></para> </listitem>
+ <listitem><para> <literal>3#</literal> has type <literal>Int#</literal>. In general,
+ any Haskell 98 integer lexeme followed by a <literal>#</literal> is an <literal>Int#</literal> literal, e.g.
+ <literal>-0x3A#</literal> as well as <literal>32#</literal></para>.</listitem>
+ <listitem><para> <literal>3##</literal> has type <literal>Word#</literal>. In general,
+ any non-negative Haskell 98 integer lexeme followed by <literal>##</literal>
+ is a <literal>Word#</literal>. </para> </listitem>
+ <listitem><para> <literal>3.2#</literal> has type <literal>Float#</literal>.</para> </listitem>
+ <listitem><para> <literal>3.2##</literal> has type <literal>Double#</literal></para> </listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+
<!-- ====================== HIERARCHICAL MODULES ======================= -->
+
<sect2 id="hierarchical-modules">
<title>Hierarchical Modules</title>
<title>Liberalised type synonyms</title>
<para>
-Type synonyms are like macros at the type level, and
+Type synonyms are like macros at the type level, but Haskell 98 imposes many rules
+on individual synonym declarations.
+With the <option>-XLiberalTypeSynonyms</option> extension,
GHC does validity checking on types <emphasis>only after expanding type synonyms</emphasis>.
-That means that GHC can be very much more liberal about type synonyms than Haskell 98:
+That means that GHC can be very much more liberal about type synonyms than Haskell 98.
+
<itemizedlist>
<listitem> <para>You can write a <literal>forall</literal> (including overloading)
in a type synonym, thus:
</listitem>
<listitem><para>
-You can write an unboxed tuple in a type synonym:
+If you also use <option>-XUnboxedTuples</option>,
+you can write an unboxed tuple in a type synonym:
<programlisting>
type Pr = (# Int, Int #)
projects / ghc-hetmet.git / blobdiff