Documentation

Any MonoidalAction gives rise to a flavor: the witness pair is a matched pair of arrows into/out of the action for some shared, existentially hidden index x. LensFl/PrismFl are (unspelled-out) special cases of this for ProdAction/CoprodAction.

An Eilenberg-Moore algebra for the monad m -- a representable Promonad on k, acting as the functor m % - (Proarrow.Promonad): a structure map m % a ~> a, coherent with the monad's unit and multiplication. The free algebras m % s are the ones an algebraic lens is built from (algebraicLens).

There are deliberately no instances for the unit or for products of algebras, and there cannot be: Unit and (**) are type families, which may not head an instance. That is why withAlgP passes the structure map as a value -- the composition instance pairs two algebras with unparRep and the identity witness supplies the unit one with unpar0Rep, neither needing an Algebra instance. A witness pair whose residual is the unit is the identity optic up to the unitors, so nothing is lost.

The algebraic-lens flavor (Riley, Categories of Optics; Clarke et al.): the tensor-action witness pair Rep/Corep (ActionAt Tensor x) of Proarrow.Optic.MonoidalLens -- legs s ~> x ** a and x ** b ~> t -- with the residual x an Algebra for m. The flavor itself asks only that the functor m % be oplax monoidal, enough to pair and discard residuals; the monad structure arrives with each Algebra witness, not with the flavor. The algebra is what lets put see a whole m-computation of sources rather than one: classifyOf collapses m % s to a single residual through it. Every algebraic lens is a MonoidalLens (the MonLensFl superclass: the residual is a comonoid), so it views, sets, folds and traverses as a lens does. withAlgP hands the algebra over as a value, so composites pair algebras without an instance for the product.

An algebraic lens: like a Lens, but put is allowed to combine information monadically -- get :: s ~> a, put :: m % s ** b ~> t -- rather than only ever seeing the last s.

Build an algebraic lens from get and a monadic put; the residual is the free algebra m % s itself (which must be a comonoid, as must s to be kept alongside its focus).

Classify a monadic computation of s's through an AlgebraicLens (or any stronger optic, in any encoding), given a replacement focus b -- generalizing "set" to combine every s the computation might produce (via its residual's Algebra) rather than only ever seeing the last one. The focus a is discarded under the monad, hence must be a comonoid.

classifyOf for a Haskell monad, curried: optic .? b $ fs.

The classifying lens (Clarke et al., Example 3.11): the algebraic lens for the list monad, here for any monad l whose algebras are monoids. Tensoring with a monoid is an applicative functor (the writer applicative) -- so a classifying lens is also a kaleidoscope (KaleidoFl), the meet of the two flavors. This is what lets it compose with a kaleidoscope to a kaleidoscope again (Clarke et al., Remark 3.28): a lens composed with a kaleidoscope is not a kaleidoscope, since a product functor is not applicative, but a product by a monoid is. The algebra and the monoid on the residual are assumed to agree, as they do for the free algebra l % s of the list monad (join and ++) that classifyingLens uses.

Build a classifying lens from get and a classify :: l % s ** b ~> t; the residual is the free algebra l % s, e.g. the list of sources.