Merge branch 'main' into thread-safe-whitespace

.github/workflows/ci.yaml

@@ -60,10 +60,7 @@ jobs:
           cabal test $CONFIG --test-options="--color always"
 
       - name: Doc
-      # Define the `__HADDOCK__` C macro only for the documentation generation.
-      # This is used when generating the type-specialised docs, but allows
-      # the actual haskell library to export the non-specialised versions.
-        run: cabal haddock gigaparsec --haddock-options=--optghc=-cpp --haddock-options=--optghc=-D__HADDOCK__ $CONFIG
+        run: cabal haddock gigaparsec
 
   deploy:
     name: Deploy Docs
@@ -99,7 +96,7 @@ jobs:
             ${{ runner.os }}-${{ matrix.ghc }}-${{ matrix.cabal }}-
 
       - name: Doc
-        run: cabal haddock gigaparsec --enable-doc --haddock-hyperlink-source --haddock-quickjump --haddock-html-location='https://hackage.haskell.org/package/$pkg-$version/docs' --haddock-options=--optghc=-cpp --haddock-options=--optghc=-D__HADDOCK__
+        run: cabal haddock gigaparsec --enable-doc --haddock-hyperlink-source --haddock-quickjump --haddock-html-location='https://hackage.haskell.org/package/$pkg-$version/docs'
 
       - name: Prepare to upload built htmls
         run: cp -r ./$(find dist-newstyle -path '*/doc/html/gigaparsec') site

README.md

@@ -16,19 +16,19 @@ To achieve these aims, some departures have been made
 from many of the classic `parsec`-style implementations:
 
 * `gigaparsec`'s `Parsec` type is simple: only one type-parameter. There are a few consequences of this:
-    - `Parsec` does not have a `ParsecT` variant: occasionally, people may wish to thread other monads through a parser, however, most of the practical use-cases of this can be captured using `gigaparsec`'s *registers*. The exception here is `IO`
+    - `Parsec` does not have a `ParsecT` variant: occasionally, people may wish to thread other monads through a parser, however, most of the practical use-cases of this can be captured using `gigaparsec`'s *state* and *references*, implemented with [`reference-threads`](https://github.com/j-mie6/reference-threads). The exception here is `IO`
     operations.
     - `Parsec` cannot generate the type of the input stream: currently, the input is assumed to be `String`. In future, however, it may be possible to specify an implementation for the input without resorting to noise in the type-signatures.
     - `Parsec` cannot specify a custom error type to be carried through parsing. In practice, a rich typeclass-driven API can be used to format error messages in the desired way, as well as change their types at the point of calling `parse`.
 * The common `try` combinator has been more appropriately
-  named as the `atomic` combinator: this is consistent with the `parsley` naming, and we believe that this name is more true to the combinators purpose.
-* Creating new primitive combinators is not endorsed by the libary: while the capacities to make them have been exposed, they are not made part of the public API to allow freedom for the maintainers to continue to innovate and improve the internals -- this includes continued optimisation.
+  named as the `atomic` combinator: this is consistent with the `parsley` naming, and we believe that this name better embodies the combinator's purpose.
+* Creating new primitive combinators is not endorsed by the library: while the capacities to make them have been exposed, they are not made part of the public API to allow freedom for the maintainers to continue to innovate and improve the internals -- this includes continued optimisation.
 
 Current `HEAD` documentation can be found [here][Link-Haddock]: for
 stable documentation please consult Hackage directly.
 
 ## Library Evolution ![Semantic Versioning: pvp][Badge-PVP]
-`gigaparsec` adheres strictly to Haskell PVP, with the following `early-semver`esque caveat:
+`gigaparsec` adheres strictly to Haskell PVP, with the following `early-semver`-esque caveat:
 
 * Versions `0.M.m.p` are to be treated as pre-release, with high-volatility. While the major
   component `M` will still be bumped for every major change, it is likely that there will be high

docs/Haddock.md

@@ -0,0 +1,23 @@
+# Conditional Compilation
+To improve documentation of re-exports (such as `<|>`), we use CPP macros that re-define these re-exports only during a `haddock` pass.
+We achieve this with the `__HADDOCK_VERSION__` macro, so we can write things like,
+```haskell
+#ifdef __HADDOCK_VERSION__
+{-| Some custom docs
+-}
+infixl 3 <|>
+(<|>) :: Parsec a -- ^ custom docs.
+      -> Parsec a -- ^ custom docs.
+      -> Parsec a -- ^ custom docs.
+(<|>) = (Applicative.<|>)
+#endif
+```
+
+If we were to perform the redefinition for the actual library, then users would have conflicting types between 
+`Text.Gigaparsec.<|>` and the applicative `<|>`.
+Moreover, the haskell compiler will treat these as different, and we may lose some specialisation improvements/optimisations.
+
+One side-effect of this is that `<|>` within the `gigaparsec` library must be imported from `Applicative`, not from `Text.Gigaparsec`, 
+otherwise the `haddock` phase of compilation will fail in cases where `<|>` is used in a type that is not `Parsec`.
+This is a small price to pay for better documentation :)
+This does not affect external users.

docs/Version Tables.md

@@ -0,0 +1,46 @@
+As we want to support multiple GHC versions, we need to take care of how to handle the versions of different dependencies.
+
+
+### GHC vs Base
+https://wiki.haskell.org/Base_package
+| GHC | Base |
+| --- | ---- |
+| 8.10.1  | 4.14.0.0 |
+| 8.10.2  | 4.14.1.0 |
+| 8.10.7  | 4.14.3.0 |
+| 9.0.1   | 4.15.0.0 |
+| 9.0.2   | 4.15.1.0 |
+| 9.2.1   | 4.16.0.0 |
+| 9.2.2   | 4.16.1.0 |
+| 9.2.5   | 4.16.4.0 |
+| 9.4.1   | 4.17.0.0 |
+| 9.6.1   | 4.18.0.0 |
+| 9.8.1   | 4.19.0.0 |
+| 9.10    | 4.20.0.0 |
+
+
+# Template Haskell
+Minimum TH version to support will be 2.16.
+
+### Template Haskell Type Constructors
+| Constructor  | Since | Min Base | Min GHC  |
+| ----       | --- | --- | --- | 
+| `ForallT` | always | 
+| `AppT` | always |
+| `SigT` | always |
+| `VarT` | always |
+| `InfixT` | 2.11 | 4.7 | 8.0
+| `UInfixT` | 2.11 | 4.7 | 8.0
+| `ParensT` | 2.11 | 4.7 | 8.0
+| `AppKindT` | 2.15 | 4.11 | 8.8
+| `ImplicitParamT` |  2.15 | 4.11 | 8.8
+| `ForallVisT` | 2.16 | 4.11 | 8.10.1 
+| `PromotedInfixT` | 2.19 | 4.11 | 9.4
+| `PromotedUInfixT` | 2.19 | 4.11 | 9.4
+
+Some important version differences:
+
+| TH Version | Issue | Notes |
+| --- | --- | --- |
+| 2.17 | `TyVarBndr` now has a `flag` parameter, this is a breaking change | 
+

src/Text/Gigaparsec.hs

@@ -100,7 +100,7 @@ import Text.Gigaparsec.Errors.ErrorGen (vanillaGen)
 
 -- We want to improve the docs for Applicative, so we do some trickery with redefinitions 
 --  *only* for the haddock generation.
-#ifdef __HADDOCK__
+#ifdef __HADDOCK_VERSION__
 {-# LANGUAGE NoImplicitPrelude #-}
 import Prelude hiding ((<$>), (<$), (<*>), (*>), (<*), pure, liftA2)
 import Prelude qualified
@@ -574,7 +574,7 @@ We use some C++ macro stuff to only redefine these re-exports for the gigaparsec
 which lets us provide more descriptive (and specialised) documentation for combinators.
 -}
 
-#ifdef __HADDOCK__
+#ifdef __HADDOCK_VERSION__
 {-|
 Repeatedly parse the given parser __zero__ or more times, collecting the results into a list.
 

src/Text/Gigaparsec/Patterns.hs

@@ -101,7 +101,7 @@ deriveLiftedConstructors prefix = fmap concat . traverse deriveCon
 This function is used to automatically generate /Deferred Constructors/, which are
 one of the patterns in /"Design Patterns for Parser Combinators/". It is provided
 with a prefix, which is used to denote an application of the constructor, and
-then a list of "ticked" constructors to generate deferred constructors for. This
+then a list of "ticked" constructors for which to generate deferred constructors. This
 means adding a single @'@ in front of the constructor name. For example:
 
 > {-# LANGUAGE TemplateHaskell #-}

src/Text/Gigaparsec/Token/Descriptions.hs

@@ -547,7 +547,7 @@ data EscapeDesc = EscapeDesc
                                         -- the string but can be used to disambiguate other escape sequences: in Haskell this would be \&
   , gapsSupported :: !Bool              -- ^ specifies whether or not string gaps are supported:
                                         -- this is where whitespace can be injected between two escBegin characters and this will all be ignored in the final string,
-                                        -- such that "hello \ \world" is "hello world"
+                                        -- such that @"hello \ \world"@ is "hello world"
   }
 
 {-|