| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Dep.SimpleAdvice
Description
This module provides the Advice datatype, along for functions for creating,
manipulating, composing and applying values of that type.
Advices are type-preserving transformations on effectful functions of
any number of arguments.
For example, assuming we have a record-of-functions like
>>>:{data Env m = Env { foo :: m () , bar :: Int -> m (Maybe Char) , baz :: Int -> Bool -> m Char } deriving Generic env :: Env IO env = Env { foo = pure () , bar = \_ -> pure (Just 'c') , baz = \_ _ -> pure 'i' } :}
We can modify all the functions in the record in this way:
>>>:{env' :: Env IO env' = env & advising (adviseRecord @_ @Top \_ -> printArgs stdout "prefix ") :}
using the printArgs advice.
Or modify an individual function in this way:
>>>:{env' :: Env IO env' = env & advising \env -> env { bar = advise (printArgs stdout "prefix ") (bar env) } :}
NOTE:
This module is an alternative to Control.Monad.Dep.Advice with two advantages:
- It doesn't use
DepT. The types are simpler because they don't need to refer toDepT's environment. - Unlike in Control.Monad.Dep.Advice, we can advise components
which work on a fixed concrete monad like
IO.
Compared with Control.Monad.Dep.Advice, it does require the extra step
of invoking the advising helper function on a record-of-functions.
Synopsis
- advising :: Coercible (r_ m) (r_ (AspectT m)) => (r_ (AspectT m) -> r_ (AspectT m)) -> r_ m -> r_ m
- newtype AspectT (m :: Type -> Type) (r :: Type) = AspectT {
- runAspectT :: m r
- data Advice (ca :: Type -> Constraint) m r
- makeAdvice :: forall ca m r. (forall as. All ca as => NP I as -> AspectT m (AspectT m r -> AspectT m r, NP I as)) -> Advice ca m r
- makeArgsAdvice :: forall ca m r. Monad m => (forall as. All ca as => NP I as -> AspectT m (NP I as)) -> Advice ca m r
- makeExecutionAdvice :: forall ca m r. Applicative m => (AspectT m r -> AspectT m r) -> Advice ca m r
- advise :: forall ca m r as advisee. (Multicurryable as m r advisee, All ca as, Monad m) => Advice ca m r -> advisee -> advisee
- restrictArgs :: forall more less m r. (forall x. Dict more x -> Dict less x) -> Advice less m r -> Advice more m r
- adviseRecord :: forall ca cr m advised. AdvisedRecord ca m cr advised => (forall r. cr r => NonEmpty (TypeRep, String) -> Advice ca m r) -> advised (AspectT m) -> advised (AspectT m)
- class Top (x :: k)
- class (f x, g x) => And (f :: k -> Constraint) (g :: k -> Constraint) (x :: k)
- class (AllF c xs, SListI xs) => All (c :: k -> Constraint) (xs :: [k])
- data NP (a :: k -> Type) (b :: [k]) where
- newtype I a = I a
- cfoldMap_NP :: forall k c (xs :: [k]) m proxy f. (All c xs, Monoid m) => proxy c -> (forall (a :: k). c a => f a -> m) -> NP f xs -> m
- data Dict (c :: k -> Constraint) (a :: k) where
- Dict :: forall k (c :: k -> Constraint) (a :: k). c a => Dict c a
Preparing components for being advised
Arguments
| :: Coercible (r_ m) (r_ (AspectT m)) | |
| => (r_ (AspectT m) -> r_ (AspectT m)) | transform the record coerced to |
| -> r_ m | transform the original record |
| -> r_ m |
This function "installs" an AspectT newtype wrapper for the monad
parameter of a record-of-functions, applies some function on
the tweaked component, and then removes the wrapper from the result.
This is necessary because the typeclass machinery which handles
Advices uses AspectT as a "mark" to recognize "the end of the function".
newtype AspectT (m :: Type -> Type) (r :: Type) Source #
This transformer is isomorphic to IdentityT.
It doesn't really do anything, it only helps the typeclass machinery.
Constructors
| AspectT | |
Fields
| |
Instances
The Advice type
data Advice (ca :: Type -> Constraint) m r Source #
A generic transformation of AspectT-effectful functions with
base monad m and return type r,
provided the functions satisfy certain constraint ca
on all of their arguments.
Advices that don't care about the ca constraint (because they don't
touch function arguments) can leave it polymorphic, and this facilitates
Advice composition, but then the constraint must be given the catch-all
Top value (using a type application) at the moment of calling advise.
See Control.Monad.Dep.SimpleAdvice.Basic for examples.
Instances
| Monad m => Semigroup (Advice ca m r) Source # |
The first |
| Monad m => Monoid (Advice ca m r) Source # | |
Creating Advice values
Arguments
| :: forall ca m r. (forall as. All ca as => NP I as -> AspectT m (AspectT m r -> AspectT m r, NP I as)) | The function that tweaks the arguments and the execution. |
| -> Advice ca m r |
The most general way of constructing Advices.
An Advice receives the arguments of the advised
function packed into an n-ary product NP, performs some
effects based on them, and returns a potentially modified version of the
arguments, along with a function for tweaking the execution of the
advised function.
>>>:{doesNothing :: forall ca m r. Monad m => Advice ca m r doesNothing = makeAdvice (\args -> pure (id, args)) :}
Arguments
| :: forall ca m r. Monad m | |
| => (forall as. All ca as => NP I as -> AspectT m (NP I as)) | The function that tweaks the arguments. |
| -> Advice ca m r |
Create an advice which only tweaks and/or analyzes the function arguments.
>>>:{doesNothing :: forall ca m r. Monad m => Advice ca m r doesNothing = makeArgsAdvice pure :}
Arguments
| :: forall ca m r. Applicative m | |
| => (AspectT m r -> AspectT m r) | The function that tweaks the execution. |
| -> Advice ca m r |
Create an advice which only tweaks the execution of the final monadic action.
>>>:{doesNothing :: forall ca m r. Monad m => Advice ca m r doesNothing = makeExecutionAdvice id :}
Applying Advices
Arguments
| :: forall ca m r as advisee. (Multicurryable as m r advisee, All ca as, Monad m) | |
| => Advice ca m r | The advice to apply. |
| -> advisee | A function to be adviced. |
| -> advisee |
Apply an Advice to some compatible function. The function must have its
effects in AspectT, and all of its arguments must satisfy the ca constraint.
>>>:{foo :: Int -> AspectT IO String foo _ = pure "foo" advisedFoo = advise (printArgs stdout "Foo args: ") foo :}
TYPE APPLICATION REQUIRED! If the ca constraint of the Advice remains polymorphic,
it must be supplied by means of a type application:
>>>:{bar :: Int -> AspectT IO String bar _ = pure "bar" advisedBar1 = advise (returnMempty @Top) bar advisedBar2 = advise @Top returnMempty bar :}
Harmonizing Advice argument constraints
Advice values can be composed using the Monoid instance, but only if
they have the same type parameters. It's unfortunate that—unlike with
normal function constraints—the ca constraints of an Advice aren't
automatically "collected" during composition.
Instead, we need to harmonize the ca constraints of each Advice by
turning them into the combination of all constraints. restrictArgs
helps with that.
restrictArgs takes as parameter value-level "evidence" that one
constraint implies another. But how to construct such evidence? By using
the Dict GADT, more precisely the deceptively simple-looking term
\Dict -> Dict. That function "absorbs" some constraint present in the
ambient context and re-packages it a a new constraint that is implied by
the former. We can't rely on type inference here; we need to provide
enough type information to the GADT, be it as an explicit signature:
>>>:{stricterPrintArgs :: forall m r. MonadIO m => Advice (Show `And` Eq `And` Ord) m r stricterPrintArgs = restrictArgs (\Dict -> Dict) (printArgs stdout "foo") :}
or with a type application to restrictArgs:
>>>stricterPrintArgs = restrictArgs @(Show `And` Eq `And` Ord) (\Dict -> Dict) (printArgs stdout "foo")
Arguments
| :: forall more less m r. (forall x. Dict more x -> Dict less x) | Evidence that one constraint implies the other. Every |
| -> Advice less m r | Advice with less restrictive constraint on the args. |
| -> Advice more m r | Advice with more restrictive constraint on the args. |
Makes the constraint on the arguments more restrictive.
Advising entire records
Arguments
| :: forall ca cr m advised. AdvisedRecord ca m cr advised | |
| => (forall r. cr r => NonEmpty (TypeRep, String) -> Advice ca m r) | The advice to apply. |
| -> advised (AspectT m) | The record to advise recursively. |
| -> advised (AspectT m) | The advised record. |
Gives Advice to all the functions in a record-of-functions.
The function that builds the advice receives a list of tuples (TypeRep, String)
which represent the record types and fields names we have
traversed until arriving at the advised function. This info can be useful for
logging advices. It's a list instead of a single tuple because
adviseRecord works recursively. The elements come innermost-first.
TYPE APPLICATION REQUIRED! The ca constraint on function arguments
and the cr constraint on the result type must be supplied by means of a
type application. Supply Top if no constraint is required.
"sop-core" re-exports
Some useful definitions re-exported the from "sop-core" package.
NP is an n-ary product used to represent the arguments of advised functions.
I is an identity functor. The arguments processed by an Advice come wrapped in it.
cfoldMap_NP is useful to construct homogeneous lists out of the NP product, for example:
>>>cfoldMap_NP (Proxy @Show) (\(I a) -> [show a]) (I False :* I (1::Int) :* Nil)["False","1"]
A constraint that can always be satisfied.
Since: sop-core-0.2
Instances
| Top (x :: k) | |
Defined in Data.SOP.Constraint | |
class (f x, g x) => And (f :: k -> Constraint) (g :: k -> Constraint) (x :: k) infixl 7 #
Pairing of constraints.
Since: sop-core-0.2
Instances
| (f x, g x) => And (f :: k -> Constraint) (g :: k -> Constraint) (x :: k) | |
Defined in Data.SOP.Constraint | |
class (AllF c xs, SListI xs) => All (c :: k -> Constraint) (xs :: [k]) #
Require a constraint for every element of a list.
If you have a datatype that is indexed over a type-level
list, then you can use All to indicate that all elements
of that type-level list must satisfy a given constraint.
Example: The constraint
All Eq '[ Int, Bool, Char ]
is equivalent to the constraint
(Eq Int, Eq Bool, Eq Char)
Example: A type signature such as
f :: All Eq xs => NP I xs -> ...
means that f can assume that all elements of the n-ary
product satisfy Eq.
Note on superclasses: ghc cannot deduce superclasses from All
constraints.
You might expect the following to compile
class (Eq a) => MyClass a foo :: (All Eq xs) => NP f xs -> z foo = [..] bar :: (All MyClass xs) => NP f xs -> x bar = foo
but it will fail with an error saying that it was unable to
deduce the class constraint AllF Eq xsbar.
In cases like this you can use Dict from Data.SOP.Dict
to prove conversions between constraints.
See this answer on SO for more details.
Minimal complete definition
Instances
| All (c :: k -> Constraint) ('[] :: [k]) | |
Defined in Data.SOP.Constraint Methods cpara_SList :: proxy c -> r '[] -> (forall (y :: k0) (ys :: [k0]). (c y, All c ys) => r ys -> r (y ': ys)) -> r '[] # | |
| (c x, All c xs) => All (c :: a -> Constraint) (x ': xs :: [a]) | |
Defined in Data.SOP.Constraint Methods cpara_SList :: proxy c -> r '[] -> (forall (y :: k) (ys :: [k]). (c y, All c ys) => r ys -> r (y ': ys)) -> r (x ': xs) # | |
data NP (a :: k -> Type) (b :: [k]) where #
An n-ary product.
The product is parameterized by a type constructor f and
indexed by a type-level list xs. The length of the list
determines the number of elements in the product, and if the
i-th element of the list is of type x, then the i-th
element of the product is of type f x.
The constructor names are chosen to resemble the names of the list constructors.
Two common instantiations of f are the identity functor I
and the constant functor K. For I, the product becomes a
heterogeneous list, where the type-level list describes the
types of its components. For K a
In the context of the SOP approach to generic programming, an n-ary product describes the structure of the arguments of a single data constructor.
Examples:
I 'x' :* I True :* Nil :: NP I '[ Char, Bool ] K 0 :* K 1 :* Nil :: NP (K Int) '[ Char, Bool ] Just 'x' :* Nothing :* Nil :: NP Maybe '[ Char, Bool ]
Constructors
| Nil :: forall k (a :: k -> Type). NP a ('[] :: [k]) | |
| (:*) :: forall k (a :: k -> Type) (x :: k) (xs :: [k]). a x -> NP a xs -> NP a (x ': xs) infixr 5 |
Instances
| HTrans (NP :: (k1 -> Type) -> [k1] -> Type) (NP :: (k2 -> Type) -> [k2] -> Type) | |
Defined in Data.SOP.NP Methods htrans :: forall c (xs :: l1) (ys :: l2) proxy f g. AllZipN (Prod NP) c xs ys => proxy c -> (forall (x :: k10) (y :: k20). c x y => f x -> g y) -> NP f xs -> NP g ys # hcoerce :: forall (f :: k10 -> Type) (g :: k20 -> Type) (xs :: l1) (ys :: l2). AllZipN (Prod NP) (LiftedCoercible f g) xs ys => NP f xs -> NP g ys # | |
| HPure (NP :: (k -> Type) -> [k] -> Type) | |
| HAp (NP :: (k -> Type) -> [k] -> Type) | |
| HCollapse (NP :: (k -> Type) -> [k] -> Type) | |
Defined in Data.SOP.NP | |
| HTraverse_ (NP :: (k -> Type) -> [k] -> Type) | |
Defined in Data.SOP.NP Methods hctraverse_ :: forall c (xs :: l) g proxy f. (AllN NP c xs, Applicative g) => proxy c -> (forall (a :: k0). c a => f a -> g ()) -> NP f xs -> g () # htraverse_ :: forall (xs :: l) g f. (SListIN NP xs, Applicative g) => (forall (a :: k0). f a -> g ()) -> NP f xs -> g () # | |
| HSequence (NP :: (k -> Type) -> [k] -> Type) | |
Defined in Data.SOP.NP Methods hsequence' :: forall (xs :: l) f (g :: k0 -> Type). (SListIN NP xs, Applicative f) => NP (f :.: g) xs -> f (NP g xs) # hctraverse' :: forall c (xs :: l) g proxy f f'. (AllN NP c xs, Applicative g) => proxy c -> (forall (a :: k0). c a => f a -> g (f' a)) -> NP f xs -> g (NP f' xs) # htraverse' :: forall (xs :: l) g f f'. (SListIN NP xs, Applicative g) => (forall (a :: k0). f a -> g (f' a)) -> NP f xs -> g (NP f' xs) # | |
| All (Compose Eq f) xs => Eq (NP f xs) | |
| (All (Compose Eq f) xs, All (Compose Ord f) xs) => Ord (NP f xs) | |
| All (Compose Show f) xs => Show (NP f xs) | |
| All (Compose Semigroup f) xs => Semigroup (NP f xs) | Since: sop-core-0.4.0.0 |
| (All (Compose Monoid f) xs, All (Compose Semigroup f) xs) => Monoid (NP f xs) | Since: sop-core-0.4.0.0 |
| All (Compose NFData f) xs => NFData (NP f xs) | Since: sop-core-0.2.5.0 |
Defined in Data.SOP.NP | |
| type AllZipN (NP :: (k -> Type) -> [k] -> Type) (c :: a -> b -> Constraint) | |
Defined in Data.SOP.NP | |
| type Same (NP :: (k1 -> Type) -> [k1] -> Type) | |
| type Prod (NP :: (k -> Type) -> [k] -> Type) | |
| type UnProd (NP :: (k -> Type) -> [k] -> Type) | |
| type SListIN (NP :: (k -> Type) -> [k] -> Type) | |
Defined in Data.SOP.NP | |
| type CollapseTo (NP :: (k -> Type) -> [k] -> Type) a | |
Defined in Data.SOP.NP | |
| type AllN (NP :: (k -> Type) -> [k] -> Type) (c :: k -> Constraint) | |
Defined in Data.SOP.NP | |
The identity type functor.
Like Identity, but with a shorter name.
Constructors
| I a |
Instances
| Monad I | |
| Functor I | |
| Applicative I | |
| Foldable I | |
Defined in Data.SOP.BasicFunctors Methods fold :: Monoid m => I m -> m # foldMap :: Monoid m => (a -> m) -> I a -> m # foldMap' :: Monoid m => (a -> m) -> I a -> m # foldr :: (a -> b -> b) -> b -> I a -> b # foldr' :: (a -> b -> b) -> b -> I a -> b # foldl :: (b -> a -> b) -> b -> I a -> b # foldl' :: (b -> a -> b) -> b -> I a -> b # foldr1 :: (a -> a -> a) -> I a -> a # foldl1 :: (a -> a -> a) -> I a -> a # elem :: Eq a => a -> I a -> Bool # maximum :: Ord a => I a -> a # | |
| Traversable I | |
| Eq1 I | Since: sop-core-0.2.4.0 |
| Ord1 I | Since: sop-core-0.2.4.0 |
Defined in Data.SOP.BasicFunctors | |
| Read1 I | Since: sop-core-0.2.4.0 |
Defined in Data.SOP.BasicFunctors | |
| Show1 I | Since: sop-core-0.2.4.0 |
| NFData1 I | Since: sop-core-0.2.5.0 |
Defined in Data.SOP.BasicFunctors | |
| Eq a => Eq (I a) | |
| Ord a => Ord (I a) | |
| Read a => Read (I a) | |
| Show a => Show (I a) | |
| Generic (I a) | |
| Semigroup a => Semigroup (I a) | Since: sop-core-0.4.0.0 |
| Monoid a => Monoid (I a) | Since: sop-core-0.4.0.0 |
| NFData a => NFData (I a) | Since: sop-core-0.2.5.0 |
Defined in Data.SOP.BasicFunctors | |
| type Rep (I a) | |
Defined in Data.SOP.BasicFunctors | |
cfoldMap_NP :: forall k c (xs :: [k]) m proxy f. (All c xs, Monoid m) => proxy c -> (forall (a :: k). c a => f a -> m) -> NP f xs -> m #
Specialization of hcfoldMap.
Since: sop-core-0.3.2.0
data Dict (c :: k -> Constraint) (a :: k) where #
An explicit dictionary carrying evidence of a class constraint.
The constraint parameter is separated into a
second argument so that Dict cNP.
Since: sop-core-0.2
Constructors
| Dict :: forall k (c :: k -> Constraint) (a :: k). c a => Dict c a |