com.jnape.palatable.lambda.functor.builtin

## Class Writer<W,A>

- java.lang.Object
- - com.jnape.palatable.lambda.functor.builtin.Writer<W,A>

- Type Parameters:
    `W` - the accumulation type
    `A` - the value type
  All Implemented Interfaces:
    Applicative<A,Writer<W,?>>, Functor<A,Writer<W,?>>, Monad<A,Writer<W,?>>, MonadRec<A,Writer<W,?>>, MonadWriter<W,A,Writer<W,?>>

      public final class Writer<W,A>
      extends Object
      implements MonadWriter<W,A,Writer<W,?>>, MonadRec<A,Writer<W,?>>

  The lazy writer monad, a monad capturing some accumulation (eventually to be folded in terms of a given monoid) and a value. Note that unlike the `State` monad, the `Writer` monad does not allow the value to be fully derived from the accumulation.

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Writer<W,A>` | `censor(Fn1<? super W,? extends W> fn)` Update the accumulated state.
    `<B> Writer<W,B>` | `discardL(Applicative<B,Writer<W,?>> appB)` Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`.
    `<B> Writer<W,A>` | `discardR(Applicative<B,Writer<W,?>> appB)` Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`.
    `<B> Writer<W,B>` | `flatMap(Fn1<? super A,? extends Monad<B,Writer<W,?>>> f)` Chain dependent computations that may continue or short-circuit based on previous results.
    `<B> Writer<W,B>` | `fmap(Fn1<? super A,? extends B> fn)` Covariantly transmute this functor's parameter using the given mapping function.
    `<B> Lazy<Writer<W,B>>` | `lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,Writer<W,?>>> 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.
    `static <W,A> Writer<W,A>` | `listen(A a)` Construct a `Writer` from a value.
    `<B> Writer<W,Tuple2<A,B>>` | `listens(Fn1<? super W,? extends B> fn)` Map the accumulation into a value and pair it with the current output.
    `<B> Writer<W,B>` | `pure(B b)` Lift the value `b` into this applicative functor.
    `static <W> Pure<Writer<W,?>>` | `pureWriter()` The canonical `Pure` instance for `Writer`.
    `Tuple2<A,W>` | `runWriter(Monoid<W> monoid)` Given a `Monoid` for the accumulation, run the computation represented by this `Writer`, accumulate the written output in terms of the `Monoid`, and produce the accumulation and the value.
    `static <W> Writer<W,Unit>` | `tell(W w)` Construct a `Writer` from an accumulation.
    `<B> Writer<W,B>` | `trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,Writer<W,?>>> fn)` Given some operation yielding a `RecursiveResult` inside this `MonadRec`, internally trampoline the operation until it yields a `termination` instruction.
    `static <W,A> Writer<W,A>` | `writer(Tuple2<A,W> aw)` Construct a `Writer` from an accumulation and a value.
    `<B> Writer<W,B>` | `zip(Applicative<Fn1<? super A,? extends B>,Writer<W,?>> 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

    - #### runWriter

          public Tuple2<A,W> runWriter(Monoid<W> monoid)

      Given a `Monoid` for the accumulation, run the computation represented by this `Writer`, accumulate the written output in terms of the `Monoid`, and produce the accumulation and the value.
      Parameters:
        `monoid` - the accumulation `Monoid`
      Returns:
        the accumulation with the value

    - #### listens

          public <B> Writer<W,Tuple2<A,B>> listens(Fn1<? super W,? extends B> fn)

      Map the accumulation into a value and pair it with the current output.
      Specified by:
        `listens` in interface `MonadWriter<W,A,Writer<W,?>>`
      Type Parameters:
        `B` - the mapped output
      Parameters:
        `fn` - the mapping function
      Returns:
        the updated `MonadWriter`

    - #### censor

          public Writer<W,A> censor(Fn1<? super W,? extends W> fn)

      Update the accumulated state.
      Specified by:
        `censor` in interface `MonadWriter<W,A,Writer<W,?>>`
      Parameters:
        `fn` - the update function
      Returns:
        the updated `MonadWriter`

    - #### trampolineM

          public <B> Writer<W,B> trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,Writer<W,?>>> 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,Writer<W,?>>`
      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`

    - #### flatMap

          public <B> Writer<W,B> flatMap(Fn1<? super A,? extends Monad<B,Writer<W,?>>> f)

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

    - #### pure

          public <B> Writer<W,B> pure(B b)

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

    - #### zip

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

    - #### lazyZip

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

    - #### discardR

          public <B> Writer<W,A> discardR(Applicative<B,Writer<W,?>> 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,Writer<W,?>>`
      Specified by:
        `discardR` in interface `Monad<A,Writer<W,?>>`
      Specified by:
        `discardR` in interface `MonadRec<A,Writer<W,?>>`
      Specified by:
        `discardR` in interface `MonadWriter<W,A,Writer<W,?>>`
      Type Parameters:
        `B` - the type of appB's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        this Applicative

    - #### tell

          public static <W> Writer<W,Unit> tell(W w)

      Construct a `Writer` from an accumulation.
      Type Parameters:
        `W` - the accumulation type
      Returns:
        the `Writer`

    - #### listen

          public static <W,A> Writer<W,A> listen(A a)

      Construct a `Writer` from a value.
      Type Parameters:
        `W` - the accumulation type
        `A` - the value type
      Returns:
        the `Writer`

    - #### writer

          public static <W,A> Writer<W,A> writer(Tuple2<A,W> aw)

      Construct a `Writer` from an accumulation and a value.
      Type Parameters:
        `W` - the accumulation type
        `A` - the value type
      Returns:
        the `WriterT`

    - #### pureWriter

          public static <W> Pure<Writer<W,?>> pureWriter()

      The canonical `Pure` instance for `Writer`.
      Type Parameters:
        `W` - the accumulation type
      Returns:
        the `Pure` instance