defmodule Algae.Writer do
  @moduledoc ~S"""
  `Algae.Writer` helps capture the pattern of writing to a pure log or accumulated
  value, handling the bookkeeping for you.

  If `Algae.Reader` is quasi-read-only, `Algae.Writer` is quasi-write-only.
  This is often used for loggers, but could be anything as long as the hidden value
  is a `Witchcraft.Monoid`.

  There are many applications of `Writer`s, but as an illustrative point,
  one could use it for logging across processes and time, since the log
  is carried around with the result in a pure fashion. The monadic DSL
  helps make using these feel more natural.

  For an illustrated guide to `Writer`s,
  see [Thee Useful Monads](http://adit.io/posts/2013-06-10-three-useful-monads.html#the-state-monad).

  ## Anatomy

        %Algae.Writer{writer: {value, log}}
                                 ↑     ↑
       # "explicit" value position    "hidden" position,
       #                               commonly used as a log

  ## Examples

      iex> use Witchcraft
      ...>
      ...> excite =
      ...>   fn string ->
      ...>     monad writer({0.0, "log"}) do
      ...>       tell string
      ...>
      ...>       excited <- return "#{string}!"
      ...>       tell " => #{excited} ... "
      ...>
      ...>       return excited
      ...>     end
      ...>   end
      ...>
      ...> {_, logs} =
      ...>   "Hi"
      ...>   |> excite.()
      ...>   >>> excite
      ...>   >>> excite
      ...>   |> censor(&String.trim_trailing(&1, " ... "))
      ...>   |> run()
      ...>
      ...> logs
      "Hi => Hi! ... Hi! => Hi!! ... Hi!! => Hi!!!"

      iex> use Witchcraft
      ...>
      ...> exponent =
      ...>   fn num ->
      ...>     monad writer({0, 0}) do
      ...>       tell 1
      ...>       return num * num
      ...>     end
      ...>   end
      ...>
      ...> initial = 42
      ...> {result, times} = run(exponent.(initial) >>> exponent >>> exponent)
      ...>
      ...> "#{initial}^#{round(:math.pow(2, times))} = #{result}"
      "42^8 = 9682651996416"

  """

  alias __MODULE__
  alias Witchcraft.{Monoid, Unit}
  use   Witchcraft

  @type log    :: Monoid.t()
  @type value  :: any()
  @type writer :: {Writer.value(), Writer.log()}

  @type t :: %Writer{writer: writer()}

  defstruct writer: {0, []}

  @doc """
  Construct a `Algae.Writer` struct from a starting value and log.

  ## Examples

      iex> new()
      %Algae.Writer{writer: {0, []}}

      iex> new("hi")
      %Algae.Writer{writer: {"hi", []}}

      iex> new("ohai", 42)
      %Algae.Writer{writer: {"ohai", 42}}

  """
  @spec new(any(), Monoid.t()) :: Writer.t()
  def new(value \\ 0, log \\ []), do: %Writer{writer: {value, log}}

  @doc """
  Similar to `new/2`, but taking a tuple rather than separate fields.

  ## Examples

      iex> writer({"ohai", 42})
      %Algae.Writer{writer: {"ohai", 42}}

  """
  @spec writer(Writer.writer()) :: Writer.t()
  def writer({value, log}), do: new(value, log)

  @doc ~S"""
  Extract the enclosed value and log from an `Algae.Writer`.

  ## Examples

      iex> run(%Algae.Writer{writer: {"hi", "there"}})
      {"hi", "there"}

      iex> use Witchcraft
      ...>
      ...> half =
      ...>   fn num ->
      ...>     monad writer({0.0, ["log"]}) do
      ...>       let half = num / 2
      ...>       tell ["#{num} / 2 = #{half}"]
      ...>       return half
      ...>     end
      ...>   end
      ...>
      ...> run(half.(42) >>> half >>> half)
      {
        5.25,
        [
          "42 / 2 = 21.0",
          "21.0 / 2 = 10.5",
          "10.5 / 2 = 5.25"
        ]
      }

  """
  @spec run(Writer.t()) :: Writer.value()
  def run(%Writer{writer: writer}), do: writer

  @doc ~S"""
  Set the "log" portion of an `Algae.Writer` step

  ## Examples

      iex> tell("secrets")
      %Algae.Writer{writer: {%Witchcraft.Unit{}, "secrets"}}

      iex> use Witchcraft
      ...>
      ...> monad %Algae.Writer{writer: {"string", 1}} do
      ...>   tell 42
      ...>   tell 43
      ...>   return "hey"
      ...> end
      %Algae.Writer{writer: {"hey", 85}}

      iex> use Witchcraft
      ...>
      ...> half =
      ...>   fn num ->
      ...>     monad writer({0.0, ["log"]}) do
      ...>       let half = num / 2
      ...>       tell ["#{num} / 2 = #{half}"]
      ...>       return half
      ...>     end
      ...>   end
      ...>
      ...> run(half.(42.0) >>> half >>> half)
      {
        5.25,
        [
          "42.0 / 2 = 21.0",
          "21.0 / 2 = 10.5",
          "10.5 / 2 = 5.25"
        ]
      }

  """
  @spec tell(Writer.log()) :: Writer.t()
  def tell(log), do: new(%Unit{}, log)

  @doc """
  Copy the log into the value position. This makes it accessible in do-notation.

  ## Examples

      iex> listen(%Algae.Writer{writer: {42, "hi"}})
      %Algae.Writer{writer: {{42, "hi"}, "hi"}}

      iex> use Witchcraft
      ...>
      ...> monad new(1, 1) do
      ...>   wr <- listen tell(42)
      ...>   tell 43
      ...>   return wr
      ...> end
      %Algae.Writer{
        writer: {{%Witchcraft.Unit{}, 42}, 85}
      }

  """
  @spec listen(Writer.t()) :: Writer.t()
  def listen(%Writer{writer: {value, log}}), do: %Writer{writer: {{value, log}, log}}

  @doc """
  Similar to `listen/1`, but with the ability to adjust the copied log.

  ## Examples

      iex> listen(%Algae.Writer{writer: {1, "hi"}}, &String.upcase/1)
      %Algae.Writer{
        writer: {{1, "HI"}, "hi"}
      }

  """
  @spec listen(Writer.t(), (log() -> log())) :: Writer.t()
  def listen(writer, fun) do
    monad writer do
      {value, log} <- listen writer
      return {value, fun.(log)}
    end
  end

  @doc ~S"""
  Run a function in the value portion of an `Algae.Writer` on the log.

  Notice that the structure is similar to what somes out of `listen/{1,2}`

      Algae.Writer{writer: {{_, function}, log}}

  ## Examples

      iex> pass(%Algae.Writer{writer: {{1, fn x -> x * 10 end}, 42}})
      %Algae.Writer{writer: {1, 420}}

      iex> use Witchcraft
      ...>
      ...> monad new("string", ["logs"]) do
      ...>   a <-  ["start"] |> tell() |> listen()
      ...>   tell ["middle"]
      ...>
      ...>   {value, logs} <- return a
      ...>   pass writer({{value, fn [log | _] -> [log | [log | logs]] end}, logs})
      ...>
      ...>   tell ["next is 42"]
      ...>   return 42
      ...> end
      %Algae.Writer{
        writer: {42, ["start", "middle", "start", "start", "start", "next is 42"]}
      }

  """
  @spec pass(Writer.t()) :: Writer.t()
  def pass(%Writer{writer: {{value, fun}, log}}), do: %Writer{writer: {value, fun.(log)}}

  @doc ~S"""
  Run a writer, and run a function over the resulting log.

  ## Examples

      iex> 42
      ...> |> new(["hi", "THERE", "friend"])
      ...> |> censor(&Enum.reject(&1, fn log -> String.upcase(log) == log end))
      ...> |> run()
      {42, ["hi", "friend"]}

      iex> use Witchcraft
      ...>
      ...> 0
      ...> |> new(["logs"])
      ...> |> monad do
      ...>   tell ["Start"]
      ...>   tell ["BANG!"]
      ...>   tell ["shhhhhhh..."]
      ...>   tell ["LOUD NOISES!!!"]
      ...>   tell ["End"]
      ...>
      ...>   return 42
      ...> end
      ...> |> censor(&Enum.reject(&1, fn log -> String.upcase(log) == log end))
      ...> |> run()
      {42, ["Start", "shhhhhhh...", "End"]}

  """
  @spec censor(Writer.t(), (any() -> any())) :: Writer.t()
  def censor(writer, fun) do
    pass(monad writer do
      value <- writer
      return {value, fun}
    end)
  end
end