Monadic & Grammatical constraints

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Setup Haskell Stack
-        uses: haskell/actions/setup@v2
+        uses: haskell-actions/setup@v2
         with:
           enable-stack: true
 

.gitignore

@@ -23,4 +23,4 @@ stack.yaml.lock
 tags
 .*.swp
 .qodo
-SCRATCH
+SCRATCH*

CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog for `distributors`
 
+## 0.3.0.0 - 2026-02-05
+
+### New Modules
+
+- `Control.Lens.Grammar` - Grammar hierarchy based on Chomsky's formal grammar classification
+- `Control.Lens.Grammar.BackusNaur` - Context-free grammar combinators (BNF)
+- `Control.Lens.Grammar.Boole` - Boolean algebra for grammars
+- `Control.Lens.Grammar.Kleene` - Regular expression combinators
+- `Control.Lens.Grammar.Symbol` - Symbol-level grammar primitives
+- `Control.Lens.Grammar.Token` - Token-level grammar primitives
+- `Data.Profunctor.Filtrator` - Filterable profunctors
+- `Data.Profunctor.Grammar` - Grammar profunctor abstraction
+- `Data.Profunctor.Monadic` - Monadic profunctor combinators with QualifiedDo support
+- `Data.Profunctor.Monoidal` - Monoidal profunctor combinators
+
+### Removed Modules
+
+- `Text.Grammar.Distributor` - Functionality split into the new modules above
+
+### Testing
+
+- Added `doctest` for documentation testing
+- New test examples: Arithmetic, Json, Lambda, LenVec, RegString, SemVer, SExpr
+
 ## 0.2.0.0 - 2025-07-08
 
 Added some combinators for `RegEx`es. Updated documentation.

LICENSE

@@ -1,4 +1,4 @@
-Copyright Eitan Chatav (c) 2024
+Copyright Eitan Chatav (c) 2026
 
 All rights reserved.
 

README.md

@@ -18,7 +18,8 @@ The term "distributor" is a synonym for "[profunctor](https://ncatlab.org/nlab/s
 
 Since "profunctor" became the standard nomenclature, we reappropriate "distributor" to describe a profunctor on a [distributive category](https://ncatlab.org/nlab/show/distributive+category).
 
-This library provides a study of `Monoidal` profunctors, `Distributor`s, `Alternator`s and `Filtrator`s. These profunctor constraints are analogous to `Applicative`, `Alternative` and `Filterable` functors. Examples of `Distributor`s will include printers and parsers, and it is demonstrated how to write a single term for both. Profunctors naturally give rise to optics and this library also studies some previously discovered optics, `PartialIso`s, `Monocle`s, `Grate`s and `Wither`s and also defines new optics, `Diopter`s and `Bifocal`s. Finally, an application of distributors is demonstrated by unifying Backus-Naur form grammars with invertible parsers, giving users a powerful playground for language syntax design.
+This library provides a study of distributor theory and optics,
+and their application to invertible grammar theory.
 
 ## previous work
 
@@ -28,6 +29,11 @@ While `Distributor`s in the library are lax distributive endoprofunctors, a math
 
 The idea for unifying Backus-Naur grammars with parsers comes from Joachim Breitner in a post [Showcasing Applicative](https://www.joachim-breitner.de/blog/710-Showcasing_Applicative).
 
+The idea for using monadic profunctors for reversible context-free grammars
+comes from Li-Yao Xia, in some posts and a paper but particularly
+this post on [Monadic profunctors for bidirectional programming]
+(https://blog.poisson.chat/posts/2017-01-01-monadic-profunctors.html).
+
 The person deserving the most credit for bringing the power of optics to programming, with his [lens library](https://github.com/ekmett/lens/), is Ed Kmett, to whom I am very grateful for teaching me a lot.
 
 None of the ideas in this library are particularly original and a lot of related ideas have been explored, in Tom Ellis' [product-profunctors](https://github.com/tomjaguarpaw/product-profunctors) as well as Sjoerd Visscher's [one-liner](https://github.com/sjoerdvisscher/one-liner) and more. Such explorations are _not_ limited to Haskell. Brandon Williams and Stephen Celis' excellent [swift-parsing](https://github.com/pointfreeco/swift-parsing) was also influenced by invertible parser theory.

blog.md

@@ -368,12 +368,12 @@ Just as `Alternative` has 0-or-more `many` and 0-or-1 `optional` combinators, we
 
 ```Haskell
 optionalP :: Distributor p => p a b -> p (Maybe a) (Maybe b)
-optionalP p = mapIso maybeEot (oneP >+< p)
+optionalP p = mapIso eotMaybe (oneP >+< p)
 
 manyP :: p a b -> p [a] [b]
 manyP p = mapIso listEot (oneP >+< p >*< manyP p)
 
-maybeEot :: Iso (Maybe a) (Maybe b) (Either () a) (Either () b)
+eotMaybe :: Iso (Maybe a) (Maybe b) (Either () a) (Either () b)
 
 listEot
   :: (Cons s s a a, AsEmpty t, Cons t t b b)

distributors.cabal

@@ -1,19 +1,19 @@
 cabal-version: 2.2
 
--- This file has been generated from package.yaml by hpack version 0.37.0.
+-- This file has been generated from package.yaml by hpack version 0.39.1.
 --
 -- see: https://github.com/sol/hpack
 
 name:           distributors
-version:        0.2.0.1
+version:        0.3.0.0
 synopsis:       Unifying Parsers, Printers & Grammars
 description:    Distributors provides mathematically inspired abstractions for coders to write parsers that can also be inverted to printers.
 category:       Profunctors, Optics, Parsing
 homepage:       https://github.com/morphismtech/distributors#readme
 bug-reports:    https://github.com/morphismtech/distributors/issues
 author:         Eitan Chatav
 maintainer:     eitan.chatav@gmail.com
-copyright:      2025 Eitan Chatav
+copyright:      2026 Eitan Chatav
 license:        BSD-3-Clause
 license-file:   LICENSE
 build-type:     Simple
@@ -30,13 +30,22 @@ library
   exposed-modules:
       Control.Lens.Bifocal
       Control.Lens.Diopter
+      Control.Lens.Grammar
+      Control.Lens.Grammar.BackusNaur
+      Control.Lens.Grammar.Boole
+      Control.Lens.Grammar.Kleene
+      Control.Lens.Grammar.Symbol
+      Control.Lens.Grammar.Token
       Control.Lens.Grate
       Control.Lens.Internal.NestedPrismTH
       Control.Lens.Monocle
       Control.Lens.PartialIso
       Control.Lens.Wither
       Data.Profunctor.Distributor
-      Text.Grammar.Distributor
+      Data.Profunctor.Filtrator
+      Data.Profunctor.Grammar
+      Data.Profunctor.Monadic
+      Data.Profunctor.Monoidal
   other-modules:
       Paths_distributors
   autogen-modules:
@@ -49,7 +58,9 @@ library
       ConstraintKinds
       DataKinds
       DefaultSignatures
+      DeriveFoldable
       DeriveFunctor
+      DeriveTraversable
       DeriveGeneric
       DerivingStrategies
       DerivingVia
@@ -65,12 +76,13 @@ library
       LambdaCase
       MagicHash
       MonoLocalBinds
-      OverloadedStrings
+      QualifiedDo
       QuantifiedConstraints
       RankNTypes
       RecursiveDo
       ScopedTypeVariables
       StandaloneDeriving
+      StandaloneKindSignatures
       TemplateHaskell
       TupleSections
       TypeApplications
@@ -80,28 +92,36 @@ library
       UndecidableSuperClasses
   ghc-options: -Wall -Wcompat -Widentities -Wincomplete-record-updates -Wincomplete-uni-patterns -Wmissing-export-lists -Wmissing-home-modules -Wpartial-fields -Wredundant-constraints
   build-depends:
-      adjunctions >=4.4 && <5
-    , base >=4.7 && <5
-    , bifunctors >=5.6 && <6
+      MemoTrie >=0.6 && <1
+    , adjunctions >=4.4 && <5
+    , base >=4.15 && <5
+    , bifunctors >=5.5 && <6
     , bytestring >=0.11 && <1
     , containers >=0.6 && <1
     , contravariant >=1.5 && <2
     , distributive >=0.6 && <1
-    , lens >=5.2 && <6
-    , mtl >=2.3 && <3
+    , lens >=5.0 && <6
+    , mtl >=2.2 && <3
     , profunctors >=5.6 && <6
     , tagged >=0.8 && <1
-    , template-haskell
+    , template-haskell >=2.17 && <3
     , text ==2.*
-    , th-abstraction
-    , vector >=0.13 && <1
+    , th-abstraction >=0.4 && <1
+    , vector >=0.12 && <1
     , witherable >=0.4 && <1
   default-language: Haskell2010
 
-test-suite spec
+test-suite test
   type: exitcode-stdio-1.0
-  main-is: Spec.hs
+  main-is: Main.hs
   other-modules:
+      Examples.Arithmetic
+      Examples.Json
+      Examples.Lambda
+      Examples.LenVec
+      Examples.RegString
+      Examples.SemVer
+      Examples.SExpr
       Paths_distributors
   autogen-modules:
       Paths_distributors
@@ -113,7 +133,9 @@ test-suite spec
       ConstraintKinds
       DataKinds
       DefaultSignatures
+      DeriveFoldable
       DeriveFunctor
+      DeriveTraversable
       DeriveGeneric
       DerivingStrategies
       DerivingVia
@@ -129,12 +151,13 @@ test-suite spec
       LambdaCase
       MagicHash
       MonoLocalBinds
-      OverloadedStrings
+      QualifiedDo
       QuantifiedConstraints
       RankNTypes
       RecursiveDo
       ScopedTypeVariables
       StandaloneDeriving
+      StandaloneKindSignatures
       TemplateHaskell
       TupleSections
       TypeApplications
@@ -144,22 +167,24 @@ test-suite spec
       UndecidableSuperClasses
   ghc-options: -Wall -Wcompat -Widentities -Wincomplete-record-updates -Wincomplete-uni-patterns -Wmissing-export-lists -Wmissing-home-modules -Wpartial-fields -Wredundant-constraints
   build-depends:
-      adjunctions >=4.4 && <5
-    , base >=4.7 && <5
-    , bifunctors >=5.6 && <6
+      MemoTrie >=0.6 && <1
+    , adjunctions >=4.4 && <5
+    , base >=4.15 && <5
+    , bifunctors >=5.5 && <6
     , bytestring >=0.11 && <1
     , containers >=0.6 && <1
     , contravariant >=1.5 && <2
     , distributive >=0.6 && <1
     , distributors
-    , hspec
-    , lens >=5.2 && <6
-    , mtl >=2.3 && <3
+    , doctest >=0.18 && <1
+    , hspec >=2.7 && <3
+    , lens >=5.0 && <6
+    , mtl >=2.2 && <3
     , profunctors >=5.6 && <6
     , tagged >=0.8 && <1
-    , template-haskell
+    , template-haskell >=2.17 && <3
     , text ==2.*
-    , th-abstraction
-    , vector >=0.13 && <1
+    , th-abstraction >=0.4 && <1
+    , vector >=0.12 && <1
     , witherable >=0.4 && <1
   default-language: Haskell2010

package.yaml

@@ -1,39 +1,39 @@
 name: distributors
-version: 0.2.0.1
+version: 0.3.0.0
 github: "morphismtech/distributors"
 license: BSD-3-Clause
 author: "Eitan Chatav"
 maintainer: "eitan.chatav@gmail.com"
-copyright: "2025 Eitan Chatav"
+copyright: "2026 Eitan Chatav"
 
 extra-source-files:
 - README.md
 extra-doc-files:
 - CHANGELOG.md
 
-
 category: Profunctors, Optics, Parsing
 synopsis: Unifying Parsers, Printers & Grammars
 description:
   Distributors provides mathematically inspired abstractions
   for coders to write parsers that can also be inverted to printers.
 
 dependencies:
-- base >= 4.7 && < 5
+- base >= 4.15 && < 5
 - adjunctions >= 4.4 && < 5
-- bifunctors >= 5.6 && < 6
+- bifunctors >= 5.5 && < 6
 - bytestring >= 0.11 && < 1
 - containers >= 0.6 && < 1
 - contravariant >= 1.5 && < 2
 - distributive >= 0.6 && < 1
-- lens >= 5.2 && < 6
-- mtl >= 2.3 && < 3
+- lens >= 5.0 && < 6
+- MemoTrie >= 0.6 && < 1
+- mtl >= 2.2 && < 3
 - profunctors >= 5.6 && < 6
 - tagged >= 0.8 && < 1
-- template-haskell
+- template-haskell >= 2.17 && < 3
 - text >= 2 && < 3
-- th-abstraction
-- vector >= 0.13 && < 1
+- th-abstraction >= 0.4 && < 1
+- vector >= 0.12 && < 1
 - witherable >= 0.4 && < 1
 
 ghc-options:
@@ -56,7 +56,9 @@ default-extensions:
 - ConstraintKinds
 - DataKinds
 - DefaultSignatures
+- DeriveFoldable
 - DeriveFunctor
+- DeriveTraversable
 - DeriveGeneric
 - DerivingStrategies
 - DerivingVia
@@ -72,12 +74,13 @@ default-extensions:
 - LambdaCase
 - MagicHash
 - MonoLocalBinds
-- OverloadedStrings
+- QualifiedDo
 - QuantifiedConstraints
 - RankNTypes
 - RecursiveDo
 - ScopedTypeVariables
 - StandaloneDeriving
+- StandaloneKindSignatures
 - TemplateHaskell
 - TupleSections
 - TypeApplications
@@ -87,9 +90,10 @@ default-extensions:
 - UndecidableSuperClasses
 
 tests:
-  spec:
-    main: Spec.hs
+  test:
+    main: Main.hs
     source-dirs: test
     dependencies:
       - distributors
-      - hspec
+      - doctest >= 0.18 && < 1
+      - hspec >= 2.7 && < 3