com.jnape.palatable.lambda.monad.transformer

## Interface MonadT<M extends MonadRec<?,M>,A,MT extends MonadT<M,?,MT,T>,T extends MonadT<?,?,?,T>>

- Type Parameters:
    `M` - the argument `monad`
    `A` - the carrier type
    `MT` - the `Monad` witness
    `T` - the `MonadT` witness
  All Superinterfaces:
    Applicative<A,MT>, Functor<A,MT>, Monad<A,MT>, MonadBase<M,A,T>, MonadRec<A,MT>
  All Known Implementing Classes:
    EitherT, IdentityT, LazyT, MaybeT, ReaderT, SafeT, StateT, WriterT

      public interface MonadT<M extends MonadRec<?,M>,A,MT extends MonadT<M,?,MT,T>,T extends MonadT<?,?,?,T>>
      extends MonadBase<M,A,T>, Monad<A,MT>, MonadRec<A,MT>

  The generic type representing a `Monad` transformer, exposing the argument `Monad` as a type parameter.

  While any two `functors` and any two `applicatives` can be composed in general, the same is not true in general of any two `monads`. However, there exist `monads` that do compose, in general, with any other `Monad`. When this is the case, the combination of these `monads` with any other `Monad` can offer composed implementations of `pure` and `flatMap` for free, simply by relying on the other `monad's` implementation of both, as well as their own privileged knowledge about how to merge the nested `flatMap` call. This can be thought of as "gluing" together two `monads`, allowing easier access to their values, as well as, in some cases, providing universally correct constructions of the composed short-circuiting algorithms.

  The term "monad transformer" describes this particular encoding of monadic composition, and tends to be named in terms of `Monad` for which privileged knowledge must be known in order to eliminate during `flatmapping`.

  For more information, read more about monad transformers.

  See Also:
    `Monad`, `MonadBase`, `MaybeT`, `EitherT`, `ReaderT`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default <B> MonadT<M,B,MT,T>` | `discardL(Applicative<B,MT> appB)` Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`.
    `default <B> MonadT<M,A,MT,T>` | `discardR(Applicative<B,MT> appB)` Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`.
    `<B> MonadT<M,B,MT,T>` | `flatMap(Fn1<? super A,? extends Monad<B,MT>> f)` Chain dependent computations that may continue or short-circuit based on previous results.
    `default <B> MonadT<M,B,MT,T>` | `fmap(Fn1<? super A,? extends B> fn)` Covariantly transmute this functor's parameter using the given mapping function.
    `default <B> Lazy<? extends MonadT<M,B,MT,T>>` | `lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,MT>> 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>> MonadT<N,B,?,T>` | `lift(MonadRec<B,N> mb)` Lift a new argument `MonadRec` into this `MonadBase`.
    `<B> MonadT<M,B,MT,T>` | `pure(B b)` Lift the value `b` into this applicative functor.
    `default <B> MonadT<M,B,MT,T>` | `zip(Applicative<Fn1<? super A,? extends B>,MT> 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 interface com.jnape.palatable.lambda.monad.MonadRec

      `trampolineM`

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

      `join`

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

      `coerce`

- - ### Method Detail

    - #### lift

          <B,N extends MonadRec<?,N>> MonadT<N,B,?,T> lift(MonadRec<B,N> mb)

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

    - #### flatMap

          <B> MonadT<M,B,MT,T> flatMap(Fn1<? super A,? extends Monad<B,MT>> f)

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

    - #### pure

          <B> MonadT<M,B,MT,T> pure(B b)

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

    - #### fmap

          default <B> MonadT<M,B,MT,T> 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,MT extends MonadT<M,?,MT,T>>`
      Specified by:
        `fmap` in interface `Functor<A,MT extends MonadT<M,?,MT,T>>`
      Specified by:
        `fmap` in interface `Monad<A,MT extends MonadT<M,?,MT,T>>`
      Specified by:
        `fmap` in interface `MonadRec<A,MT extends MonadT<M,?,MT,T>>`
      Type Parameters:
        `B` - the new parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a functor over B (the new parameter type)

    - #### zip

          default <B> MonadT<M,B,MT,T> zip(Applicative<Fn1<? super A,? extends B>,MT> 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,MT extends MonadT<M,?,MT,T>>`
      Specified by:
        `zip` in interface `Monad<A,MT extends MonadT<M,?,MT,T>>`
      Specified by:
        `zip` in interface `MonadRec<A,MT extends MonadT<M,?,MT,T>>`
      Type Parameters:
        `B` - the resulting applicative parameter type
      Parameters:
        `appFn` - the other applicative instance
      Returns:
        the mapped applicative

    - #### lazyZip

          default <B> Lazy<? extends MonadT<M,B,MT,T>> lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,MT>> 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,MT extends MonadT<M,?,MT,T>>`
      Specified by:
        `lazyZip` in interface `Monad<A,MT extends MonadT<M,?,MT,T>>`
      Specified by:
        `lazyZip` in interface `MonadRec<A,MT extends MonadT<M,?,MT,T>>`
      Type Parameters:
        `B` - the resulting applicative parameter type
      Parameters:
        `lazyAppFn` - the lazy other applicative instance
      Returns:
        the mapped applicative
      See Also:
        `Maybe`, `Either`

    - #### discardL

          default <B> MonadT<M,B,MT,T> discardL(Applicative<B,MT> 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,MT extends MonadT<M,?,MT,T>>`
      Specified by:
        `discardL` in interface `Monad<A,MT extends MonadT<M,?,MT,T>>`
      Specified by:
        `discardL` in interface `MonadRec<A,MT extends MonadT<M,?,MT,T>>`
      Type Parameters:
        `B` - the type of the returned Applicative's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        appB

    - #### discardR

          default <B> MonadT<M,A,MT,T> discardR(Applicative<B,MT> 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,MT extends MonadT<M,?,MT,T>>`
      Specified by:
        `discardR` in interface `Monad<A,MT extends MonadT<M,?,MT,T>>`
      Specified by:
        `discardR` in interface `MonadRec<A,MT extends MonadT<M,?,MT,T>>`
      Type Parameters:
        `B` - the type of appB's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        this Applicative