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


-- | Disambiguate obvious uses of effects.
--   
--   Please see the README on GitHub at
--   <a>https://github.com/isovector/polysemy/tree/master/polysemy-plugin#readme</a>
@package polysemy-plugin
@version 0.2.4.0

module Polysemy.Plugin.Fundep.Stuff

-- | All of the things from "polysemy" that we need access to in the
--   plugin. When <tt>l ~ 'Locations</tt>, each of these is just a pair of
--   strings. When <tt>l ~ 'Things</tt>, it's actually references to the
--   stuff.
data PolysemyStuff (l :: LookupState)
PolysemyStuff :: ThingOf l Class -> ThingOf l TyCon -> ThingOf l TyCon -> ThingOf l TyCon -> PolysemyStuff
[findClass] :: PolysemyStuff -> ThingOf l Class
[semTyCon] :: PolysemyStuff -> ThingOf l TyCon
[ifStuckTyCon] :: PolysemyStuff -> ThingOf l TyCon
[indexOfTyCon] :: PolysemyStuff -> ThingOf l TyCon

-- | Data kind for <a>ThingOf</a>.
data LookupState
Locations :: LookupState
Things :: LookupState

-- | Lookup all of the <a>PolysemyStuff</a>.
polysemyStuff :: TcPluginM (PolysemyStuff  'Things)
instance Polysemy.Plugin.Fundep.Stuff.CanLookup Class.Class
instance Polysemy.Plugin.Fundep.Stuff.CanLookup TyCon.TyCon

module Polysemy.Plugin.Fundep.Unification

-- | The context in which we're attempting to solve a constraint.
data SolveContext

-- | In the context of a function definition.
FunctionDef :: SolveContext

-- | In the context of running an interpreter. The <a>Bool</a> corresponds
--   to whether we are only trying to solve a single <tt>Member</tt>
--   constraint right now. If so, we *must* produce a unification wanted.
InterpreterUse :: Bool -> SolveContext

-- | Depending on the context in which we're solving a constraint, we may
--   or may not want to force a unification of effects. For example, when
--   defining user code whose type is <tt>Member (State Int) r =&gt;
--   ...</tt>, if we see <tt>get :: Sem r s</tt>, we should unify <tt>s ~
--   Int</tt>.
mustUnify :: SolveContext -> Bool

-- | Determine whether or not two effects are unifiable. This is nuanced.
--   
--   There are several cases:
--   
--   <ol>
--   <li>[W] ∀ e1. e1 [G] ∀ e2. e2 Always fails, because we never want to
--   unify two effects if effect names are polymorphic.</li>
--   <li>[W] State s [G] State Int Always succeeds. It's safe to take our
--   given as a fundep annotation.</li>
--   <li>[W] State Int [G] State s (when the [G] is a given that comes from
--   a type signature)</li>
--   </ol>
--   
--   This should fail, because it means we wrote the type signature
--   <tt>Member (State s) r =&gt; ...</tt>, but are trying to use
--   <tt>s</tt> as an <tt>Int</tt>. Clearly bogus!
--   
--   <ol>
--   <li>[W] State Int [G] State s (when the [G] was generated by running
--   an interpreter)</li>
--   </ol>
--   
--   Sometimes OK, but only if the [G] is the only thing we're trying to
--   solve right now. Consider the case:
--   
--   runState 5 $ pure @(Sem (State Int ': r)) ()
--   
--   Here we have [G] forall a. Num a =&gt; State a and [W] State Int.
--   Clearly the typechecking should flow "backwards" here, out of the row
--   and into the type of <tt>runState</tt>.
--   
--   What happens if there are multiple [G]s in scope for the same
--   <tt>r</tt>? Then we'd emit multiple unification constraints for the
--   same effect but with different polymorphic variables, which would
--   unify a bunch of effects that shouldn't be!
canUnifyRecursive :: SolveContext -> Type -> Type -> Bool

-- | A non-recursive version of <a>canUnifyRecursive</a>.
canUnify :: Bool -> Type -> Type -> Bool

-- | A wrapper for two types that we want to say have been unified.
data Unification
Unification :: OrdType -> OrdType -> Unification
[_unifyLHS] :: Unification -> OrdType
[_unifyRHS] :: Unification -> OrdType

-- | <a>Type</a>s don't have <a>Eq</a> or <a>Ord</a> instances by default,
--   even though there are functions in GHC that implement these
--   operations. This newtype gives us those instances.
newtype OrdType
OrdType :: Type -> OrdType
[getOrdType] :: OrdType -> Type

-- | Filter out the unifications we've already emitted, and then give back
--   the things we should put into the <tt>S.Set Unification</tt>, and the
--   new constraints we should emit.
unzipNewWanteds :: Set Unification -> [(Unification, Ct)] -> ([Unification], [Ct])
instance GHC.Classes.Ord Polysemy.Plugin.Fundep.Unification.Unification
instance GHC.Classes.Eq Polysemy.Plugin.Fundep.Unification.Unification
instance GHC.Show.Show Polysemy.Plugin.Fundep.Unification.SolveContext
instance GHC.Classes.Ord Polysemy.Plugin.Fundep.Unification.SolveContext
instance GHC.Classes.Eq Polysemy.Plugin.Fundep.Unification.SolveContext
instance GHC.Classes.Eq Polysemy.Plugin.Fundep.Unification.OrdType
instance GHC.Classes.Ord Polysemy.Plugin.Fundep.Unification.OrdType

module Polysemy.Plugin.Fundep.Utils

-- | Returns the head of the list iff there is exactly one element.
singleListToJust :: [a] -> Maybe a

-- | Like <a>when</a>, but in the context of an <a>Alternative</a>.
whenA :: (Monad m, Alternative z) => Bool -> m a -> m (z a)

-- | Count the number of times <tt>a</tt> is present in the list.
countLength :: Eq a => [a] -> [(a, Int)]

module Polysemy.Plugin.Fundep
fundepPlugin :: TcPlugin


-- | A typechecker plugin that can disambiguate "obvious" uses of effects
--   in Polysemy.
--   
--   <b>Example:</b>
--   
--   Consider the following program:
--   
--   <pre>
--   foo :: <a>Member</a> (<a>State</a> Int) r =&gt; <a>Sem</a> r ()
--   foo = <a>put</a> 10
--   </pre>
--   
--   What does this program do? Any human will tell you that it changes the
--   state of the <a>Int</a> to 10, which is clearly what's meant.
--   
--   Unfortunately, Polysemy can't work this out on its own. Its reasoning
--   is "maybe you wanted to change some other <a>State</a> effect which is
--   <i>also</i> a <a>Num</a>, but you just forgot to add a <a>Member</a>
--   constraint for it."
--   
--   This is obviously insane, but it's the way the cookie crumbles.
--   <a>Plugin</a> is a typechecker plugin which will disambiguate the
--   above program (and others) so the compiler will do what you want.
--   
--   <b>Usage:</b>
--   
--   Add the following line to your package configuration:
--   
--   <pre>
--   ghc-options: -fplugin=Polysemy.Plugin
--   </pre>
--   
--   <b>Limitations:</b>
--   
--   The <a>Plugin</a> will only disambiguate effects if there is exactly
--   one relevant constraint in scope. For example, it will <i>not</i>
--   disambiguate the following program:
--   
--   <pre>
--   bar :: <a>Members</a> '[ <a>State</a> Int
--                   , <a>State</a> Double
--                   ] r =&gt; <a>Sem</a> r ()
--   bar = <a>put</a> 10
--   </pre>
--   
--   because it is now unclear whether you're attempting to set the
--   <a>Int</a> or the <a>Double</a>. Instead, you can manually write a
--   type application in this case.
--   
--   <pre>
--   bar :: <a>Members</a> '[ <a>State</a> Int
--                   , <a>State</a> Double
--                   ] r =&gt; <a>Sem</a> r ()
--   bar = <a>put</a> @Int 10
--   </pre>
module Polysemy.Plugin
plugin :: Plugin

module Polysemy.Plugin.Phases
extraPhases :: DynFlags -> [CoreToDo]