diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +Version 0.7.2.1 +--------------- +* Updated CI configuration +* Improved Haddock documentation +* Removed the unused containers dependency from library and bumped it in tests and executables + Version 0.7.2 --------------- * Added `Combinators.takeSomeNonEmpty` diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -107,4 +107,6 @@ [Combined](https://github.com/blamario/grampa/blob/master/grammatical-parsers/examples/Combined.hs) module. For more conventional tastes there are monolithic examples of -[Lua](https://github.com/blamario/language-lua2/blob/master/src/Language/Lua/Grammar.hs) and [Oberon](http://hackage.haskell.org/package/language-oberon) grammars as well. +[Lua](https://github.com/blamario/language-lua2/blob/master/src/Language/Lua/Grammar.hs), +[Modula-2](https://hackage.haskell.org/package/language-Modula2), and +[Oberon](http://hackage.haskell.org/package/language-oberon) grammars as well. diff --git a/grammatical-parsers.cabal b/grammatical-parsers.cabal --- a/grammatical-parsers.cabal +++ b/grammatical-parsers.cabal @@ -1,5 +1,5 @@ name: grammatical-parsers -version: 0.7.2 +version: 0.7.2.1 synopsis: parsers that combine into grammars description: /Gram/matical-/pa/rsers, or Grampa for short, is a library of parser types whose values are meant to be assigned @@ -16,7 +16,7 @@ category: Text, Parsing build-type: Custom cabal-version: >=1.10 -tested-with: GHC==9.8.2, GHC==9.6.4, GHC==9.4.8, GHC==9.2.8, GHC==9.0.2, GHC==8.10.7 +tested-with: GHC==9.12.1, GHC==9.10.1, GHC==9.8.2, GHC==9.6.4, GHC==9.4.8, GHC==9.2.8, GHC==9.0.2, GHC==8.10.7 extra-source-files: README.md, CHANGELOG.md source-repository head type: git @@ -49,7 +49,6 @@ default-language: Haskell2010 ghc-options: -Wall build-depends: base >=4.9 && <5, - containers >= 0.4 && < 0.8, transformers >= 0.5 && < 0.7, monoid-subclasses >=1.0 && <1.3, parsers < 0.13, @@ -63,7 +62,7 @@ main-is: Main.hs other-modules: Arithmetic, Boolean, Combined, Comparisons, Conditionals, Lambda, Utilities default-language: Haskell2010 - build-depends: base >=4.9 && <5, containers >= 0.5.7.0 && < 0.8, + build-depends: base >=4.9 && <5, containers >= 0.5.7.0 && < 0.9, parsers < 0.13, rank2classes >= 1.0.2 && < 1.6, grammatical-parsers, monoid-subclasses @@ -73,7 +72,7 @@ main-is: BooleanTransformations.hs other-modules: Boolean, Utilities default-language: Haskell2010 - build-depends: base >=4.9 && <5, containers >= 0.5.7.0 && < 0.8, + build-depends: base >=4.9 && <5, containers >= 0.5.7.0 && < 0.9, parsers < 0.13, rank2classes >= 1.0.2 && < 1.6, grammatical-parsers, monoid-subclasses @@ -82,7 +81,7 @@ type: exitcode-stdio-1.0 hs-source-dirs: test, examples x-uses-tf: true - build-depends: base >=4.9 && < 5, containers >= 0.5.7.0 && < 0.8, + build-depends: base >=4.9 && < 5, containers >= 0.5.7.0 && < 0.9, monoid-subclasses, parsers < 0.13, witherable >= 0.4 && < 0.6, rank2classes >= 1.0.2 && < 1.6, grammatical-parsers, @@ -109,7 +108,7 @@ ghc-options: -O2 -Wall -rtsopts -main-is Benchmark.main Build-Depends: base >=4.9 && < 5, rank2classes >= 1.0.2 && < 1.6, grammatical-parsers, monoid-subclasses, parsers < 0.13, - criterion >= 1.0, deepseq >= 1.1, containers >= 0.5.7.0 && < 0.8, text >= 1.1 + criterion >= 1.0, deepseq >= 1.1, containers >= 0.5.7.0 && < 0.9, text >= 1.1 main-is: Benchmark.hs other-modules: Main, Arithmetic, Boolean, Combined, Comparisons, Conditionals, Lambda, Utilities default-language: Haskell2010 diff --git a/src/Text/Grampa.hs b/src/Text/Grampa.hs --- a/src/Text/Grampa.hs +++ b/src/Text/Grampa.hs @@ -1,5 +1,31 @@ --- | A collection of parsing algorithms with a common interface, operating on grammars represented as records with --- rank-2 field types. +-- | This library consists of a collection of parsing algorithms and a common interface for representing grammars as +-- records with rank-2 field types. +-- +-- To implement a grammar, first determine if it is a context-free grammar or perhaps a parsing expression grammar. In +-- the latter case, you should import your parser type from either "Text.Grampa.PEG.Backtrack" or the +-- "Text.Grampa.PEG.Packrat" module. The former is faster on simple grammars but may require exponential time on more +-- complex cases. The Packrat parser on the other hand guarantees linear time complexity but has more overhead and +-- consumes more memory. +-- +-- If your grammar is context-free, there are more possibilities to choose from: +-- +-- * If the grammar is neither left-recursive nor ambiguous, you can import your parser type from +-- "Text.Grampa.ContextFree.Continued". +-- * If the grammar is ambiguous and you need to see all the results, there's "Text.Grampa.ContextFree.Parallel". +-- * For a complex but non-left-recursive grammar, you can use "Text.Grampa.ContextFree.SortedMemoizing". +-- * If you need to carry a monadic computation, there's "Text.Grampa.ContextFree.SortedMemoizing.Transformer". +-- * If the grammar is left-recursive, "Text.Grampa.ContextFree.SortedMemoizing.LeftRecursive" is the ticket. +-- * If the grammar is left-recursive /and/ you require monadic context, the final option is +-- "Text.Grampa.ContextFree.SortedMemoizing.Transformer.LeftRecursive". +-- +-- Regardless of the chosen parer type, you'll construct your grammar the same way. A grammar is a set of productions +-- using the same parser type, collected and abstracted inside a rank-2 record type. Each production is built using +-- the standard parser combinators from the usual 'Applicative' and 'Alternative' classes, plus some additional +-- [classes](#g:classes) provided by this library. The 'Monad' operations are available as well, but should not be +-- used in left-recursive positions. +-- +-- Once the grammar is complete, you can use 'parseComplete' or 'parsePrefix' to apply it to your input. + {-# LANGUAGE FlexibleContexts, KindSignatures, OverloadedStrings, RankNTypes, ScopedTypeVariables, TypeFamilies, TypeOperators #-} module Text.Grampa ( @@ -7,7 +33,7 @@ failureDescription, simply, -- * Types Grammar, GrammarBuilder, GrammarOverlay, ParseResults, ParseFailure(..), FailureDescription(..), Ambiguous(..), Pos, - -- * Classes + -- * Classes #classes# -- ** Parsing DeterministicParsing(..), AmbiguousParsing(..), CommittedParsing(..), TraceableParsing(..), LexicalParsing(..), @@ -83,8 +109,8 @@ simply :: (Rank2.Only r (p (Rank2.Only r) s) -> s -> Rank2.Only r f) -> p (Rank2.Only r) s r -> s -> f r simply parseGrammar p input = Rank2.fromOnly (parseGrammar (Rank2.Only p) input) --- | Given the textual parse input, the parse failure on the input, and the number of lines preceding the failure to --- show, produce a human-readable failure description. +-- | Given the textual parse input, the parse failure on the input, and the number of preceding lines of context you +-- want to show, produce a human-readable failure description. failureDescription :: forall s pos. (Ord s, TextualMonoid s, Position pos) => s -> ParseFailure pos s -> Int -> s failureDescription input (ParseFailure pos (FailureDescription expected inputs) erroneous) contextLineCount = Position.context input pos contextLineCount diff --git a/test/README.lhs b/test/README.lhs --- a/test/README.lhs +++ b/test/README.lhs @@ -107,4 +107,6 @@ [Combined](https://github.com/blamario/grampa/blob/master/grammatical-parsers/examples/Combined.hs) module. For more conventional tastes there are monolithic examples of -[Lua](https://github.com/blamario/language-lua2/blob/master/src/Language/Lua/Grammar.hs) and [Oberon](http://hackage.haskell.org/package/language-oberon) grammars as well. +[Lua](https://github.com/blamario/language-lua2/blob/master/src/Language/Lua/Grammar.hs), +[Modula-2](https://hackage.haskell.org/package/language-Modula2), and +[Oberon](http://hackage.haskell.org/package/language-oberon) grammars as well.