[commit: ghc] master: Update manual for pattern splices (#1476) (cfa574c)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/cfa574cea30b411080de5d641309bdf135ed9be5/ghc

>---------------------------------------------------------------

commit cfa574cea30b411080de5d641309bdf135ed9be5
Author: Richard Eisenberg <eir at cis.upenn.edu>
Date:   Fri Nov 21 10:51:38 2014 -0500

    Update manual for pattern splices (#1476)


>---------------------------------------------------------------

cfa574cea30b411080de5d641309bdf135ed9be5
 docs/users_guide/glasgow_exts.xml | 55 ++++++++++++++++++++++++++++++---------
 1 file changed, 42 insertions(+), 13 deletions(-)

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index a21e677..f73a1d9 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -8785,25 +8785,54 @@ h z = z-1
 
 	    <listitem>
 	      <para>
-		Binders are lexically scoped. For example, consider the
-		following code, where a value <literal>g</literal> of type
-		<literal>Bool -> Q Pat</literal> is in scope, having been
-		imported from another module
+		Outermost pattern splices may bind variables. By "outermost" here, we refer to
+		a pattern splice that occurs outside of any quotation brackets. For example,
+
 <programlisting>
-y :: Int
-y = 7
+mkPat :: Bool -> Q Pat
+mkPat True  = [p| (x, y) |]
+mkPat False = [p| (y, x) |]
 
-f :: Int -> Int -> Int
-f n = \ $(g True) -> y+n
+-- in another module:
+foo :: (Char, String) -> String
+foo $(mkPat True) = x : y
+
+bar :: (String, Char) -> String
+bar $(mkPat False) = x : y
+</programlisting>
+	      </para>
+	    </listitem>
+
+
+	    <listitem>
+	      <para>
+		Nested pattern splices do <emphasis>not</emphasis> bind variables.
+		By "nested" here, we refer to a pattern splice occurring within a
+		quotation bracket. Continuing the example from the last bullet:
+
+<programlisting>
+baz :: Bool -> Q Exp
+baz b = [| quux $(mkPat b) = x + y |]
 </programlisting>
-                The <literal>y</literal> in the right-hand side of
-                <literal>f</literal> refers to the top-level <literal>y =
-                7</literal>, even if the pattern splice <literal>$(g
-                n)</literal> also generates a binder <literal>y</literal>.
+
+                would fail with <literal>x</literal> and <literal>y</literal>
+		being out of scope.
 	      </para>
 
 	      <para>
-		Note that a pattern quasiquoter <emphasis>may</emphasis>
+		The difference in treatment of outermost and nested pattern splices is
+		because outermost splices are run at compile time. GHC can then use
+		the result of running the splice when analyzing the expressions within
+		the pattern's scope. Nested splices, on the other hand, are <emphasis>not</emphasis>
+		run at compile time; they are run when the bracket is spliced in, sometime later.
+		Since nested pattern splices may refer to local variables, there is no way for GHC
+		to know, at splice compile time, what variables are bound, so it binds none.
+	      </para>
+	    </listitem>
+
+	    <listitem>
+	      <para>
+		A pattern quasiquoter <emphasis>may</emphasis>
 		generate binders that scope over the right-hand side of a
 		definition because these binders are in scope lexically. For
 		example, given a quasiquoter <literal>haskell</literal> that