functor-combinators

Tools for functor combinator-based program design

https://github.com/mstksg/functor-combinators#readme

Version on this page:0.4.1.3
LTS Haskell 23.27:0.4.1.4
Stackage Nightly 2025-07-12:0.4.1.4
Latest on Hackage:0.4.1.4

See all snapshotsfunctor-combinators appears in

BSD-3-Clause licensedbyJustin Le
Maintained by[email protected]
This version can be pinned in stack with:functor-combinators-0.4.1.3@sha256:4756ec042170ae3982e875e71c0a7542c4b7ddc59f649da57adf1b7d4bda19cb,5692

Module documentation for 0.4.1.3

Used by 1 package inlts-23.17(full list with versions):

functor-combinators

Introductory Blog Post /Hackage

Tools for working withfunctor combinators: types that take functors (orother indexed types) and returns a new functor that “enhances” or “mixes” themin some way.

The main functionality is exported inData.Functor.Combinators, but morefine-grained functionality and extra combinators (some of themre-implementations for compatibility) are available in other modules as well.

The goal is to represent schemas, DSL’s, and computations (things like parsers,things to execute, things to consume or produce data) by assembling“self-evident” basic primitives and subjecting them to manydifferentsuccessive transformations and combiners. The process of doing so:

  1. Forces you to make explicit decisions about the structure of yourcomputation type as an ADT.
  2. Allows you to retain isolation of fundamental parts of your domain asseparate types
  3. Lets you manipulate the structure of your final computation type throughnormal Haskell techniques like pattern matching. The structure isavailable throughout the entire process, so you can replace individualcomponents and values within your structure.
  4. Allows you to fullyreflect the structure of your final computationthrough pattern matching and folds, so you can inspect the structure andproduce useful summaries.

The main benefit of this library in specific is to allow you to be able to workwith different functor combinators with a uniform and lawful interface, so thereal functionality here is the wide variety of functor combinators from allaround the Haskell ecosystem. This library does not provide the functorcombinators, as much as it re-exports them with a unified interface. However,it does “fill in the matrix”, in a sense, of functor combinators in specificroles that are missing from the haskell ecosystem.

To jump into using it, importData.Functor.Combinator. For a fullintroduction, check out theFunctor Combinatorpedia, whichgoes in-depth into the motivation behind functor combinator-driven development,examples of the functor combinators in this library, and details about how touse these abstractions!

Comparisons

On the surface,functor-combinators look like it fills a similar space toeffects systems and libraries likemtl,polysemy,freer-simple, orfused-effects. However, the functor combinatordesign pattern actually exists on a different level.

Functor combinator design patterns can be used to help build thestructure ofthedata types and schemas that define your program/DSL. Once you buildthese nice structures, you theninterpret them into some target context. This“target context” is the realm that libraries likemtl andpolysemy canfill; functor combinators serve to help you define a structure for your programbefore you interpret it into whatever Applicative or Monad or effects systemyou end up using.

Changes

Changelog

Version 0.4.1.3

January 9, 2024

https://github.com/mstksg/functor-combinators/releases/tag/v0.4.1.3

  • Compatibility with transformers 0.6, and therefore ghc 9.6 (#7)

Version 0.4.1.2

January 29, 2023

https://github.com/mstksg/functor-combinators/releases/tag/v0.4.1.2

  • Add Invariant instances to Freer.Church types

Version 0.4.1.1

January 29, 2023

https://github.com/mstksg/functor-combinators/releases/tag/v0.4.1.1

  • Fix builds and warnings for GHC 9.2 and base 4.16

Version 0.4.1.0

September 29, 2021

https://github.com/mstksg/functor-combinators/releases/tag/v0.4.1.0

  • All of the missing instances to the typeclasses added in 0.4 that I couldremember.
  • Variations ofconcatInply /concatInplicative /concatInalt /concatInplus renamed togatheredN /swervedN /gatheredN1 /swervedN1.
  • gatherN,gatherN1 added with typeclass-based multi-arity functions.
  • GHC 9.0 compatibility (@ocharles)

Version 0.4.0.0

September 3, 2021

https://github.com/mstksg/functor-combinators/releases/tag/v0.4.0.0

  • Finally addData.Functor.Invariant.Inplicative andData.Functor.Internative, with the typlecassesInply,Inplicative,Inalt,Inplus, andInternative, the invariant versions ofApply/Divise,Applicative/Divisible,Alt/Decide,Plus/Choose, andAlternative/Decidable.

  • MoveData.Functor.Invariant.DivAp andData.Functor.Invariant.DecAlt toData.Functor.Invariant.Inplicative.Free andData.Functor.Invariant.Internative.Free, respectively.

    Their specializedgather/knot/swerve/reject are now a part of thetypeclasses.

  • concatDivAp family andconcatDecAlt family of functions generalized towork for allInplicative andInplus, respectively, and moved to themodules for their respective typeclasses asconcatInplicative,concatInply,concatInplus, andconcatInalt.

  • Changed the order of arguments ongather andswerve to be consistentwith the arguments ofinvmap,Day, andNight.

  • Changed the order of arguments in theGather, andSwerve patterns tobe more consistent with the new order of arguments forgather/swerve.

  • Changed the order of arguments in theDivAp1 andDecAlt1 patterns tobe more consistent with the order of arguments forDay andNight.

  • AddrunDay andrunNight for invariantDay andNight, using theInply andInalt typeclasses, respectively.runDay is found inData.Functor.Invariant.Inplicative, even though it should belong inData.Functor.Invariant.Day, but that’s in a different package.

  • Adddather,necide, andnerve to invariantDay, contravariantNight, invariantNight, in parallel todap for covariantDay. UsestheInply,Divise, andInalt typeclasses, respectively.dather isfound inData.Functor.Invariant.Inplicative, even though it shouldbelong inData.Functor.Invariant.Day, but that’s in a different package.

  • Addhfor andhfor1 toData.HFunctor.HTraversable.

Version 0.3.6.0

August 27, 2020

https://github.com/mstksg/functor-combinators/releases/tag/v0.3.6.0

  • Data.HFunctor.HTraversable added, providingHTraversable andHTraversable1.
  • Control.Monad.Freer.Church: MissingApply,Alt, andPlus instancesadded forComp.
  • Data.HBifunctor:HFunctor instances forLeftF,RightF,Joker,Void3, andComp made more kind-polymorphic
  • Data.HFunctor.Interpret:itraverse added, mimickinghtraverse forproperInterpret instances.
  • Data.HFunctor.Chain:foldChainA andfoldChain1A added, for effectfulfolding of chains.

Version 0.3.5.0

August 15, 2020

https://github.com/mstksg/functor-combinators/releases/tag/v0.3.5.0

  • DayChain andNightChain renamed toDivAp andDecAlt, to betterreflect their abstracted nature ever since0.3.4.0. The modules arerenamed toData.Functor.Invariant.DivAp andData.Functor.Invariant.DecAlt.

  • v0.3.5.1: Fixed infinite recursion bug for Tensor instances ofinvariantDay/Night.

Version 0.3.4.0

August 14, 2020

https://github.com/mstksg/functor-combinators/releases/tag/v0.3.4.0

  • Data.HFunctor.Route: A new twist on getting invariant functorcombinators. Instead of creating new ones, utilize existing functorcombinators withPre/Post.

  • Data.Functor.Invariant.Day.Chain andData.Functor.Invariant.Night.Chaincreated, factoring out theChain part of the invariantDay/Night.This was done to fix the fact thatData.Functor.Invariant.Day is a modulethat already existed inkan-extensions. Oops!

    • As a consequence,DayChain andNightChain are now newtype wrappersinstead of plain type synonyms.

  • v0.3.4.1: Add in missingFunctor andInvariant instances forProPre andProPost, as well as a bunch of instances forProPre.

  • v0.3.4.2: Add in missingHFunctor,Inject,Interpret instancesforPostT.

Version 0.3.3.0

August 11, 2020

https://github.com/mstksg/functor-combinators/releases/tag/v0.3.3.0

  • Control.Applicative.ListF: Missing contravariant instances added forMaybeF.
  • Data.HFunctor: AddinjectMap andinjectContramap, two small utilityfunctions that represent common patterns in injection and mapping.
  • Data.Functor.Combinator: ReplacedivideN and related functions withdsum anddsum1, which is an altogether cleaner interface that doesn’trequire heterogenous lists. A part of a larger project on cleaning upDivisible tools.
  • Data.Functor.Contravariant.Divise: Add useful utility functionsdsumand<:>, which makes the type ofdivise closer to that of<|> andasum.
  • Data.Functor.Contravariant.Divisible.Free: ImplementDiv in terms of alist, instead of the mirroredAp. Should make it much easier to use,although a less-than-idealCoyoneda is required to keep it compatiblewith the contravariantDay inkan-extensions. Added patterns torecover the original interface.

Version 0.3.2.0

August 9, 2020

https://github.com/mstksg/functor-combinators/releases/tag/v0.3.2.0

  • Data.HFunctor.Interpret:icollect,icollect1 now are moreconstrained: they only work on things that haveInterpret instances forallMonoid m orSemigroup m inAltConst m. While this doesn’taffect how it works on any types in this library, it does make the typesignature a little more clean (hiding the usage ofDList) and preventsone from making an oddInterpret instance that does something weird withtheDList. This also allows us to drop the directdlist >= 1.0 dependency.
  • Data.HFunctor.Interpret:biapply,bifanout,bifanout1 added ascontravariant consumer versions ofiget,icollect, andicollect1.
  • Data.HBifunctor.Associative:bicollectbicollect1 removed becausethey really don’t make sense for associative tensors, which can only haveat most one of each tensor.
  • Data.HBifunctor.Associative:biapply added as the contravariantconsumer version ofbiget.
  • Data.Functor.Invariant.Day: Add conversion functions from chains to thecovariant/invariant versions,chainAp,chainAp1,chainDiv, andchainDiv1.
  • Data.Functor.Invariant.Night: Add conversion functions from chains to thecovariant/invariant versions,chainDec,chainDec1,chainListF,chainNonEmptyF. Also add “undescored” versions to the covariantversions,toCoNight_,chainListF_,chainNonEmptyF_, to moreaccurately represent the actual contravariant either-based day convolution.Also changedShare toSwerve.
  • Data.Functor.Combinator:AltConst re-exported.

Version 0.3.1.0

August 7, 2020

https://github.com/mstksg/functor-combinators/releases/tag/v0.3.1.0

  • Data.HFunctor.Interpret:getI andcollectI made more efficient, andrenamed toiget andicollect, respectively, to mirrorbiget andbicollect.getI andcollectI are left in with a deprecation warning.icollect1 added to ensure a non-empty collection.AltConst added toaid in implementation.
  • Data.HBifunctor.Associative:bicollect1 added to ensure a non-emptycollection.biget andbicollect made more efficient.
  • Data.Functor.Contravariant.Night,Data.Functor.Invariant.Night:refuted added for a convenientNot. MissingInvariant instance forNot also added.
  • Data.HFunctor.Chain:chainPair andchain1Pair renamed totoChainandtoChain1, respectively, to mirrortoListBy andtoNonEmptyBy.

Version 0.3.0.0

August 5, 2020

https://github.com/mstksg/functor-combinators/releases/tag/v0.3.0.0

  • Data.HBifunctor.Associative,Data.HBifunctor.Tensor: Support forContravariant andInvariant functor combinators. Main change to theinfrastructure: add aFunctorBy associated constraint toAssociative tosignal what “sort of functor” the tensor supports: it should either beUnconstrained,Functor,Contravariant, orInvariant.

  • Data.Functor.Contravariant.Divise,Data.Functor.Contravariant.Decide,andData.Functor.Contravariant.Conclude: Temporarily add in thesemigroupoidal contravariant typeclasses. These should only be needed untilthey get merged intosemigroupoids.

  • Data.Functor.Contravariant.Divisible: Add free structures forcontravariant typeclass hierarchy.

  • Added in some new day convolutions:

    • Data.Functor.Contravariant.Night:Night, a contravariant dayconvolution usingEither, which is the tensor that generatesConclude (andDecidable kinda).
    • Data.Functor.Invariant.Day:Day, aninvariant day convolutionusing tuples.
    • Data.Functor.Invariant.Night:Night, aninvariant day convolutionusing either.

    For the invariant day convolutions, wecould write free monoids on them(likeAp/Div/Dec). But instead we just outsource our free structurestoChain, providing useful pattern synonyms and folding functions topretend like we had an actual free structure.

  • Data.Functor.Combinator: Useful functions in for working with divisibleand decidable contravariant functors:divideN,diviseN,concludeN,decideN,divideNRec, anddiviseNRec.

  • Contravariant andInvariant instances for many types.

  • Data.HFunctor.Final:FreeOf adjusted to allow for contravariant freetypes.

  • Data.Functor.Combinator.Unsafe: AddunsafeDivise andunsafeConclude,to mirror the situation withunsafeApply andunsafePlus.

Version 0.2.0.0

November 11, 2019

https://github.com/mstksg/functor-combinators/releases/tag/v0.2.0.0

  • Major restructuring of the hbifunctor-based classes.Data.HBifunctor.AssociativeandData.HBifunctor.Tensor are more or less completely rewritten; thetypeclasses are restructured in order to more properly reflect the maththat motivates them. See the updated type classes to see what methodsended up where.

    However, much of the external API that is independent of the underlyingabstraction is effectively unchanged (biget, etc.)

    For the most part, the migration would involve:

    • SF,MF are nowNonEmptyBy andListBy, respectively.
    • -SF and-MF as suffixes for function names now become-NE and-LB.

  • upgradeC no longer exists; use unsafe functions fromData.Functor.Combinator.Unsafe instead, on a per-tensor basis.

  • Restructuring ofInterpret: It now takes an extra type parameter, thetype to interpret into. This makes it more consistent with the newMonoidInandSemigroupIn. Most of the external API should be effectivelyunchanged.

    For the most part, the migration would only affect people whowriteinstances ofInterpret. Instead of

    instance Interpret MyType where    type C MyType = Monad

    you would write:

    instance Monad f => Interpret MyType f where

Version 0.1.1.1

July 13, 2019

https://github.com/mstksg/functor-combinators/releases/tag/v0.1.1.1

  • Moved totrivial-constraints-0.6.0.0

Version 0.1.1.0

June 19, 2019

https://github.com/mstksg/functor-combinators/releases/tag/v0.1.1.0

  • appendChain andappendChain1

Version 0.1.0.1

June 19, 2019

https://github.com/mstksg/functor-combinators/releases/tag/v0.1.0.1

  • Small tweaks for haddock generation and dependency bounds.

Version 0.1.0.0

June 19, 2019

https://github.com/mstksg/functor-combinators/releases/tag/v0.1.0.0

  • Initial release