com.jnape.palatable.lambda.monad

## Interface MonadError<E,A,M extends MonadError<E,?,M>>

- Type Parameters:
    `E` - the error type
    `M` - the `Monad` witness
    `A` - the carrier
  All Superinterfaces:
    Applicative<A,M>, Functor<A,M>, Monad<A,M>
  All Known Implementing Classes:
    Either, IO, Maybe, Try

      public interface MonadError<E,A,M extends MonadError<E,?,M>>
      extends Monad<A,M>

  An interface for `monads` that can be interrupted with some type of error. The type of error is fully dictated by the instance of `MonadError` and is not necessarily analogous to Java `exceptions` or even `Throwable`. For instance, `IO` can be thrown any `Throwable`, where as `Either` can only be "thrown" a value of its `left` type.
  See Also:
    `IO`, `Either`, `Try`, `Maybe`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `MonadError<E,A,M>` | `catchError(Fn1<? super E,? extends Monad<A,M>> recoveryFn)` Catch any `thrown` errors inside the `Monad` and resume normal operations.
    `default <B> MonadError<E,B,M>` | `discardL(Applicative<B,M> appB)` Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`.
    `default <B> MonadError<E,A,M>` | `discardR(Applicative<B,M> appB)` Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`.
    `<B> MonadError<E,B,M>` | `flatMap(Fn1<? super A,? extends Monad<B,M>> f)` Chain dependent computations that may continue or short-circuit based on previous results.
    `default <B> MonadError<E,B,M>` | `fmap(Fn1<? super A,? extends B> fn)` Covariantly transmute this functor's parameter using the given mapping function.
    `default <B> Lazy<? extends MonadError<E,B,M>>` | `lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,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> MonadError<E,B,M>` | `pure(B b)` Lift the value `b` into this applicative functor.
    `MonadError<E,A,M>` | `throwError(E e)` Throw an error value of type `E` into the `monad`.
    `default <B> MonadError<E,B,M>` | `zip(Applicative<Fn1<? super A,? extends B>,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 interface com.jnape.palatable.lambda.monad.Monad

      `join`

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

      `coerce`

- - ### Method Detail

    - #### throwError

          MonadError<E,A,M> throwError(E e)

      Throw an error value of type `E` into the `monad`.
      Parameters:
        `e` - the error type
      Returns:
        the `monad`

    - #### catchError

          MonadError<E,A,M> catchError(Fn1<? super E,? extends Monad<A,M>> recoveryFn)

      Catch any `thrown` errors inside the `Monad` and resume normal operations.
      Parameters:
        `recoveryFn` - the catch function
      Returns:
        the recovered `Monad`

    - #### flatMap

          <B> MonadError<E,B,M> flatMap(Fn1<? super A,? extends Monad<B,M>> f)

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

    - #### pure

          <B> MonadError<E,B,M> pure(B b)

      Lift the value `b` into this applicative functor.
      Specified by:
        `pure` in interface `Applicative<A,M extends MonadError<E,?,M>>`
      Specified by:
        `pure` in interface `Monad<A,M extends MonadError<E,?,M>>`
      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> MonadError<E,B,M> 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,M extends MonadError<E,?,M>>`
      Specified by:
        `fmap` in interface `Functor<A,M extends MonadError<E,?,M>>`
      Specified by:
        `fmap` in interface `Monad<A,M extends MonadError<E,?,M>>`
      Type Parameters:
        `B` - the new parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a functor over B (the new parameter type)

    - #### zip

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

    - #### lazyZip

          default <B> Lazy<? extends MonadError<E,B,M>> lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,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,M extends MonadError<E,?,M>>`
      Specified by:
        `lazyZip` in interface `Monad<A,M extends MonadError<E,?,M>>`
      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> MonadError<E,B,M> discardL(Applicative<B,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,M extends MonadError<E,?,M>>`
      Specified by:
        `discardL` in interface `Monad<A,M extends MonadError<E,?,M>>`
      Type Parameters:
        `B` - the type of the returned Applicative's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        appB

    - #### discardR

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