Add note about Template Haskell and mutual recursion

[ghc-hetmet.git] / docs / users_guide / glasgow_exts.xml

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 41bba18..fb2124e 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -241,6 +241,14 @@ documentation</ulink> describes all the libraries that come with GHC.
       </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
@@ -620,7 +628,7 @@ to write clunky would be to use case expressions:
 </para>
 
 <programlisting>
-clunky env var1 var1 = case lookup env var1 of
+clunky env var1 var2 = case lookup env var1 of
   Nothing -&gt; fail
   Just val1 -&gt; case lookup env var2 of
     Nothing -&gt; fail
@@ -645,7 +653,7 @@ Here is how I would write clunky:
 </para>
 
 <programlisting>
-clunky env var1 var1
+clunky env var1 var2
   | Just val1 &lt;- lookup env var1
   , Just val2 &lt;- lookup env var2
   = val1 + val2
@@ -4056,6 +4064,57 @@ pattern binding must have the same context.  For example, this is fine:
 </para>
 </sect2>
 
+<sect2 id="overloaded-strings">
+<title>Overloaded string literals
+</title>
+
+<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>
+class IsString a where
+    fromString :: String -> a
+</programlisting>
+And the only predefined instance is the obvious one to make strings work as usual:
+<programlisting>
+instance IsString [Char] where
+    fromString cs = cs
+</programlisting>
+</para>
+<para>
+A small example:
+<programlisting>
+newtype MyString = MyString String deriving (Eq, Show)
+instance IsString MyString where
+    fromString = MyString
+
+greet :: MyString -> MyString
+greet "hello" = "world"
+greet other = other
+
+main = do
+    print $ greet "hello"
+    print $ greet "fool"
+</programlisting>
+</para>
+<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>
+
 </sect1>
 <!-- ==================== End of type system extensions =================  -->
   
@@ -4167,6 +4226,14 @@ Tim Sheard is going to expand it.)
            (It would make sense to do so, but it's hard to implement.)
    </para></listitem>
 
+   <listitem><para>
+   Furthermore, the 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>
@@ -5899,12 +5966,6 @@ The following are good consumers:
 <listitem>
 
 <para>
- <function>length</function>
-</para>
-</listitem>
-<listitem>
-
-<para>
  <function>++</function> (on its first argument)
 </para>
 </listitem>