Document -XTypeHoles

Thanks to Thijs Alkemade for writing this documentation

2 files changed, 86 insertions, 0 deletions

diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index bc1c228e36..0e7ed23255 100644
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -1161,6 +1161,12 @@
             <entry>dynamic</entry>
             <entry><option>-</option></entry>
           </row>
+          <row>
+            <entry><option>-XTypeHoles</option></entry>
+            <entry>Enable <link linkend="type-holes">holes</link> in expressions.</entry>
+            <entry>dynamic</entry>
+            <entry><option>-</option></entry>
+          </row>
         </tbody>
       </tgroup>
     </informaltable>
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 1bbfaecc4b..aac9994633 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -7069,6 +7069,86 @@ If you supply a type signature, then the flag has no effect.
 </para>
 </sect2>
 
+<sect2 id="type-holes">
+<title>Type Holes</title>
+
+<para>Type hole support is enabled with the option
+<option>-XTypeHoles</option>.</para>
+
+<para>
+The goal of the type holes extension is not to change the type system, but to help with writing Haskell
+code. Type holes can be used to obtain extra information from the type checker, which might otherwise be hard
+to get.
+Normally, the type checker is used to decide if a module is well typed or not. Using GHCi,
+users can inspect the (inferred) type signatures of all top-level bindings. However, determining the
+type of a single term is still hard. Yet while writing code, it could be helpful to know the type of
+the term you're about to write.
+</para>
+
+<para>
+This extension allows special placeholders, written as <literal>_</literal>, to be used as an expression.
+During compilation these holes will generate an error message describing what type is expected there.
+The error includes helpful information about the origin of type variables and a list of local bindings
+that might help fill the hole with actual code.
+</para>
+
+<para>
+For example, compiling the following module with GHC:
+<programlisting>
+f :: a -> a
+f x = _
+</programlisting>
+Will fail with the following error:
+<programlisting>
+hole.hs:2:7:
+    Found hole `_' with type a
+    Where: `a' is a rigid type variable bound by
+               the type signature for f :: a -> a at hole.hs:1:6
+    Relevant bindings include
+      f :: a -> a (bound at hole.hs:2:1)
+      x :: a (bound at hole.hs:2:3)
+    In the expression: _
+    In an equation for `f': f x = _
+</programlisting>
+</para>
+
+<para>
+Multiple type holes can be used to find common type variables between expressions. For example:
+<programlisting>
+sum :: [Int] -> Int
+sum x = foldr _ _ _
+</programlisting>
+Shows:
+<programlisting>
+holes.hs:2:15:
+    Found hole `_' with type a0 -> Int -> Int
+    Where: `a0' is an ambiguous type variable
+    In the first argument of `foldr', namely `_'
+    In the expression: foldr _ _ _
+    In an equation for `sum': sum x = foldr _ _ _
+
+holes.hs:2:17:
+    Found hole `_' with type Int
+    In the second argument of `foldr', namely `_'
+    In the expression: foldr _ _ _
+    In an equation for `sum': sum x = foldr _ _ _
+
+holes.hs:2:19:
+    Found hole `_' with type [a0]
+    Where: `a0' is an ambiguous type variable
+    In the third argument of `foldr', namely `_'
+    In the expression: foldr _ _ _
+    In an equation for `sum': sum x = foldr _ _ _
+</programlisting>
+</para>
+
+<para>
+Holes work together well with <link linkend="defer-type-errors">deferring type errors to runtime</link>:
+with <literal>-fdefer-type-errors</literal>, the error from a hole is also deferred, effctively making the hole
+typecheck just like <literal>undefined</literal>, but with the added benefit that it will show its warning message
+if it gets evaluated. This way, other parts of the code can still be executed and tested.
+</para>
+</sect2>
 </sect1>
 <!-- ==================== End of type system extensions =================  -->