defmodule Serum.Plugin do
  @moduledoc """
  A behaviour that all Serum plugin module must implement.

  This module allows experienced Serum users and developers to make their own
  Serum plugins which can extend the functionality of Serum.

  A Serum plugin can...

  - Alter contents of input or output files,
  - Execute arbitrary codes during some stages of site building,
  - And optionally provide extra Mix tasks that extends Serum.

  ## For Plugin Developers

  In order for a Serum plugin to work, you must implement at least these
  four callbacks:

  - `name/0`
  - `version/0`
  - `elixir/0`
  - `serum/0`
  - `description/0`
  - `implements/0`

  Also there are a number of other callbacks you can optionally implement.
  Read the rest of the documentation for this module to see which callbacks
  you can implement and what each callback should do.

  ## For Plugin Users

  To enable Serum plugins, add a `plugins` key to your `serum.exs`(if it does
  not exist), and put names of Serum plugin modules there.

      %{
        plugins: [
          Awesome.Serum.Plugin,
          Great.Serum.Plugin
        ]
      }

  You can also restrict some plugins to run only in specific Mix environments.
  For example, if plugins are configured like the code below, only
  `Awesome.Serum.Plugin` plugin will be loaded when `MIX_ENV` is set to `prod`.

      %{
        plugins: [
          Awesome.Serum.Plugin,
          {Great.Serum.Plugin, only: :dev},
          {Another.Serum.Plugin, only: [:dev, :test]}
        ]
      }

  The order of plugins is important, as Serum will call plugins one by one,
  from the first item to the last one. Therefore these two configurations below
  may produce different results.

  Configuration 1:

      %{
        plugins: [
          Awesome.Serum.Plugin,
          Another.Serum.Plugin
        ]
      }

  Configuration 2:

      %{
        plugins: [
          Another.Serum.Plugin,
          Awesome.Serum.Plugin
        ]
      }
  """

  use Agent
  require Serum.Plugin.Macros
  import Serum.IOProxy, only: [put_msg: 2]
  import Serum.Plugin.Macros
  alias Serum.File
  alias Serum.Fragment
  alias Serum.Page
  alias Serum.Plugin.Loader
  alias Serum.Post
  alias Serum.PostList
  alias Serum.Result
  alias Serum.Template

  defstruct [:module, :name, :version, :description, :implements, :args]

  @type t :: %__MODULE__{
          module: atom(),
          name: binary(),
          version: binary(),
          description: binary(),
          implements: [atom()],
          args: term()
        }

  @type spec :: atom() | {atom(), plugin_options()}
  @type plugin_options :: [only: atom() | [atom()], args: term()]

  @old_callback_arities [
    build_started: 2,
    reading_pages: 1,
    reading_posts: 1,
    reading_templates: 1,
    processing_page: 1,
    processing_post: 1,
    processing_template: 1,
    processed_page: 1,
    processed_post: 1,
    processed_template: 1,
    processed_list: 1,
    processed_pages: 1,
    processed_posts: 1,
    rendering_fragment: 2,
    rendered_fragment: 1,
    rendered_page: 1,
    wrote_file: 1,
    build_succeeded: 2,
    build_failed: 3,
    finalizing: 2
  ]

  @optional_callbacks @old_callback_arities
                      |> Enum.map(fn {name, arity} ->
                        [{name, arity}, {name, arity + 1}]
                      end)
                      |> List.flatten()

  @required_msg "You must implement this callback, or the plugin may fail."

  #
  # Required Callbacks
  #

  @doc """
  Returns the name of the plugin.

  #{@required_msg}
  """
  @callback name() :: binary()

  @doc """
  Returns the version of the plugin.

  The returned version string must follow the semantic versioning scheme.

  #{@required_msg}
  """
  @callback version() :: binary()

  @doc """
  Returns the version requirement of Elixir.

  Refer to [this document](https://hexdocs.pm/elixir/Version.html#module-requirements)
  for the string format.

  #{@required_msg}
  """
  @callback elixir() :: binary()

  @doc """
  Returns the version requirement of Serum.

  Refer to [this document](https://hexdocs.pm/elixir/Version.html#module-requirements)
  for the string format.

  #{@required_msg}
  """
  @callback serum() :: binary()

  @doc """
  Returns the short description of the plugin.

  #{@required_msg}
  """
  @callback description() :: binary()

  @doc """
  Returns a list of optional callbacks which the plugin implements.

  Each list item can be in one of two forms:

  - `{callback_name, arity}`
  - `callback_name` - This is deprecated and left for compatibility. New Serum
    plugins must use the above format.

  For example, if your plugin implements `build_started/2` and `finalizing/2`,
  you must implement this callback so that it returns `[build_started: 2,
  finalizing: 2]`.

  #{@required_msg}
  """
  @callback implements() :: [atom() | {atom(), integer()}]

  #
  # Optional Callbacks
  #

  @doc """
  Called right after the build process has started. Some necessary OTP
  applications or processes should be started here.
  """
  defcallback build_started(src :: binary(), dest :: binary()) :: Result.t()

  @doc """
  Called before reading input files.

  Plugins can manipulate the list of files to be read and pass it to
  the next plugin.
  """
  defcallback reading_pages(files :: [binary()]) :: Result.t([binary()])

  @doc """
  Called before reading input files.

  Plugins can manipulate the list of files to be read and pass it to
  the next plugin.
  """
  defcallback reading_posts(files :: [binary()]) :: Result.t([binary()])

  @doc """
  Called before reading input files.

  Plugins can manipulate the list of files to be read and pass it to
  the next plugin.
  """
  defcallback reading_templates(files :: [binary()]) :: Result.t([binary()])

  @doc """
  Called before Serum processes each input file.

  Plugins can alter the raw contents of input files here.
  """
  defcallback processing_page(file :: File.t()) :: Result.t(File.t())

  @doc """
  Called before Serum processes each input file.

  Plugins can alter the raw contents of input files here.
  """
  defcallback processing_post(file :: File.t()) :: Result.t(File.t())

  @doc """
  Called before Serum processes each input file.

  Plugins can alter the raw contents of input files here.
  """
  defcallback processing_template(file :: File.t()) :: Result.t(File.t())

  @doc """
  Called after Serum has processed each input file and produced
  the resulting struct.

  Plugins can alter the processed contents and metadata here.
  """
  defcallback processed_page(page :: Page.t()) :: Result.t(Page.t())

  @doc """
  Called after Serum has processed each input file and produced
  the resulting struct.

  Plugins can alter the processed contents and metadata here.
  """
  defcallback processed_post(post :: Post.t()) :: Result.t(Post.t())

  @doc """
  Called after Serum has processed each input file and produced
  the resulting struct.

  Plugins can alter the AST and its metadata here.
  """
  defcallback processed_template(template :: Template.t()) :: Result.t(Template.t())

  @doc """
  Called after Serum has processed each input file and produced
  the resulting struct.

  Plugins can alter the processed contents and metadata here.
  """
  defcallback processed_list(list :: PostList.t()) :: Result.t(PostList.t())

  @doc "Called after Serum has successfully processed all pages."
  defcallback processed_pages(pages :: [Page.t()]) :: Result.t([Page.t()])

  @doc "Called after Serum has successfully processed all blog posts."
  defcallback processed_posts(posts :: [Post.t()]) :: Result.t([Post.t()])

  @doc """
  Called while each fragment is being constructed.

  Plugins can alter the HTML tree of its contents (which is generated by
  Floki). It is recommended to implement this callback if you want to modify
  the HTML document without worrying about breaking it.
  """
  defcallback rendering_fragment(html :: Floki.html_tree(), metadata :: map()) ::
                Result.t(Floki.html_tree())

  @doc """
  Called after producing a HTML fragment for each page.

  Plugins can modify the contents and metadata of each fragment here.
  """
  defcallback rendered_fragment(frag :: Fragment.t()) :: Result.t(Fragment.t())

  @doc """
  Called when Serum has rendered a full page and it's about to write to an
  output file.

  Plugins can alter the raw contents of the page to be written.
  """
  defcallback rendered_page(file :: File.t()) :: Result.t(File.t())

  @doc """
  Called after writing each output to a file.
  """
  defcallback wrote_file(file :: File.t()) :: Result.t()

  @doc """
  Called if the whole build process has finished successfully.
  """
  defcallback build_succeeded(src :: binary(), dest :: binary()) :: Result.t()

  @doc """
  Called if the build process has failed for some reason.
  """
  defcallback build_failed(
                src :: binary(),
                dest :: binary(),
                result :: Result.t() | Result.t(term)
              ) ::
                Result.t()

  @doc """
  Called right before Serum exits, whether the build has succeeded or not.

  This is the place where you should clean up any temporary resources created
  in `build_started/2` callback.
  """
  defcallback finalizing(src :: binary(), dest :: binary()) :: Result.t()

  #
  # Plugin Consumer Functions
  #

  @doc false
  @spec start_link(any()) :: {:error, any()} | {:ok, pid()}
  def start_link(_) do
    Agent.start_link(fn -> %{} end, name: __MODULE__)
  end

  @doc false
  @spec load_plugins([spec()]) :: Result.t([t()])
  def load_plugins(plugin_specs), do: Loader.load_plugins(plugin_specs)

  @doc false
  @spec show_info([t()]) :: :ok
  def show_info(plugins)
  def show_info([]), do: :ok

  def show_info(plugins) do
    Enum.each(plugins, fn p ->
      msg = [
        :bright,
        p.name,
        " v",
        to_string(p.version),
        :reset,
        " (#{module_name(p.module)})\n",
        :light_black,
        p.description
      ]

      put_msg(:plugin, msg)
    end)
  end

  action build_started(src :: binary(), dest :: binary()) :: Result.t()
  function reading_pages(files :: [binary()]) :: Result.t([binary()])
  function reading_posts(files :: [binary()]) :: Result.t([binary()])
  function reading_templates(files :: [binary()]) :: Result.t([binary()])
  function processing_page(file :: File.t()) :: Result.t(File.t())
  function processing_post(file :: File.t()) :: Result.t(File.t())
  function processing_template(file :: File.t()) :: Result.t(File.t())
  function processed_page(page :: Page.t()) :: Result.t(Page.t())
  function processed_post(post :: Post.t()) :: Result.t(Post.t())
  function processed_template(template :: Template.t()) :: Result.t(Template.t())
  function processed_list(list :: PostList.t()) :: Result.t(PostList.t())
  function processed_pages(pages :: [Page.t()]) :: Result.t([Page.t()])
  function processed_posts(posts :: [Post.t()]) :: Result.t([Post.t()])

  function rendering_fragment(html :: Floki.html_tree(), metadata :: map()) ::
             Result.t(Floki.html_tree())

  function rendered_fragment(frag :: Fragment.t()) :: Result.t(Fragment.t())
  function rendered_page(file :: File.t()) :: Result.t(File.t())
  action wrote_file(file :: File.t()) :: Result.t()
  action build_succeeded(src :: binary(), dest :: binary()) :: Result.t()

  action build_failed(src :: binary(), dest :: binary(), result :: Result.t() | Result.t(term)) ::
           Result.t()

  action finalizing(src :: binary(), dest :: binary()) :: Result.t()

  @spec call_action(atom(), [term()]) :: Result.t()
  defp call_action(fun, args) do
    __MODULE__
    |> Agent.get(&(&1[fun] || []))
    |> do_call_action(fun, args)
  end

  @spec do_call_action([{integer(), t()}], atom(), [term()]) :: Result.t()
  defp do_call_action(arity_and_plugins, fun, args)
  defp do_call_action([], _fun, _args), do: :ok

  defp do_call_action([{arity, plugin} | arity_and_plugins], fun, args) do
    new_args = update_callback_args(args, plugin, fun, arity)

    case apply(plugin.module, fun, new_args) do
      :ok ->
        do_call_action(arity_and_plugins, fun, args)

      {:error, _} = error ->
        error

      term ->
        message =
          "#{module_name(plugin.module)}.#{fun} returned " <>
            "an unexpected value: #{inspect(term)}"

        {:error, message}
    end
  rescue
    exception -> handle_exception(exception, plugin.module, fun)
  end

  @spec call_function(atom(), [term()]) :: Result.t(term())
  defp call_function(fun, [arg | args]) do
    __MODULE__
    |> Agent.get(&(&1[fun] || []))
    |> do_call_function(fun, args, arg)
  end

  @spec do_call_function([{integer, t()}], atom(), [term()], term()) :: Result.t(term())
  defp do_call_function(arity_and_plugins, fun, args, acc)
  defp do_call_function([], _fun, _args, acc), do: {:ok, acc}

  defp do_call_function([{arity, plugin} | arity_and_plugins], fun, args, acc) do
    new_args = update_callback_args(args, plugin, fun, arity)

    case apply(plugin.module, fun, [acc | new_args]) do
      {:ok, new_acc} ->
        do_call_function(arity_and_plugins, fun, args, new_acc)

      {:error, _} = error ->
        error

      term ->
        message =
          "#{module_name(plugin.module)}.#{fun} returned " <>
            "an unexpected value: #{inspect(term)}"

        {:error, message}
    end
  rescue
    exception -> handle_exception(exception, plugin.module, fun)
  end

  @spec update_callback_args(list(), t(), atom(), integer()) :: list()
  defp update_callback_args(args, plugin, fun, arity) do
    if arity === @old_callback_arities[fun] do
      old_fun_name = "#{fun}/#{arity}"
      new_fun_name = "#{fun}/#{arity + 1}"

      msg = [
        old_fun_name,
        " is deprecated. Use ",
        new_fun_name,
        " instead.\nfrom plugin: ",
        plugin.name,
        " (",
        module_name(plugin.module),
        ")"
      ]

      put_msg(:warn, IO.iodata_to_binary(msg))

      args
    else
      args ++ [plugin.args]
    end
  end

  @spec handle_exception(Exception.t(), atom(), atom()) :: Result.t()
  defp handle_exception(exception, module, fun) do
    ex_name = module_name(exception.__struct__)
    ex_msg = Exception.message(exception)
    msg = "#{ex_name} at #{module_name(module)}.#{fun}: #{ex_msg}"

    {:error, msg}
  end

  @spec module_name(atom()) :: binary()
  defp module_name(module) do
    module |> to_string() |> String.replace_prefix("Elixir.", "")
  end
end