[commit: ghc] master: Document Quasi-quotes/list comprehension ambiguity (767ff7c)

[git at git.haskell.org]

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

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

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

commit 767ff7cab7fc2d27b66cdd25d551ccf9e9e7c51d
Author: Ben Gamari <bgamari.foss at gmail.com>
Date:   Fri Mar 11 10:38:42 2016 +0100

    Document Quasi-quotes/list comprehension ambiguity
    
    
    Test Plan: read it
    
    Reviewers: austin, goldfire
    
    Reviewed By: goldfire
    
    Subscribers: hvr, thomie
    
    Differential Revision: https://phabricator.haskell.org/D1981
    
    GHC Trac Issues: #11679


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

767ff7cab7fc2d27b66cdd25d551ccf9e9e7c51d
 docs/users_guide/glasgow_exts.rst | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index 454c73e..dd714ec 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -1873,7 +1873,15 @@ The following syntax is stolen:
 
     Stolen by: :ghc-flag:`-XImplicitParams`
 
-``[|``, ``[e|``, ``[p|``, ``[d|``, ``[t|``, ``$(``, ``$$(``, ``[||``, ``[e||``, ``$varid``, ``$$varid``
+``[|``, ``[e|``, ``[p|``, ``[d|``, ``[t|``, ``[||``, ``[e||``
+    .. index::
+       single: Quasi-quotes
+
+    Stolen by: :ghc-flag:`-XQuasiQuotes`. Moreover, this introduces an ambiguity
+    with list comprehension syntax. See
+    :ref:`quasi-quotes-list-comprehension-ambiguity` for details.
+
+``$(``, ``$$(``, ``$varid``, ``$$varid``
     .. index::
        single: Template Haskell
 
@@ -9985,6 +9993,24 @@ Here are the salient features
    quasi-quotes do not cause a declaration group break. See
    :ref:`th-syntax` for more information.
 
+.. _quasi-quotes-list-comprehension-ambiguity:
+
+.. warning::
+
+    .. index::
+        single: quasi-quotes; ambiguity with list comprehensions
+        single: list comprehensions; ambiguity with quasi-quotes
+
+    :ghc-flag:`-XQuasiQuotes` introduces an unfortunate ambiguity with list
+    comprehension syntax. Consider the following, ::
+
+        let x = [v| v <- [0..10]]
+
+    Without :ghc-flag:`-XQuasiQuotes` this is parsed as a list comprehension.
+    With :ghc-flag:`-XQuasiQuotes` this is parsed as a quasi-quote; however,
+    this parse will fail due to the lack of a closing ``|]``. See
+    :ghc-ticket:`11679`.
+
 The example below shows quasi-quotation in action. The quoter ``expr``
 is bound to a value of type ``QuasiQuoter`` defined in module ``Expr``.
 The example makes use of an antiquoted variable ``n``, indicated by the