-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Toy dependency injection framework
--   
--   Toy dependency injection framework that wires things at runtime.
@package cauldron
@version 0.4.0.0


-- | This is a library for performing dependency injection. It's an
--   alternative to manually wiring your functions and passing all required
--   parameters explicitly. Instead of that, you throw your functions into
--   a <a>Cauldron</a>, which wires them for you, guiding itself by the
--   types.
--   
--   Wiring errors are detected at runtime, not at compile time.
--   
--   This library should be used at the <a>"composition root"</a> of the
--   application, and only there: the components we are wiring together
--   need not be aware that the library exists.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data A = A deriving Show
--   data B = B deriving Show
--   data C = C deriving Show
--   makeA :: A
--   makeA = A
--   makeB :: A -&gt; B
--   makeB = \_ -&gt; B
--   makeC :: A -&gt; B -&gt; IO C
--   makeC = \_ _ -&gt; pure C
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   do
--     let cauldron :: Cauldron IO
--         cauldron =
--           emptyCauldron
--           &amp; insert @A do makeBean do pack value makeA
--           &amp; insert @B do makeBean do pack value makeB
--           &amp; insert @C do makeBean do pack effect makeC
--         Right (_ :: DependencyGraph, action) = cook forbidDepCycles cauldron
--     beans &lt;- action
--     pure do taste @C beans
--   :}
--   Just C
--   </pre>
module Cauldron

-- | A map of <a>Bean</a> recipes. Parameterized by the monad <tt>m</tt> in
--   which the <a>Bean</a> <a>Constructor</a>s might have effects.
data Cauldron (m :: Type -> Type)
emptyCauldron :: forall (m :: Type -> Type). Cauldron m

-- | Put a recipe for a <a>Bean</a> into the <a>Cauldron</a>.
--   
--   Only one recipe is allowed for each different <tt>bean</tt> type, so
--   <a>insert</a> for a <tt>bean</tt> will overwrite previous recipes for
--   that type.
insert :: forall bean (m :: Type -> Type). Typeable bean => Bean m bean -> Cauldron m -> Cauldron m

-- | Tweak an already existing <a>Bean</a> recipe.
adjust :: forall bean (m :: Type -> Type). Typeable bean => (Bean m bean -> Bean m bean) -> Cauldron m -> Cauldron m
delete :: forall {k} (bean :: k) (m :: Type -> Type). Typeable bean => Cauldron m -> Cauldron m

-- | Change the monad used by the beans in the <a>Cauldron</a>.
hoistCauldron :: (forall x. () => m x -> n x) -> Cauldron m -> Cauldron n

-- | A bean recipe, to be inserted into a <a>Cauldron</a>.
data Bean (m :: Type -> Type) bean
[Bean] :: forall (m :: Type -> Type) bean. Constructor m bean -> Decos m bean -> Bean m bean

-- | A <a>Bean</a> without decorators, having only the main constructor.
makeBean :: forall (m :: Type -> Type) a. Constructor m a -> Bean m a
setConstructor :: forall (m :: Type -> Type) bean. Constructor m bean -> Bean m bean -> Bean m bean
setDecos :: forall (m :: Type -> Type) bean. Decos m bean -> Bean m bean -> Bean m bean
overDecos :: forall (m :: Type -> Type) bean. (Decos m bean -> Decos m bean) -> Bean m bean -> Bean m bean

-- | Change the monad used by the bean's <a>Constructor</a> and its
--   <a>Decos</a>.
hoistBean :: (forall x. () => m x -> n x) -> Bean m bean -> Bean n bean

-- | A list of <a>Constructor</a>s for the decorators of some <a>Bean</a>.
--   
--   <a>Constructor</a>s for a decorator will have the <tt>bean</tt> itself
--   among their arguments. That <tt>bean</tt> argument will be either the
--   "bare" undecorated bean (for the first decorator) or the result of
--   applying the previous decorator in the list.
--   
--   Decorators can have other dependencies besides the <tt>bean</tt>.
data Decos (m :: Type -> Type) bean

-- | Empty list of decorators.
emptyDecos :: forall (m :: Type -> Type) bean. Decos m bean

-- | Build the decorators from a list of <a>Constructor</a>s, first
--   innermost, last outermost.
fromConstructors :: forall (m :: Type -> Type) bean. [Constructor m bean] -> Decos m bean

-- | Add a new decorator that modifies the bean <i>after</i> all existing
--   decorators.
--   
--   This means the behaviours it adds to the bean's methods will be
--   applied <i>first</i> when entering the method.
addOuter :: forall (m :: Type -> Type) bean. Constructor m bean -> Decos m bean -> Decos m bean

-- | Add a new decorator that modifies the bean <i>before</i> all existing
--   decorators.
--   
--   This means the behaviours it adds to the bean's methods will be
--   applied <i>last</i>, just before entering the base bean's method.
--   
--   Usually <a>addOuter</a> is preferrable.
addInner :: forall (m :: Type -> Type) bean. Constructor m bean -> Decos m bean -> Decos m bean

-- | Change the monad used by the decorators.
hoistDecos :: (forall x. () => m x -> n x) -> Decos m bean -> Decos n bean

-- | A way of building some <tt>bean</tt> value, potentially requiring some
--   dependencies, potentially returning some secondary beans along the
--   primary <tt>bean</tt> result, and also potentially requiring some
--   initialization effect in a monad <tt>m</tt>.
--   
--   Note that only the type of the primary <tt>bean</tt> is reflected in
--   the <a>Constructor</a> type. Those of the dependencies and secondary
--   beans are not.
--   
--   A typical initialization monad will be <a>IO</a>, used for example to
--   create mutable references that the bean will use internally. Sometimes
--   the a constructor will allocate resources with bracket-like
--   operations, and in that case a monad like <tt>Managed</tt> might be
--   needed instead.
data Constructor (m :: Type -> Type) bean

-- | Take a curried function that constructs a bean, uncurry it recursively
--   and then apply a <a>Packer</a> to its tip, resulting in a
--   <a>Constructor</a>.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data A = A deriving Show
--   data B = B deriving Show
--   data C = C deriving Show
--   makeB :: A -&gt; B
--   makeB = \_ -&gt; B
--   makeC :: A -&gt; B -&gt; IO C
--   makeC = \_ _ -&gt; pure C
--   constructorB :: Constructor IO B
--   constructorB = pack value makeB
--   constructorC :: Constructor IO C
--   constructorC = pack effect makeC
--   :}
--   </pre>
--   
--   There are <a>pack0</a>, <a>pack1</a>... functions which work for
--   specific number of arguments, but the generic <a>pack</a> should work
--   in most cases anyway.
pack :: forall (args :: [Type]) r curried (regs :: [Type]) bean (m :: Type -> Type). (MulticurryableF args r curried (IsFunction curried), All (Typeable :: Type -> Constraint) args, All (And (Typeable :: Type -> Constraint) Monoid) regs) => Packer m regs bean r -> curried -> Constructor m bean

-- | Slightly simpler version of <a>pack</a> for <tt>0</tt>-argument
--   functions.
pack0 :: forall (regs :: [Type]) (m :: Type -> Type) bean r. All (And (Typeable :: Type -> Constraint) Monoid) regs => Packer m regs bean r -> r -> Constructor m bean

-- | Slightly simpler version of <a>pack</a> for <tt>1</tt>-argument
--   functions.
pack1 :: forall arg1 r (m :: Type -> Type) (regs :: [Type]) bean. (Typeable arg1, All (And (Typeable :: Type -> Constraint) Monoid) regs) => Packer m regs bean r -> (arg1 -> r) -> Constructor m bean

-- | Slightly simpler version of <a>pack</a> for <tt>2</tt>-argument
--   functions.
pack2 :: forall arg1 arg2 r (m :: Type -> Type) (regs :: [Type]) bean. (Typeable arg1, Typeable arg2, All (And (Typeable :: Type -> Constraint) Monoid) regs) => Packer m regs bean r -> (arg1 -> arg2 -> r) -> Constructor m bean

-- | Slightly simpler version of <a>pack</a> for <tt>3</tt>-argument
--   functions.
pack3 :: forall arg1 arg2 arg3 r (m :: Type -> Type) (regs :: [Type]) bean. (Typeable arg1, Typeable arg2, Typeable arg3, All (And (Typeable :: Type -> Constraint) Monoid) regs) => Packer m regs bean r -> (arg1 -> arg2 -> arg3 -> r) -> Constructor m bean

-- | Change the monad in which the <a>Constructor</a>'s effects take place.
hoistConstructor :: (forall x. () => m x -> n x) -> Constructor m bean -> Constructor n bean

-- | Applies a transformation to the tip of a curried function, coaxing it
--   into the shape expected by a <a>Constructor</a>, which includes
--   information about which is the primary bean and which are the
--   secondary ones.
--   
--   <ul>
--   <li>For pure constructors without registrations, try
--   <a>value</a>.</li>
--   <li>For effectful constructors without registrations, try
--   <a>effect</a>.</li>
--   </ul>
--   
--   More complex cases might require <a>valueWith</a>, <a>effectWith</a>,
--   or working with the <a>Packer</a> constructor itself.
newtype Packer (m :: Type -> Type) (regs :: [Type]) bean r
Packer :: (r -> m (Regs regs bean)) -> Packer (m :: Type -> Type) (regs :: [Type]) bean r

-- | For pure constructors that return the <tt>bean</tt> directly, and do
--   not register secondary beans.
value :: forall (m :: Type -> Type) bean. Applicative m => Packer m ('[] :: [Type]) bean bean

-- | For effectul constructors that return an <tt>m bean</tt>
--   initialization action, and do not register secondary beans.
effect :: Applicative m => Packer m ('[] :: [Type]) bean (m bean)

-- | <pre>
--   &gt;&gt;&gt; :{
--   data A = A deriving Show
--   data B = B deriving Show
--   makeB :: A -&gt; (Sum Int, B)
--   makeB = \_ -&gt; (Sum 1, B)
--   constructorB :: Constructor IO B
--   constructorB = pack (valueWith \(s,bean) -&gt; regs1 s bean) makeB
--   :}
--   </pre>
valueWith :: forall (m :: Type -> Type) (regs :: [Type]) r bean. (Applicative m, All (And (Typeable :: Type -> Constraint) Monoid) regs) => (r -> Regs regs bean) -> Packer m regs bean r

-- | <pre>
--   &gt;&gt;&gt; :{
--   data A = A deriving Show
--   data B = B deriving Show
--   makeB :: A -&gt; IO (Sum Int, B)
--   makeB = \_ -&gt; pure (Sum 1, B)
--   constructorB :: Constructor IO B
--   constructorB = pack (effectWith \(s,bean) -&gt; regs1 s bean) makeB
--   :}
--   </pre>
effectWith :: forall m (regs :: [Type]) r bean. (Applicative m, All (And (Typeable :: Type -> Constraint) Monoid) regs) => (r -> Regs regs bean) -> Packer m regs bean (m r)

-- | Auxiliary type which contains a primary bean along with zero or more
--   secondary beans. The secondary beans must have <a>Monoid</a>
--   instances.
data Regs (regs :: [Type]) bean

-- | A primary <tt>bean</tt> without secondary beans.
regs0 :: bean -> Regs ('[] :: [Type]) bean

-- | A primary <tt>bean</tt> with one secondary bean.
regs1 :: reg1 -> bean -> Regs '[reg1] bean

-- | A primary <tt>bean</tt> with two secondary beans.
regs2 :: reg1 -> reg2 -> bean -> Regs '[reg1, reg2] bean

-- | A primary <tt>bean</tt> with three secondary beans.
regs3 :: reg1 -> reg2 -> reg3 -> bean -> Regs '[reg1, reg2, reg3] bean

-- | Build the beans using the recipes stored in the <a>Cauldron</a>.
cook :: Monad m => Fire m -> Cauldron m -> Either BadBeans (DependencyGraph, m BoiledBeans)

-- | Cook a list of <a>Cauldron</a>s.
--   
--   <a>Cauldron</a>s later in the list can see the beans in all previous
--   <a>Cauldron</a>s, but not vice versa.
--   
--   Beans in a <a>Cauldron</a> have priority over the same beans in
--   previous <a>Cauldron</a>s.
cookNonEmpty :: Monad m => NonEmpty (Fire m, Cauldron m) -> Either BadBeans (NonEmpty DependencyGraph, m (NonEmpty BoiledBeans))

-- | Cook a hierarchy of <a>Cauldron</a>s.
--   
--   <a>Cauldron</a>s down in the branches can see the beans of their
--   ancestor <a>Cauldron</a>s, but not vice versa.
--   
--   Beans in a <a>Cauldron</a> have priority over the same beans in
--   ancestor <a>Cauldron</a>s.
cookTree :: Monad m => Tree (Fire m, Cauldron m) -> Either BadBeans (Tree DependencyGraph, m (Tree BoiledBeans))

-- | Strategy for dealing with dependency cycles.
--   
--   (Terrible uninformative name caused by a metaphor stretched too far.)
data Fire (m :: Type -> Type)

-- | Forbid any kind of cyclic dependencies between beans. This is probably
--   what you want.
forbidDepCycles :: forall (m :: Type -> Type). Monad m => Fire m

-- | Allow <i>direct</i> 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.
--   (<b>BEWARE</b>: Pattern-matching too eagerly on this "bean from the
--   future" during construction will cause infinite loops.)
--   
--   Note that a <a>MonadFix</a> instance is required of the initialization
--   monad.
allowSelfDeps :: forall (m :: Type -> Type). MonadFix m => Fire m

-- | The successful result of <a>cook</a>ing a <a>Cauldron</a>. Can't do a
--   lot with them other than to <a>taste</a> them.
data BoiledBeans

-- | Return the resulting <tt>bean</tt>, if present.
taste :: Typeable bean => BoiledBeans -> Maybe bean

-- | Sometimes the <a>cook</a>ing process goes wrong.
data BadBeans

-- | The <a>Cauldron</a> identified by <a>PathToCauldron</a> has beans that
--   depend on beans that can't be found either in the current
--   <a>Cauldron</a> or its ancestors.
MissingDependencies :: PathToCauldron -> Map TypeRep (Set TypeRep) -> BadBeans

-- | Beans that work both as primary beans and as secondary beans are
--   disallowed.
DoubleDutyBeans :: Set TypeRep -> BadBeans

-- | Dependency cycles are disallowed by some <a>Fire</a>s.
DependencyCycle :: NonEmpty BeanConstructionStep -> BadBeans

-- | Will always be <tt>[]</tt> when using <a>cook</a>; identifies a
--   <a>Cauldron</a> in a hierarchy of <a>Cauldron</a>s when using
--   <a>cookNonEmpty</a> or <a>cookTree</a>.
type PathToCauldron = [Int]

-- | An edge means that the source depends on the target.
--   
--   The dependencies of each bean are given separatedly from its
--   decorators.
data DependencyGraph

-- | See the <a>DOT format</a>.
exportToDot :: (BeanConstructionStep -> Text) -> FilePath -> DependencyGraph -> IO ()
defaultStepToText :: BeanConstructionStep -> Text

-- | A step in the construction of a bean value.
data BeanConstructionStep

-- | Undecorated bean.
BarePrimaryBean :: TypeRep -> BeanConstructionStep

-- | Apply the decorator with the given index. Comes after the
--   <a>BarePrimaryBean</a> and all <a>PrimaryBeanDeco</a>s with a lower
--   index value.
PrimaryBeanDeco :: TypeRep -> Int -> BeanConstructionStep

-- | Final, fully decorated version of a bean. If there are no decorators,
--   comes directly after <a>BarePrimaryBean</a>.
PrimaryBean :: TypeRep -> BeanConstructionStep

-- | Beans that are secondary registrations of a <a>Constructor</a> and
--   which are aggregated monoidally.
SecondaryBean :: TypeRep -> BeanConstructionStep
removeSecondaryBeans :: DependencyGraph -> DependencyGraph
removeDecos :: DependencyGraph -> DependencyGraph

-- | Unifies <a>PrimaryBean</a>s with their respective
--   <a>BarePrimaryBean</a>s and <a>PrimaryBeanDeco</a>s.
--   
--   Also removes any self-loops.
collapsePrimaryBeans :: DependencyGraph -> DependencyGraph

-- | Conversion to a graph type from the <a>algebraic-graphs</a> library
--   for further processing.
toAdjacencyMap :: DependencyGraph -> AdjacencyMap BeanConstructionStep
instance GHC.Internal.Base.Applicative (Cauldron.Args args)
instance GHC.Internal.Base.Applicative Cauldron.Extractor
instance Data.Functor.Contravariant.Contravariant (Cauldron.Packer m regs bean)
instance GHC.Classes.Eq Cauldron.BeanConstructionStep
instance GHC.Internal.Base.Functor (Cauldron.Args args)
instance GHC.Internal.Base.Functor Cauldron.Extractor
instance GHC.Internal.Base.Functor (Cauldron.Regs regs)
instance GHC.Internal.IsList.IsList (Cauldron.Decos m bean)
instance GHC.Internal.Base.Monad (Cauldron.Args args)
instance GHC.Internal.Base.Monoid (Cauldron.Cauldron m)
instance GHC.Internal.Base.Monoid (Cauldron.Decos m bean)
instance GHC.Classes.Ord Cauldron.BeanConstructionStep
instance GHC.Internal.Base.Semigroup (Cauldron.Cauldron m)
instance GHC.Internal.Base.Semigroup (Cauldron.Decos m bean)
instance GHC.Internal.Show.Show Cauldron.BadBeans
instance GHC.Internal.Show.Show Cauldron.BeanConstructionStep

module Cauldron.Managed

-- | This is a copy of the <tt>Managed</tt> type from the <a>managed</a>
--   package, with a dodgy <a>MonadFix</a> instance tacked on.
data Managed a

-- | Build a <a>Managed</a> value from a <tt>withFoo</tt>-style
--   resource-handling function that accepts a continuation, like
--   <a>withFile</a>.
--   
--   Passing functions that do weird things like running their continuation
--   <i>twice</i> will tear apart the fabric of reality. Why would you want
--   to do that? Pass only <tt>withFoo</tt>-style functions.
managed :: (forall r. () => (a -> IO r) -> IO r) -> Managed a

-- | Make use of the managed resource by supplying a callback.
with :: Managed a -> (a -> IO b) -> IO b
instance GHC.Internal.Base.Applicative Cauldron.Managed.Managed
instance GHC.Internal.Base.Functor Cauldron.Managed.Managed
instance GHC.Internal.Control.Monad.Fix.MonadFix Cauldron.Managed.Managed
instance Control.Monad.IO.Class.MonadIO Cauldron.Managed.Managed
instance GHC.Internal.Base.Monad Cauldron.Managed.Managed