Add (#<|) and deprecate its alias (<|#)

Previously the documentation stated that `(#<|)` was not supported by the
parser. It turns out it is a silly interaction with `-XUnboxedTuples`.
Adding extra spacing between the parentheses and the function fixes the
issue.

This commit adds `(#<|)` and makes `(<|#)` its deprecated alias.

src/Data/Text/Builder/Linear/Buffer.hs

@@ -31,6 +31,7 @@ module Data.Text.Builder.Linear.Buffer (
 
   -- ** Raw 'Addr#'
   (|>#),
+  ( #<| ), -- NOTE: extra spaces required because of -XUnboxedTuples
   (<|#),
 
   -- * Number formatting
@@ -75,7 +76,7 @@ buffer |> (Text src srcOff srcLen) =
     buffer
 
 -- | Prepend 'Text' prefix to a 'Buffer' by mutating it.
--- If a prefix is statically known, consider using '(<|#)' for optimal performance.
+-- If a prefix is statically known, consider using '(#<|)' for optimal performance.
 --
 -- >>> :set -XOverloadedStrings -XLinearTypes
 -- >>> runBuffer (\b -> "foo" <| "bar" <| b)
@@ -98,8 +99,6 @@ Text src srcOff srcLen <| buffer =
 --
 -- The literal string must not contain zero bytes @\\0@ and must be a valid UTF-8,
 -- these conditions are not checked.
---
--- Note the inconsistency in naming: unfortunately, GHC parser does not allow for @#<|@.
 (|>#) ∷ Buffer ⊸ Addr# → Buffer
 
 infixl 6 |>#
@@ -115,22 +114,34 @@ buffer |># addr# =
 -- to a 'Buffer' by mutating it. E. g.,
 --
 -- >>> :set -XOverloadedStrings -XLinearTypes -XMagicHash
--- >>> runBuffer (\b -> "foo"# <|# "bar"# <|# b)
+-- >>> runBuffer (\b -> "foo"# #<| "bar"# #<| b)
 -- "foobar"
 --
 -- The literal string must not contain zero bytes @\\0@ and must be a valid UTF-8,
 -- these conditions are not checked.
-(<|#) ∷ Addr# → Buffer ⊸ Buffer
-
-infixr 6 <|#
-addr# <|# buffer =
+--
+-- /Note:/ When the syntactic extensions @UnboxedTuples@ or @UnboxedSums@ are
+-- enabled, extra spaces are required when using parentheses: i.e. use @( '#<|' )@
+-- instead of @('#<|')@. See the GHC User Guide chapter
+-- “[Unboxed types and primitive operations](https://downloads.haskell.org/ghc/latest/docs/users_guide/exts/primitives.html#unboxed-tuples)”
+-- for futher information.
+( #<| ) ∷ Addr# → Buffer ⊸ Buffer
+
+infixr 6 #<|, <|#
+addr# #<| buffer =
   prependExact
     srcLen
     (\dst dstOff → A.copyFromPointer dst dstOff (Ptr addr#) srcLen)
     buffer
   where
     srcLen = I# (cstringLength# addr#)
 
+-- | Alias for @'(#<|)'@.
+{-# DEPRECATED (<|#) "Use '(#<|)' instead" #-}
+(<|#) ∷ Addr# → Buffer ⊸ Buffer
+(<|#) = ( #<| ) -- NOTE: extra spaces required because of -XUnboxedTuples
+{-# INLINE (<|#) #-}
+
 -- | Append given number of spaces.
 (|>…) ∷ Buffer ⊸ Word → Buffer
 

test/Main.hs

@@ -144,7 +144,7 @@ prop4 acts = runBuffer f1 === runBuffer f2
   where
     addr# = "foo"#
     f1, f2 :: Buffer ⊸ Buffer
-    f1 = \b → addr# <|# interpretOnBuffer acts b
+    f1 = \b → addr# #<| interpretOnBuffer acts b
     f2 = \b → T.pack "foo" <| interpretOnBuffer acts b
 
 prop5 ∷ [Action] → Property