cats.mtl
package cats.mtl
Type members
Classlikes
@implicitNotFound("Could not find an implicit instance of Ask[${F}, ${E}]. If you have a\nvalue of type ${E} in scope, or a way of computing one, you may want to construct\na value of type Kleisli for this call-site, rather than type ${F}. An example type:\n\n Kleisli[${F}, ${E}, *]\n\nIf you do not have an ${E} or a way of getting one, you should add\nan implicit parameter of this type to your function. For example:\n\n (implicit fask: Ask[${F}, ${E}])\n")
Ask[F, E] lets you access an E value in the F[_] context.Intuitively, this means that an
E value is required as an input to get "out" of the F[_] context.Ask[F, E] has one external law:{{{
def askAddsNoEffects[A] (fa: F[A] ) = {
(ask *> fa) <-> fa
}
}}}
Ask[F, E] has one internal law:{{{
def readerIsAskAndMap[A] (f: E => A) = {
ask.map(f) <-> reader(f)
}
}}}
- Companion
- object
@implicitNotFound("Could not find an implicit instance of Censor[${F}, ${L}]. If you wish\nto capture side-channel output of type ${L} at this location, you may want\nto construct a value of type WriterT for this call-site, rather than ${F}.\nAn example type:\n\n WriterT[${F}, ${L}, *]\n\nOne use-case for this would be if ${L} represents an accumulation of values\nwhich are produced by this function *in addition to* its normal results.\nThis can be used to implement some forms of pure logging.\n\nIf you do not wish to capture a side-channel of type ${L} at this location,\nyou should add an implicit parameter of this type to your function. For\nexample:\n\n (implicit fcensor: Censor[${F}, ${L}])\n")
- Companion
- object
@implicitNotFound("Could not find an implicit instance of Chronicle[${F}, ${E}]. If you\nhave a good way of handling errors of type ${E} at this location, you may\nwant to construct a value of type IorT for this call-site, rather than \n${F}. An example type:\n\n IorT[${F}, ${E}, *]\n\nThis is analogous to writing try/catch around this call. The IorT will\n\"catch\" and accumulate the errors of type ${E}. Unlike try/catch, IorT\nmay produce errors alongside a valid result.\n\nIf you do not wish to handle errors of type ${E} at this location, you should\nadd an implicit parameter of this type to your function. For example:\n\n (implicit fchron: Chronicle[${F}, ${E}])\n")
- Companion
- object
@implicitNotFound("Could not find an implicit instance of Handle[${F}, ${E}]. If you\nhave a good way of handling errors of type ${E} at this location, you may want\nto construct a value of type EitherT for this call-site, rather than ${F}.\nAn example type:\n\n EitherT[${F}, ${E}, *]\n\nThis is analogous to writing try/catch around this call. The EitherT will\n\"catch\" the errors of type ${E}.\n\nIf you do not wish to handle errors of type ${E} at this location, you should\nadd an implicit parameter of this type to your function. For example:\n\n (implicit fhandle: Handle[${F}, ${E}}])\n")
- Companion
- object
@implicitNotFound("Could not find an implicit instance of Listen[${F}, ${L}]. If you wish\nto capture side-channel output of type ${L} at this location, you may want\nto construct a value of type WriterT for this call-site, rather than ${F}.\nAn example type:\n\n WriterT[${F}, ${L}, *]\n\nOne use-case for this would be if ${L} represents an accumulation of values\nwhich are produced by this function *in addition to* its normal results.\nThis can be used to implement some forms of pure logging.\n\nIf you do not wish to capture a side-channel of type ${L} at this location,\nyou should add an implicit parameter of this type to your function. For\nexample:\n\n (implicit flisten: Listen[${F}, ${L}])\n")
Listen[F, L] is a function F[A] => F[(A, L)] which exposes some statethat is contained in all
F[A] values, and can be modified using tell.Listen has two external laws:{{{
def listenRespectsTell(l: L) = {
listen(tell(l)) <-> tell(l).as(((), l))
}
def listenAddsNoEffects(fa: F[A]
) = {
listen(fa).map(_._1) <-> fa
}
}}}
listen(fa).map(_._1) <-> fa
}
}}}
Listen has one internal law:{{{
def listensIsListenThenMap(fa: F[A] , f: L => B) = {
listens(fa)(f) <-> listen(fa).map { case (a, l) => (a, f(l)) }
}
}}}
- Companion
- object
@implicitNotFound("Could not find an implicit instance of Local[${F}, ${E}]. If you have a\nvalue of type ${E} in scope, or a way of computing one, you may want to construct\na value of type Kleisli for this call-site, rather than type ${F}. An example type:\n\n Kleisli[${F}, ${E}, *]\n\nIf you do not have an ${E} or a way of getting one, you should add\nan implicit parameter of this type to your function. For example:\n\n (implicit flocal: Local[${F}, ${E}])\n")
Local[F, E] lets you alter the E value that is observed by an F[A] valueusing
ask; the modification can only be observed from within that F[A] value.Local[F, E] has three external laws:{{{
def askReflectsLocal(f: E => E) = {
local(f)(ask) <-> ask map f
}
def localPureIsPure[A]
(a: A, f: E => E) = {
local(f)(pure(a)) <-> pure(a)
}
local(f)(pure(a)) <-> pure(a)
}
def localDistributesOverAp[A, B]
(fa: F[A]
, ff: F[A => B]
, f: E => E) = {
local(f)(ff ap fa) <-> local(f)(ff) ap local(f)(fa)
}
}}}
local(f)(ff ap fa) <-> local(f)(ff) ap local(f)(fa)
}
}}}
Local has one internal law:{{{
def scopeIsLocalConst(fa: F[A] , e: E) = {
scope(e)(fa) <-> local(_ => e)(fa)
}
}}}
- Companion
- object
Encapsulates the notion of a monad, G, which contains all of
the effects of some other monad, F. This means that any effect
of type F[A] can be lifted to G[A] , such that both F and G
form monads and the lifting distributes over flatMap and pure.
the effects of some other monad, F. This means that any effect
of type F[A] can be lifted to G[A] , such that both F and G
form monads and the lifting distributes over flatMap and pure.
Original idea by Kris Nuttycombe.
- Companion
- object
@implicitNotFound("Could not find an implicit instance of Raise[${F}, ${E}]. If you have\na good way of handling errors of type ${E} at this location, you may want\nto construct a value of type EitherT for this call-site, rather than ${F}.\nAn example type:\n\n EitherT[${F}, ${E}, *]\n\nThis is analogous to writing try/catch around this call. The EitherT will\n\"catch\" the errors of type ${E}.\n\nIf you do not wish to handle errors of type ${E} at this location, you should\nadd an implicit parameter of this type to your function. For example:\n\n (implicit fraise: Raise[${F}, ${E}])\n")
Raise[F, E] expresses the ability to raise errors of type E in a functorial F[_] context.This means that a value of type
F[A] may contain no A values but instead an E error value,and further
map calls will not have any values to execute the passed function on.Raise has no external laws.Raise has two internal laws:{{{
def catchNonFatalDefault[A] (a: => A)(f: Throwable => E)(implicit A: Applicative[F] ) = {
catchNonFatal(a)(f) <-> try {
A.pure(a)
} catch {
case NonFatal(ex) => raise(f(ex))
}
}
def ensureDefault[A]
(fa: F[A]
)(error: => E)(predicate: A => Boolean)(implicit A: Monad[F]
) = {
ensure(fa)(error)(predicate) <-> for {
a <- fa
_ <- if (predicate(a)) pure(()) else raise(error)
} yield a
}
}}}
ensure(fa)(error)(predicate) <-> for {
a <- fa
_ <- if (predicate(a)) pure(()) else raise(error)
} yield a
}
}}}
Raise has one free law, i.e. a law guaranteed by parametricity:{{{
def failThenFlatMapFails[A, B] (ex: E, f: A => F[B] ) = {
fail(ex).flatMap(f) <-> fail(ex)
}
guaranteed by:
failX <-> failF[Y] // parametricity
failX.map(f) <-> failF[Y] // map must have no effect, because there's no X value
failX.map(f).join <-> fail[F[Y] ].join // add join to both sides
fail(ex).flatMap(f) <-> fail(ex) // join is equal, because there's no inner value to flatten effects from
// QED.
}}}
- Companion
- object
@implicitNotFound("Could not find an implicit instance of Stateful[${F}, ${S}]. If you wish\nto ensure that the statefulness of this function is confined within this\nscope, you may want to construct a value of type StateT for this call-site,\nrather than ${F}. An example type:\n\n StateT[${F}, ${S}, *]\n\nIf you wish the state of ${S} to be threaded *through* this location, rather\nthan being scoped entirely within it, you should add an implicit parameter\nof this type to your function. For example:\n\n (implicit fstate: Stateful[${F}, ${S}])\n")
Stateful[F, S] is the capability to access and modify a state valuefrom inside the
F[_] context, using set(s: S): F[Unit] and get: F[S].Stateful has four external laws:
{{{
def getThenSetDoesNothing = {
get >>= set <-> pure(())
}
def setThenGetReturnsSetted(s: S) = {
set(s) *> get <-> set(s) *> pure(s)
}
def setThenSetSetsLast(s1: S, s2: S) = {
set(s1) *> set(s2) <-> set(s2)
}
def getThenGetGetsOnce = {
get *> get <-> get
}
}}}
{{{
def getThenSetDoesNothing = {
get >>= set <-> pure(())
}
def setThenGetReturnsSetted(s: S) = {
set(s) *> get <-> set(s) *> pure(s)
}
def setThenSetSetsLast(s1: S, s2: S) = {
set(s1) *> set(s2) <-> set(s2)
}
def getThenGetGetsOnce = {
get *> get <-> get
}
}}}
Stateful has two internal law:{{{
def modifyIsGetThenSet(f: S => S) = {
modify(f) <-> (inspect(f) flatMap set)
}
def inspectLaw[A]
(f: S => A) = {
inspect(f) <-> (get map f)
}
}}}
inspect(f) <-> (get map f)
}
}}}
- Companion
- object
@implicitNotFound("Could not find an implicit instance of Tell[${F}, ${L}]. If you wish\nto capture side-channel output of type ${L} at this location, you may want\nto construct a value of type WriterT for this call-site, rather than ${F}.\nAn example type:\n\n WriterT[${F}, ${L}, *]\n\nOne use-case for this would be if ${L} represents an accumulation of values\nwhich are produced by this function *in addition to* its normal results.\nThis can be used to implement some forms of pure logging.\n\nIf you do not wish to capture a side-channel of type ${L} at this location,\nyou should add an implicit parameter of this type to your function. For\nexample:\n\n (implicit ftell: Tell[${F}, ${L}])\n")
Tell[F, L] is the ability to "log" values L inside a context F[_], as an effect.Tell has no external laws.Tell has one internal law:{{{
def writerIsTellAndMap(a: A, l: L) = {
(tell(l) as a) <-> writer(a, l)
}
def tupleIsWriterFlipped(a: A, l: L) = {
writer(a, l) <-> tuple((l, a))
}
}}}
writer(a, l) <-> tuple((l, a))
}
}}}
- Companion
- object