defmodule Logi.Channel do
  @moduledoc """
  Log Message Channels.

  A channel (logically) receives log messages from loggers and delivers the messages to installed sinks.

  ## Examples

  ```elixir
  # CREATE CHANNEL
  iex> :ok = Logi.Channel.create :sample_log
  iex> Logi.Channel.which_channels
  [:sample_log, :logi_default_log] # 'logi_default_log' is created automatically when 'logi' application was started

  # INSTALL SINK
  iex> write_fun = fn (_, format, data) -> :io.format("[my_sink] " <> format <> "\\n", data) end
  iex> sink = Logi.BuiltIn.Sink.Fun.new :sample_sink, write_fun
  iex> {:ok, _} = Logi.Channel.install_sink :sample_log, sink, :info  # Installs `sink` with `:info` level
  iex> Logi.Channel.which_sinks :sample_log
  [:sample_sink]

  # OUTPUT LOG MESSAGE
  iex> require Logi
  iex> Logi.debug "hello world", [], [logger: :sample_log]
  # The message is not emitted (the severity is too low).

  iex> Logi.info "hello world", [], [logger: :sample_log]
  #OUTPUT# [my_sink] hello world

  iex> Logi.alert "hello world", [], [logger: :sample_log]
  #OUTPUT# [my_sink] hello world

  iex> Logi.info "hello world"  # If `logger` option is omitted, the default channel will be used
  # The message is not emitted (no sinks are installed to the default channel).
  ```
  """

  @typedoc "The identifier of a channel"
  @type id :: atom


  @typedoc """
  Options for `install_sink_opt/3`.

  ## if_exists
  - The confliction handling policy.
  - If a sink with the same identifier already exists,
      - `:error`: the function returns an error `{:error, {:already_installed, existing_sink}}`.
      - `:ignore`: the new sink is ignored. Then the function returns `{:ok, existing_sink}`.
      - `:supersede`: the new sink supersedes it. Then the function returns `{:ok, old_sink}`.
  - Default: `:supersede`
  """
  @type install_sink_options :: [
    {:if_exists, :error | :ignore | :supersede}
  ]

  @typedoc "The information of an installed sink."
  @type installed_sink :: %{
    :sink => Logi.Sink.sink,
    :condition => Logi.Confliction.condition,
    :sink_sup => Logi.SinkProc.sink_sup,
    :writer => Logi.SinkWriter.writer | :undefined
  }

  @doc """
  The default channel.

  This channel is created automatically when `logi_ex` application was started.

  NOTE: The default channel ID is the same as the default logger ID (`Logi.default_logger/0`).
  """
  @spec default_channel :: id
  def default_channel do
    :logi_channel.default_channel
  end

  @doc """
  Creates a new channel.

  If the channel already exists, nothing happens.

  If there exists a process or a ETS table with the same name as `channel`, the function crashes.
  """
  @spec create(id) :: :ok
  def create(channel) do
    :logi_channel.create channel
  end

  @doc """
  Deletes a channel.

  If the channel does not exists, it is silently ignored.
  """
  @spec delete(id) :: :ok
  def delete(channel) do
    :logi_channel.delete channel
  end

  @doc "Returns a list of all existing channels."
  @spec which_channels :: [id]
  def which_channels do
    :logi_channel.which_channels
  end

  @doc "Equivalent to `Logi.Channel.install_sink Logi.Channel.default_channel, sink, condition`."
  @spec install_sink(Logi.Sink.sink, Logi.Condition.condition) :: {:ok, old} | {:error, reason} when
  old: :undefined | installed_sink,
  reason: {:cannot_start, any}
  def install_sink(sink, condition) do
    :logi_channel.install_sink sink, condition
  end

  @doc "Equivalent to `Logi.Channel.install_sink_opt channel, sink, condition, []`."
  @spec install_sink(id, Logi.Sink.sink, Logi.Condition.condition) :: {:ok, old} | {:error, reason} when
  old: :undefined | installed_sink,
  reason: {:cannot_start, any}
  def install_sink(channel, sink, condition) do
    :logi_channel.install_sink channel, sink, condition
  end

  @doc "Equivalent to `Logi.Channel.install_sink_opt Logi.Channel.default_channel, sink, condition, options`."
  @spec install_sink_opt(Logi.Sink.sink, Logi.Condition.condition, install_sink_options) :: {:ok, old} | {:error, reason} when
  old: :undefined | installed_sink,
  reason: {:cannot_start, any} | {:already_installed, installed_sink}
  def install_sink_opt(sink, condition, options) do
    :logi_channel.install_sink_opt sink, condition, options
  end

  @doc """
  Installs `sink`.

  If failed to start a sink process specified by `logi_sink:get_spec(sink)`,
  the function returns `{:cannot_start, failure_reason}`.

  If there does not exist a sink which has the same identifier with a new one,
  the function returns `{:ok, :undefined}`.

  Otherwise the result value depends on the value of the `:if_exists` option
  (see the description of `t:install_sink_options/0` for details).
  """
  @spec install_sink_opt(id, Logi.Sink.sink, Logi.Condition.condition, install_sink_options) :: {:ok, old} | {:error, reason} when
  old: :undefined | installed_sink,
  reason: {:cannot_start, any} | {:already_installed, installed_sink}
  def install_sink_opt(channel, sink, condition, options) do
    :logi_channel.install_sink_opt channel, sink, condition, options
  end

  @doc "Equivalent to `Logi.Channel.uninstall_sink Logi.Channel.default_channel, sink_id`."
  @spec uninstall_sink(Logi.Sink.id) :: {:ok, installed_sink} | :error
  def uninstall_sink(sink_id) do
    :logi_channel.uninstall_sink sink_id
  end

  @doc """
  Uninstalls the sink which has the identifier `sink_id` from `channel`.

  The function returns `{:ok, sink}` if the specified sink exists in the channel, `:error` otherwise.
  """
  @spec uninstall_sink(id, Logi.Sink.id) :: {:ok, installed_sink} | :error
  def uninstall_sink(channel, sink_id) do
    :logi_channel.uninstall_sink channel, sink_id
  end

  @doc "Equivalent to `Logi.Channel.set_sink_condition Logi.Channel.default_channel, sink_id, condition`."
  @spec set_sink_condition(Logi.Sink.id, Logi.Condition.condition) :: {:ok, old} | :error when
  old: Logi.Condition.condition
  def set_sink_condition(sink_id, condition) do
    :logi_channel.set_sink_condition sink_id, condition
  end

  @doc """
  Sets the applicable condition of the `sink_id`.

  The function returns `{:ok, old}` if the specified sink exists in the channel, `:error` otherwise.
  """
  @spec set_sink_condition(id, Logi.Sink.id, Logi.Condition.condition) :: {:ok, old} | :error when
  old: Logi.Condition.condition
  def set_sink_condition(channel, sink_id, condition) do
    :logi_channel.set_sink_condition channel, sink_id, condition
  end

  @doc "Equivalent to `Logi.Channel.find_sink Logi.Channel.id, sink_id`."
  @spec find_sink(Logi.Sink.id) :: {:ok, installed_sink} | :error
  def find_sink(sink_id) do
    :logi_channel.find_sink sink_id
  end

  @doc """
  Searches for `sink_id` in `channel`.

  The function returns `{:ok, sink}`, or `:error` if `sink_id` is not present.
  """
  @spec find_sink(id, Logi.Sink.id) :: {:ok, installed_sink} | :error
  def find_sink(channel_id, sink_id) do
    :logi_channel.find_sink channel_id, sink_id
  end

  @doc "Returns a list of installed sinks."
  @spec which_sinks(id) :: [Logi.Sink.id]
  def which_sinks(channel \\ Logi.Channel.default_channel) do
    :logi_channel.which_sinks channel
  end

  @doc "Equivalent to `Logi.Channel.whereis_sink_proc Logi.Channel.default_channel, path`."
  @spec whereis_sink_proc([Logi.Sink.id]) :: pid | :undefined
  def whereis_sink_proc(path) do
    :logi_channel.whereis_sink_proc path
  end

  @doc "Returns the pid associated with `path`."
  @spec whereis_sink_proc(id, [Logi.Sink.id]) :: pid | :undefined
  def whereis_sink_proc(channel, path) do
    :logi_channel.whereis_sink_proc channel, path
  end
end