com.jnape.palatable.lambda.monad.transformer.builtin

## Class ReaderT<R,M extends MonadRec<?,M>,A>

- java.lang.Object
- - com.jnape.palatable.lambda.monad.transformer.builtin.ReaderT<R,M,A>

- Type Parameters:
    `R` - the input type
    `M` - the returned `MonadRec`
    `A` - the embedded output type
  All Implemented Interfaces:
    Applicative<A,ReaderT<R,M,?>>, Cartesian<R,A,ReaderT<?,M,?>>, Contravariant<R,Profunctor<?,A,ReaderT<?,M,?>>>, Functor<A,ReaderT<R,M,?>>, Profunctor<R,A,ReaderT<?,M,?>>, Monad<A,ReaderT<R,M,?>>, MonadBase<M,A,ReaderT<R,?,?>>, MonadReader<R,A,ReaderT<R,M,?>>, MonadRec<A,ReaderT<R,M,?>>, MonadT<M,A,ReaderT<R,M,?>,ReaderT<R,?,?>>

      public final class ReaderT<R,M extends MonadRec<?,M>,A>
      extends Object
      implements MonadReader<R,A,ReaderT<R,M,?>>, Cartesian<R,A,ReaderT<?,M,?>>, MonadT<M,A,ReaderT<R,M,?>,ReaderT<R,?,?>>

  A `monad transformer` for any `function` from some type `R` to some `monadic` embedding ``MonadRec`<A, M>`.

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `ReaderT<R,M,Tuple2<R,A>>` | `carry()` Pair the covariantly-positioned carrier type with the contravariantly-positioned carrier type.
    `<C> ReaderT<Tuple2<C,R>,M,Tuple2<C,A>>` | `cartesian()` Pair some type `C` to this profunctor's carrier types.
    `<Q> ReaderT<Q,M,A>` | `contraMap(Fn1<? super Q,? extends R> fn)` Contravariantly map `A <- B`.
    `<Q,B> ReaderT<Q,M,B>` | `diMap(Fn1<? super Q,? extends R> lFn, Fn1<? super A,? extends B> rFn)` Dually map contravariantly over the left parameter and covariantly over the right parameter.
    `<Q> ReaderT<Q,M,A>` | `diMapL(Fn1<? super Q,? extends R> fn)` Contravariantly map over the left parameter.
    `<B> ReaderT<R,M,B>` | `diMapR(Fn1<? super A,? extends B> fn)` Covariantly map over the right parameter.
    `<B> ReaderT<R,M,B>` | `discardL(Applicative<B,ReaderT<R,M,?>> appB)` Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`.
    `<B> ReaderT<R,M,A>` | `discardR(Applicative<B,ReaderT<R,M,?>> appB)` Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`.
    `<B> ReaderT<R,M,B>` | `flatMap(Fn1<? super A,? extends Monad<B,ReaderT<R,M,?>>> f)` Chain dependent computations that may continue or short-circuit based on previous results.
    `<B> ReaderT<R,M,B>` | `fmap(Fn1<? super A,? extends B> fn)` Covariantly transmute this functor's parameter using the given mapping function.
    `<B> Lazy<ReaderT<R,M,B>>` | `lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,ReaderT<R,M,?>>> lazyAppFn)` Given a `lazy` instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.
    `<B,N extends MonadRec<?,N>> ReaderT<R,N,B>` | `lift(MonadRec<B,N> mb)` Lift a new argument `MonadRec` into this `MonadBase`.
    `static <R> Lift<ReaderT<R,?,?>>` | `liftReaderT()` `Lift` for `ReaderT`.
    `ReaderT<R,M,A>` | `local(Fn1<? super R,? extends R> fn)` Modify this `MonadReader's` environment after reading it but before running the effect.
    `<MA extends MonadRec<A,M>,N extends MonadRec<?,N>,B> ReaderT<R,N,B>` | `mapReaderT(Fn1<? super MA,? extends MonadRec<B,N>> fn)` Map the current `monadic` embedding to a new one in a potentially different `Monad`.
    `<B> ReaderT<R,M,B>` | `pure(B b)` Lift the value `b` into this applicative functor.
    `static <R,M extends MonadRec<?,M>> Pure<ReaderT<R,M,?>>` | `pureReaderT(Pure<M> pureM)` The canonical `Pure` instance for `ReaderT`.
    `static <R,M extends MonadRec<?,M>,A> ReaderT<R,M,A>` | `readerT(Fn1<? super R,? extends MonadRec<A,M>> fn)` Lift a `function` (`R -> `Monad`<A, M>`) into a `ReaderT` instance.
    `<MA extends MonadRec<A,M>> MA` | `runReaderT(R r)` Run the computation represented by this `ReaderT`.
    `<B> ReaderT<R,M,B>` | `trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,ReaderT<R,M,?>>> fn)` Given some operation yielding a `RecursiveResult` inside this `MonadRec`, internally trampoline the operation until it yields a `termination` instruction.
    `<B> ReaderT<R,M,B>` | `zip(Applicative<Fn1<? super A,? extends B>,ReaderT<R,M,?>> appFn)` Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface com.jnape.palatable.lambda.monad.Monad

      `join`

    - ### Methods inherited from interface com.jnape.palatable.lambda.functor.Functor

      `coerce`

- - ### Method Detail

    - #### runReaderT

          public <MA extends MonadRec<A,M>> MA runReaderT(R r)

      Run the computation represented by this `ReaderT`.
      Type Parameters:
        `MA` - the witnessed target type
      Parameters:
        `r` - the input
      Returns:
        the embedded `MonadRec`

    - #### mapReaderT

          public <MA extends MonadRec<A,M>,N extends MonadRec<?,N>,B> ReaderT<R,N,B> mapReaderT(Fn1<? super MA,? extends MonadRec<B,N>> fn)

      Map the current `monadic` embedding to a new one in a potentially different `Monad`.
      Type Parameters:
        `MA` - the currently embedded `Monad`
        `N` - the new `Monad` witness
        `B` - the new carrier type
      Parameters:
        `fn` - the function
      Returns:
        the mapped `ReaderT`

    - #### local

          public ReaderT<R,M,A> local(Fn1<? super R,? extends R> fn)

      Modify this `MonadReader's` environment after reading it but before running the effect.
      Specified by:
        `local` in interface `MonadReader<R,A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Parameters:
        `fn` - the modification function
      Returns:
        the `MonadReader` with a modified environment

    - #### lift

          public <B,N extends MonadRec<?,N>> ReaderT<R,N,B> lift(MonadRec<B,N> mb)

      Lift a new argument `MonadRec` into this `MonadBase`.
      Specified by:
        `lift` in interface `MonadBase<M extends MonadRec<?,M>,A,ReaderT<R,?,?>>`
      Specified by:
        `lift` in interface `MonadT<M extends MonadRec<?,M>,A,ReaderT<R,M extends MonadRec<?,M>,?>,ReaderT<R,?,?>>`
      Type Parameters:
        `B` - the `MonadRec` carrier type
        `N` - the argument `MonadRec` witness
      Parameters:
        `mb` - the argument `MonadRec`
      Returns:
        the new `MonadBase`

    - #### flatMap

          public <B> ReaderT<R,M,B> flatMap(Fn1<? super A,? extends Monad<B,ReaderT<R,M,?>>> f)

      Chain dependent computations that may continue or short-circuit based on previous results.
      Specified by:
        `flatMap` in interface `Monad<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `flatMap` in interface `MonadReader<R,A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `flatMap` in interface `MonadRec<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `flatMap` in interface `MonadT<M extends MonadRec<?,M>,A,ReaderT<R,M extends MonadRec<?,M>,?>,ReaderT<R,?,?>>`
      Type Parameters:
        `B` - the resulting monad parameter type
      Parameters:
        `f` - the dependent computation over A
      Returns:
        the new monad instance

    - #### trampolineM

          public <B> ReaderT<R,M,B> trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,ReaderT<R,M,?>>> fn)

      Given some operation yielding a `RecursiveResult` inside this `MonadRec`, internally trampoline the operation until it yields a `termination` instruction.

      Stack-safety depends on implementations guaranteeing that the growth of the call stack is a constant factor independent of the number of invocations of the operation. For various examples of how this can be achieved in stereotypical circumstances, see the referenced types.

      Specified by:
        `trampolineM` in interface `MonadRec<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Type Parameters:
        `B` - the ultimate resulting carrier type
      Parameters:
        `fn` - the function to internally trampoline
      Returns:
        the trampolined `MonadRec`
      See Also:
        `for a basic implementation`, `for a {@link CoProduct2 coproduct} implementation`, `for an implementation leveraging an already stack-safe {@link Monad#flatMap(Fn1)}`, `for a {@link MonadT monad transformer} implementation`

    - #### pure

          public <B> ReaderT<R,M,B> pure(B b)

      Lift the value `b` into this applicative functor.
      Specified by:
        `pure` in interface `Applicative<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `pure` in interface `Monad<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `pure` in interface `MonadReader<R,A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `pure` in interface `MonadRec<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `pure` in interface `MonadT<M extends MonadRec<?,M>,A,ReaderT<R,M extends MonadRec<?,M>,?>,ReaderT<R,?,?>>`
      Type Parameters:
        `B` - the type of the returned applicative's parameter
      Parameters:
        `b` - the value
      Returns:
        an instance of this applicative over b

    - #### fmap

          public <B> ReaderT<R,M,B> fmap(Fn1<? super A,? extends B> fn)

      Covariantly transmute this functor's parameter using the given mapping function. Generally this method is specialized to return an instance of the class implementing Functor.
      Specified by:
        `fmap` in interface `Applicative<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `fmap` in interface `Functor<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `fmap` in interface `Monad<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `fmap` in interface `MonadReader<R,A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `fmap` in interface `MonadRec<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `fmap` in interface `MonadT<M extends MonadRec<?,M>,A,ReaderT<R,M extends MonadRec<?,M>,?>,ReaderT<R,?,?>>`
      Type Parameters:
        `B` - the new parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a functor over B (the new parameter type)

    - #### zip

          public <B> ReaderT<R,M,B> zip(Applicative<Fn1<? super A,? extends B>,ReaderT<R,M,?>> appFn)

      Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.
      Specified by:
        `zip` in interface `Applicative<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `zip` in interface `Monad<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `zip` in interface `MonadReader<R,A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `zip` in interface `MonadRec<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `zip` in interface `MonadT<M extends MonadRec<?,M>,A,ReaderT<R,M extends MonadRec<?,M>,?>,ReaderT<R,?,?>>`
      Type Parameters:
        `B` - the resulting applicative parameter type
      Parameters:
        `appFn` - the other applicative instance
      Returns:
        the mapped applicative

    - #### lazyZip

          public <B> Lazy<ReaderT<R,M,B>> lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,ReaderT<R,M,?>>> lazyAppFn)

      Given a `lazy` instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports. This is useful for applicatives that support lazy evaluation and early termination.
      Specified by:
        `lazyZip` in interface `Applicative<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `lazyZip` in interface `Monad<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `lazyZip` in interface `MonadReader<R,A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `lazyZip` in interface `MonadRec<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `lazyZip` in interface `MonadT<M extends MonadRec<?,M>,A,ReaderT<R,M extends MonadRec<?,M>,?>,ReaderT<R,?,?>>`
      Type Parameters:
        `B` - the resulting applicative parameter type
      Parameters:
        `lazyAppFn` - the lazy other applicative instance
      Returns:
        the mapped applicative
      See Also:
        `Maybe`, `Either`

    - #### discardL

          public <B> ReaderT<R,M,B> discardL(Applicative<B,ReaderT<R,M,?>> appB)

      Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`. This is generally useful for sequentially performing side-effects.
      Specified by:
        `discardL` in interface `Applicative<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `discardL` in interface `Monad<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `discardL` in interface `MonadReader<R,A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `discardL` in interface `MonadRec<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `discardL` in interface `MonadT<M extends MonadRec<?,M>,A,ReaderT<R,M extends MonadRec<?,M>,?>,ReaderT<R,?,?>>`
      Type Parameters:
        `B` - the type of the returned Applicative's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        appB

    - #### discardR

          public <B> ReaderT<R,M,A> discardR(Applicative<B,ReaderT<R,M,?>> appB)

      Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`. This is generally useful for sequentially performing side-effects.
      Specified by:
        `discardR` in interface `Applicative<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `discardR` in interface `Monad<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `discardR` in interface `MonadReader<R,A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `discardR` in interface `MonadRec<A,ReaderT<R,M extends MonadRec<?,M>,?>>`
      Specified by:
        `discardR` in interface `MonadT<M extends MonadRec<?,M>,A,ReaderT<R,M extends MonadRec<?,M>,?>,ReaderT<R,?,?>>`
      Type Parameters:
        `B` - the type of appB's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        this Applicative

    - #### diMap

          public <Q,B> ReaderT<Q,M,B> diMap(Fn1<? super Q,? extends R> lFn,
                                            Fn1<? super A,? extends B> rFn)

      Dually map contravariantly over the left parameter and covariantly over the right parameter. This is isomorphic to `diMapL(lFn).diMapR(rFn)`.
      Specified by:
        `diMap` in interface `Cartesian<R,A,ReaderT<?,M extends MonadRec<?,M>,?>>`
      Specified by:
        `diMap` in interface `Profunctor<R,A,ReaderT<?,M extends MonadRec<?,M>,?>>`
      Type Parameters:
        `Q` - the new left parameter type
        `B` - the new right parameter type
      Parameters:
        `lFn` - the left parameter mapping function
        `rFn` - the right parameter mapping function
      Returns:
        a profunctor over Z (the new left parameter type) and C (the new right parameter type)

    - #### diMapL

          public <Q> ReaderT<Q,M,A> diMapL(Fn1<? super Q,? extends R> fn)

      Contravariantly map over the left parameter.
      Specified by:
        `diMapL` in interface `Cartesian<R,A,ReaderT<?,M extends MonadRec<?,M>,?>>`
      Specified by:
        `diMapL` in interface `Profunctor<R,A,ReaderT<?,M extends MonadRec<?,M>,?>>`
      Type Parameters:
        `Q` - the new left parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a profunctor over Z (the new left parameter type) and C (the same right parameter type)

    - #### diMapR

          public <B> ReaderT<R,M,B> diMapR(Fn1<? super A,? extends B> fn)

      Covariantly map over the right parameter. For all profunctors that are also functors, it should hold that `diMapR(f) == fmap(f)`.
      Specified by:
        `diMapR` in interface `Cartesian<R,A,ReaderT<?,M extends MonadRec<?,M>,?>>`
      Specified by:
        `diMapR` in interface `Profunctor<R,A,ReaderT<?,M extends MonadRec<?,M>,?>>`
      Type Parameters:
        `B` - the new right parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a profunctor over A (the same left parameter type) and C (the new right parameter type)

    - #### contraMap

          public <Q> ReaderT<Q,M,A> contraMap(Fn1<? super Q,? extends R> fn)

      Contravariantly map `A <- B`.
      Specified by:
        `contraMap` in interface `Cartesian<R,A,ReaderT<?,M extends MonadRec<?,M>,?>>`
      Specified by:
        `contraMap` in interface `Contravariant<R,Profunctor<?,A,ReaderT<?,M extends MonadRec<?,M>,?>>>`
      Specified by:
        `contraMap` in interface `Profunctor<R,A,ReaderT<?,M extends MonadRec<?,M>,?>>`
      Type Parameters:
        `Q` - the new parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        the mapped Contravariant functor instance

    - #### cartesian

          public <C> ReaderT<Tuple2<C,R>,M,Tuple2<C,A>> cartesian()

      Pair some type `C` to this profunctor's carrier types.
      Specified by:
        `cartesian` in interface `Cartesian<R,A,ReaderT<?,M extends MonadRec<?,M>,?>>`
      Type Parameters:
        `C` - the paired type
      Returns:
        the cartesian-strengthened profunctor

    - #### carry

          public ReaderT<R,M,Tuple2<R,A>> carry()

      Pair the covariantly-positioned carrier type with the contravariantly-positioned carrier type. This can be thought of as "carrying" or "inspecting" the left parameter.
      Specified by:
        `carry` in interface `Cartesian<R,A,ReaderT<?,M extends MonadRec<?,M>,?>>`
      Returns:
        the profunctor with the first parameter carried

    - #### readerT

          public static <R,M extends MonadRec<?,M>,A> ReaderT<R,M,A> readerT(Fn1<? super R,? extends MonadRec<A,M>> fn)

      Lift a `function` (`R -> `Monad`<A, M>`) into a `ReaderT` instance.
      Type Parameters:
        `R` - the input type
        `M` - the returned `Monad`
        `A` - the embedded output type
      Parameters:
        `fn` - the function
      Returns:
        the `ReaderT`

    - #### pureReaderT

          public static <R,M extends MonadRec<?,M>> Pure<ReaderT<R,M,?>> pureReaderT(Pure<M> pureM)

      The canonical `Pure` instance for `ReaderT`.
      Type Parameters:
        `R` - the input type
        `M` - the argument `Monad` witness
      Parameters:
        `pureM` - the argument `Monad` `Pure`
      Returns:
        the `Pure` instance

    - #### liftReaderT

          public static <R> Lift<ReaderT<R,?,?>> liftReaderT()

      `Lift` for `ReaderT`.
      Type Parameters:
        `R` - the environment type
      Returns:
        the `Monad` lifted into `ReaderT`