A map of bean recipes, indexed by the TypeRep of the bean each recipe ultimately produces. Only one recipe is allowed for each bean type. Parameterized by the monad m in which the recipe Constructors might have effects.

Create a Cauldron consisting of a single Recipe.

recipe and singleton are the same function.

For readability, the bean type is often passed as a type application, despite not being strictly required:

>>> :{
oneRecipe :: Cauldron IO
oneRecipe = recipe @Bool $ val_ $ pure $ False
:}

Typical usage involves putting singleton Cauldrons in a list and mconcatting them:

>>> :{
twoRecipes :: Cauldron IO
twoRecipes = mconcat [
     recipe $ val_ $ pure $ False,
     recipe @Char $ val_ $ wire $ \(_ :: Bool) -> 'b'
   ]
:}

Create a Cauldron consisting of a single Recipe.

recipe and singleton are the same function.

For readability, the bean type is often passed as a type application, despite not being strictly required:

>>> :{
oneRecipe :: Cauldron IO
oneRecipe = recipe @Bool $ val_ $ pure $ False
:}

Typical usage involves putting singleton Cauldrons in a list and mconcatting them:

>>> :{
twoRecipes :: Cauldron IO
twoRecipes = mconcat [
     recipe $ val_ $ pure $ False,
     recipe @Char $ val_ $ wire $ \(_ :: Bool) -> 'b'
   ]
:}

Put a Recipe into the Cauldron.

Only one recipe is allowed for each bean type, so insert for a bean will overwrite any previous recipe for that bean.

Tweak a Recipe inside the Cauldron, if it exists there.

Access a Recipe inside a Cauldron, if it exists there.

A callback is used because Cauldrons are heterogenous containers.

Besides the Recipe, the callback also receives a NonEmpty list of CallStacks conveying the locations at which the the Recipe was added and adjusted.

The set of all TypeRep keys of the map.

Restrict a Cauldron to only those TypeReps found in a Set.

Change the monad used by the Recipes in the Cauldron.

More general form of hoistCauldron that lets you modify the Args inside all the Recipes in the Cauldron. See hoistRecipe'.

Instructions for how to build a value of type bean while possibly performing actions in the monad m.

Because the instructions aren't really run until the Cauldron is cooked, they can be modified with functions like adjust, in order to change the base bean Constructor or add or remove decorators.

Convenience typeclass that allows passing either Recipes or Constructors to the recipe and insert functions.

\( O(1) \). Add an element to the right end of a sequence. Mnemonic: a triangle with the single element at the pointy end.

\( O(1) \). Add an element to the left end of a sequence. Mnemonic: a triangle with the single element at the pointy end.

Change the monad used by the bean's main Constructor and its decos.

More general form of hoistRecipe that enables precise control over the inner Args of each constructor in the Recipe.

A way of building value of type bean, potentially requiring some dependencies, potentially returning some secondary aggregate beans along the primary bean result, and also potentially requiring some initialization effect in a monad m.

Note that only the type of the primary bean is reflected in the Constructor type. Those of the dependencies and aggregate beans are not.

Constructor doesn't have a Functor instance. This is beause sometimes a Constructor may depend on the same type of bean it produces, but the Functor instance would only change the output type, leading to confusing wiring errors.

A typical initialization monad will be IO, used for example to create mutable references that the bean will use internally. Sometimes the constructor will acquire resources with bracket-like operations, and in that case a monad like Managed might be needed instead.

An Applicative that knows how to construct values by searching in a Beans map, and keeps track of the types that will be searched in the Beans map.

Look for a type in the Beans map and return its corresponding value.

>>> :{
fun1 :: Bool -> Int
fun1 _ = 5
w1 :: Args Int
w1 = fun1 <$> arg
fun2 :: String -> Bool -> Int
fun2 _ _ = 5
w2 :: Args Int
w2 = fun2 <$> arg <*> arg
:}

Takes a curried function and reads all of its arguments by type using arg, returning an Args for the final result value of the function.

This function assumes that the tip is not a function, in order to know when to stop collecting arguments. If your intended tip is a function, you might need to wrap it in a newtype in order to disambiguate.

>>> :{
fun0 :: Int
fun0 = 5
w0 :: Args Int
w0 = wire fun0
fun1 :: Bool -> Int
fun1 _ = 5
w1 :: Args Int
w1 = wire fun1
fun2 :: String -> Bool -> Int
fun2 _ _ = 5
w2 :: Args Int
w2 = wire fun2
:}

Create a Constructor from an Args value that returns a bean.

Usually, the Args value will be created by wireing a constructor function.

>>> :{
data A = A
data B = B
makeB :: A -> B
makeB _ = B
c :: Constructor IO B
c = val_ $ wire $ makeB
:}

Create a Constructor from an Args value that returns an initialization effect that produces bean.

Usually, the Args value will be created by wireing an effectul constructor function.

>>> :{
data A = A
data B = B
makeB :: A -> IO B
makeB _ = pure B
c :: Constructor IO B
c = eff_ $ wire $ makeB
:}

Like eff_, but lifts IO constructor effects into a general MonadIO.

Like val_, but examines the nested value returned by the Args looking for (potentially nested) tuples. All tuple components except the rightmost-innermost one are registered as aggregate beans (if they have Monoid instances, otherwise val won't compile).

Because this function gives a special meaning to tuples, it shouldn't be used to wire beans that have themselves a tuple type. Better define a special-purpose bean datatype instead.

>>> :{
data A = A
data B = B
makeB :: A -> (Sum Int, Any, B)
makeB _ = (Sum 0, Any False, B)
c :: Constructor IO B
c = val $ wire $ makeB
makeB' :: A -> (Sum Int, (Any, B))
makeB' _ = (Sum 0, (Any False, B))
c' :: Constructor IO B
c' = val $ wire $ makeB
:}

Like val, but uses an alternative form of registering secondary beans. Less Registrable typeclass magic, but more verbose. Likely not what you want.

Like eff_, but examines the nested value produced by the action returned by the Args looking for (potentially nested) tuples. All tuple components except the rightmost-innermost one are registered as aggregate beans (if they have Monoid instances, otherwise eff won't compile).

Because this function gives a special meaning to tuples, it shouldn't be used to wire beans that have themselves a tuple type. Better define a special-purpose bean datatype instead.

>>> :{
data A = A
data B = B
makeB :: A -> IO (Sum Int, Any, B)
makeB _ = pure (Sum 0, Any False, B)
c :: Constructor IO B
c = eff $ wire $ makeB
makeB' :: A -> IO (Sum Int, (Any, B))
makeB' _ = pure (Sum 0, (Any False, B))
c' :: Constructor IO B
c' = eff $ wire $ makeB
:}

Like eff, but uses an alternative form of registering secondary beans. Less Registrable typeclass magic, but more verbose. Likely not what you want.

Like eff, but lifts IO constructor effects into a general MonadIO.

Get the inner Args value for the Constructor, typically for inspecting TypeReps of its arguments/registrations.

For debugging purposes, Constructors remember the CallStack of when they were created.

Change the monad in which the Constructor's effects take place.

More general form of hoistConstructor that enables precise control over the inner Args.

Build the requested bean using the Recipes stored in Cauldron. The Cauldrons must contain a Recipe for the requested bean, as well as Recipes for producing all of its transitive dependencies.

>>> :{
data A = A deriving Show
:}

>>> :{
(mempty :: Cauldron IO)
 & cook @A forbidDepCycles
 & \case Left (MissingResultBeanError _) -> "no recipe for requested bean"; _ -> "oops"
:}
"no recipe for requested bean"

>>> :{
data A = A deriving Show
data B = B A deriving Show
:}

>>> :{
(singleton $ val $ wire B :: Cauldron IO)
 & cook @B forbidDepCycles
 & \case Left (MissingDependenciesError _) -> "no recipe for A"; _ -> "oops"
:}
"no recipe for A"

Takes a Cauldron and converts it into a Constructor where any unfilled dependencies are taken as the arguments of the Constructor. The Constructor can later be included in a bigger Cauldron, which will provide the missing dependencies.

This function never fails with MissingDependenciesError.

This is an advanced function for when you want limited scopes for some beans. Usually cook is enough.

Consider these example definitions:

>>> :{
data A = A (IO ())
data B = B (IO ())
data C = C (IO ())
makeA :: A
makeA = A (putStrLn "A constructor")
makeA2 :: A
makeA2 = A (putStrLn "A2 constructor")
makeB :: A -> B
makeB (A a) = B (a >> putStrLn "B constructor")
makeC :: A -> B -> C
makeC = \(A a) (B b) -> C  (a >> b >> putStrLn "C constructor")
:}

This is a wiring that uses nest to create an scope that gives a local meaning to the bean A:

>>> :{
do
  nested :: Constructor IO C <- nest @C forbidDepCycles (mconcat [
      recipe @A $ val $ wire makeA2, -- this will be used by makeC
      recipe @C $ val $ wire makeC -- takes B from outside
      ]) & either throwIO pure
  action <- cook @C forbidDepCycles (mconcat [
      recipe @A $ val $ wire makeA,
      recipe @B $ val $ wire makeB,
      recipe @C $ nested
      ]) & either throwIO pure
  C c <- action
  c
:}
A2 constructor
A constructor
B constructor
C constructor

compare with this other wiring that uses a single Cauldron:

>>> :{
do
  action <- cook @C forbidDepCycles (mconcat [
      recipe @A $ val $ wire makeA,
      recipe @B $ val $ wire makeB,
      recipe @C $ val $ wire makeC
      ]) & either throwIO pure
  C c <- action
  c
:}
A constructor
A constructor
B constructor
C constructor

Strategy for dealing with dependency cycles.

(The name is admittedly uninformative; the culinary metaphor was stretched too far.)

Forbid any kind of cyclic dependencies between beans. This is probably what you want.

>>> :{
data A = A
loopyA :: A -> A
loopyA _ = A
:}

>>> :{
  (recipe @A $ val $ wire loopyA :: Cauldron IO)
     & cook @A forbidDepCycles
     & \case Left (DependencyCycleError _) -> "self dep is forbidden"; _ -> "oops"
:}
"self dep is forbidden"

Allow direct self-dependencies.

A bean constructor might depend on itself. This can be useful for having decorated self-invocations, because the version of the bean received as argument comes "from the future" and is already decorated.

Note that a MonadFix instance is required of the initialization monad.

BEWARE: Pattern-matching too eagerly on a "bean from the future" during construction will cause infinite loops or, if you are lucky, throw FixIOExceptions.

>>> :{
data A = A
loopyA :: A -> A
loopyA _ = A
:}

>>> :{
  (recipe @A $ val $ wire loopyA :: Cauldron IO)
      & cook @A allowSelfDeps
      & \case Left (DependencyCycleError _) -> "oops"; _ -> "self dep is ok"
:}
"self dep is ok"

>>> :{
data U = U
data V = V
loopyU :: V -> U
loopyU _ = U
loopyV :: U -> V
loopyV _ = V
:}

>>> :{
  mconcat [
      recipe @U $ val $ wire loopyU,
      recipe @V $ val $ wire loopyV :: Cauldron IO
  ]
   & cook @U allowSelfDeps
   & \case Left (DependencyCycleError _) -> "cycle between 2 deps"; _ -> "oops"
:}
"cycle between 2 deps"

Allow any kind of dependency cycles.

Usually comes in handy for creating serializers / deserializers for mutually dependent types.

Note that a MonadFix instance is required of the initialization monad.

BEWARE: Pattern-matching too eagerly on argument beans during construction will cause infinite loops or, if you are lucky, throw FixIOExceptions.

>>> :{
data U = U
data V = V
loopyU :: V -> U
loopyU _ = U
loopyV :: U -> V
loopyV _ = V
:}

>>> :{
  mconcat [
      recipe @U $ val $ wire loopyU,
      recipe @V $ val $ wire loopyV :: Cauldron IO
  ]
    & cook @U allowDepCycles
    & \case Left (DependencyCycleError _) -> "oops"; _ -> "cycles are ok"
:}
"cycles are ok"

Sometimes the cooking process goes wrong.

Missing depencencies for a Constructor.

Get a graph of dependencies between BeanConstructionSteps. The graph can be obtained even if the mconcatted Cauldrons can't be cooked successfully.

An edge means that the source depends on the target.

The dependencies of each bean are given separatedly from its decorators.

See the DOT format.

Default DOT rendering style to use with writeAsDot. When a CookingError exists, is highlights the problematic BeanConstructionSteps.

Change the default way of how BeanConstructionSteps are rendered to text.

A step in the construction of a bean value.

Conversion to a graph type for further processing.

Remove all vertices and edges related to secondary beans.

Remove all vertices and edges related to bean decorators.

Unifies FinishedBeans with their respective BarePrimaryBeans, PrimaryBeanDecos and AggregateBeans.

Also removes any self-loops.