defmodule Serum.Theme do
  @moduledoc """
  A behaviour that all Serum theme module must implement.

  A Serum theme is a set of predefined templates and assets which are used
  while Serum is building a project.

  More specifically, a Serum theme is a Mix project which has the following
  contents:

  - Modules that implement this behaviour,
  - And theme files such as templates, includes, and other assets.
    These files are usually stored in the `priv/` directory.

  Your theme package must have at least one module that implements this
  behaviour, as Serum will call callbacks of this behaviour to ensure that your
  modules provide appropriate theme resources when needed.

  ## Using Serum Themes

  To use a Serum theme, you first need to add the theme package to your
  dependencies list.

      # mix.exs
      defp deps do
      [
        {:serum, "~> 1.0"},
        # ...

        # If the theme is available on Hex.pm:
        {:serum_theme_sample, "~> 1.0"}

        # If the theme is available on somewhere else:
        {:serum_theme_sample, git: "https://github.com/..."}
      ]
      end

  Fetch and build the theme package using `mix`.

      $ mix do deps.get, deps.compile

  To configure your Serum project to use a theme, you need to put a `:theme`
  key in your `serum.exs`.

      # serum.exs:
      %{
        theme: Serum.Themes.Sample,
        # ...
      }

  Read the documentation provided by the theme author, to see the list of files
  the theme consists of. Files provided by the theme are always overridden by
  corresponding files in your project directory. So it is safe to remove files
  from your project if the theme has ones.

  Finally, try building your project to see if the theme is applied correctly.

      $ mix serum.server
      # Or,
      $ MIX_ENV=prod mix serum.build
  """

  use Agent
  import Serum.IOProxy, only: [put_err: 2]
  alias Serum.Result

  defstruct module: nil,
            name: "",
            description: "",
            author: "",
            legal: "",
            version: Version.parse!("0.0.0")

  @type t :: %__MODULE__{
          module: module() | nil,
          name: binary(),
          description: binary(),
          author: binary(),
          legal: binary(),
          version: Version.t()
        }

  @serum_version Version.parse!(Mix.Project.config()[:version])

  #
  # Callbacks
  #

  @doc "Returns the theme name."
  @callback name() :: binary()

  @doc "Returns a short descriptive text about the theme."
  @callback description() :: binary()

  @doc "Returns information about the theme author."
  @callback author() :: binary()

  @doc "Returns the legal information about the theme, such as license."
  @callback legal() :: binary()

  @doc """
  Returns the theme version.

  The returned value must follow the semantic versioning scheme.
  """
  @callback version() :: binary()

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

  Read the "Requirements" section in the documentation for `Version` module
  for more information about version requirement format.
  """
  @callback serum() :: binary()

  @doc """
  Returns a list of paths to include files.

  All paths in the list must end with `".html.eex"`. Anything that does not end
  with `".html.eex"` will be ignored.

  ## Example Return Value

      [
        "/path/to/theme/priv/includes/nav.html.eex",
        "/path/to/theme/priv/includes/sidebar.html.eex",
        "/path/to/theme/priv/includes/footer.html.eex"
      ]
  """
  @callback get_includes() :: [binary()]

  @doc """
  Returns a list of paths to template files.

  All paths in the list must end with `".html.eex"`. Anything that does not end
  with `".html.eex"` will be ignored.

  ## Example Return Value

      [
        "/path/to/theme/priv/templates/base.html.eex",
        "/path/to/theme/priv/templates/list.html.eex",
        "/path/to/theme/priv/templates/post.html.eex"
      ]
  """
  @callback get_templates() :: [binary()]

  @doc """
  Returns a path to the assets directory.

  All files in the directory pointed by the returned value will be copied to
  the destination assets directory using `File.cp_r/2`.

  This callback may return `false` to indicate that no asset will be copied.
  """
  @callback get_assets() :: binary() | false

  #
  # Theme Consumer Functions
  #

  @doc false
  @spec start_link(any()) :: Agent.on_start()
  def start_link(_) do
    Agent.start_link(fn -> nil end, name: __MODULE__)
  end

  @doc false
  @spec load(module() | nil) :: Result.t(t())
  def load(module_or_nil)

  def load(nil) do
    Agent.update(__MODULE__, fn _ -> nil end)

    {:ok, %__MODULE__{}}
  end

  def load(module) do
    case make_theme(module) do
      {:ok, theme} ->
        Agent.update(__MODULE__, fn _ -> theme end)

        {:ok, theme}

      {:error, _} = error ->
        error
    end
  end

  @spec make_theme(module()) :: Result.t(t())
  defp make_theme(module) do
    name = module.name()
    version = Version.parse!(module.version())

    validate_serum_version(name, module.serum())

    result = %__MODULE__{
      module: module,
      name: name,
      description: module.description(),
      author: module.author(),
      legal: module.legal(),
      version: version
    }

    {:ok, result}
  rescue
    exception ->
      ex_name = module_name(exception.__struct__)
      ex_msg = Exception.message(exception)
      mod_name = module_name(module)
      msg = "#{ex_name} while loading theme (module: #{mod_name}): #{ex_msg}"

      {:error, msg}
  end

  @spec validate_serum_version(binary(), Version.requirement()) :: :ok
  defp validate_serum_version(name, requirement) do
    if Version.match?(@serum_version, requirement) do
      :ok
    else
      msg =
        "The theme \"#{name}\" is not compatible with " <>
          "the current version of Serum(#{@serum_version}). " <>
          "This theme may not work as intended."

      put_err(:warn, msg)
    end
  end

  @doc false
  @spec get_includes() :: Result.t(%{optional(binary()) => binary()})
  def get_includes do
    case Agent.get(__MODULE__, & &1) do
      %__MODULE__{} = theme -> do_get_includes(theme)
      nil -> {:ok, %{}}
    end
  end

  @spec do_get_includes(t()) :: Result.t(%{optional(binary()) => binary()})
  defp do_get_includes(%__MODULE__{module: module}) do
    case get_list(module, :get_includes, []) do
      {:ok, paths} ->
        result =
          paths
          |> Enum.filter(&String.ends_with?(&1, ".html.eex"))
          |> Enum.map(&{Path.basename(&1, ".html.eex"), &1})
          |> Map.new()

        {:ok, result}

      {:error, _} = error ->
        error
    end
  end

  @doc false
  @spec get_templates() :: Result.t(%{optional(binary()) => binary()})
  def get_templates do
    case Agent.get(__MODULE__, & &1) do
      %__MODULE__{} = theme -> do_get_templates(theme)
      nil -> {:ok, %{}}
    end
  end

  @spec do_get_templates(t()) :: Result.t(%{optional(binary()) => binary()})
  defp do_get_templates(%__MODULE__{module: module}) do
    case get_list(module, :get_templates, []) do
      {:ok, paths} ->
        result =
          paths
          |> Enum.map(&{Path.basename(&1, ".html.eex"), &1})
          |> Enum.filter(&String.ends_with?(elem(&1, 1), ".html.eex"))
          |> Map.new()

        {:ok, result}

      {:error, _} = error ->
        error
    end
  end

  @spec get_list(atom(), atom(), list()) :: Result.t([binary()])
  defp get_list(module, fun, args) do
    with {:ok, paths} <- call_function(module, fun, args),
         :ok <- check_list_type(paths) do
      {:ok, paths}
    else
      {:error, _} = error ->
        error

      {:bad, x} ->
        callee = "#{module_name(module)}.#{fun}"
        msg = "#{callee}: expected a list of strings, got: #{inspect(x)}"

        {:error, msg}

      {:bad_item, x} ->
        callee = "#{module_name(module)}.#{fun}"
        msg = "#{callee} expected a list of strings, got: #{inspect(x)} in the list"

        {:error, msg}
    end
  end

  @spec check_list_type(term()) :: :ok | {:bad, term()} | {:bad_item, term()}
  defp check_list_type(maybe_list)
  defp check_list_type([]), do: :ok
  defp check_list_type([x | xs]) when is_binary(x), do: check_list_type(xs)
  defp check_list_type([x | _xs]), do: {:bad_item, x}
  defp check_list_type(x), do: {:bad, x}

  @doc false
  @spec get_assets() :: Result.t(binary() | false)
  def get_assets do
    case Agent.get(__MODULE__, & &1) do
      %__MODULE__{} = theme -> get_assets(theme)
      nil -> {:ok, false}
    end
  end

  @spec get_assets(t()) :: Result.t(binary() | false)
  defp get_assets(%__MODULE__{module: module}) do
    case call_function(module, :get_assets, []) do
      {:ok, path} when is_binary(path) ->
        do_get_assets(path)

      {:ok, false} ->
        {:ok, false}

      {:error, _} = error ->
        error

      x ->
        mod_name = module_name(module)
        msg = "#{mod_name}.get_assets: expected a string, got: #{inspect(x)}"

        {:error, msg}
    end
  end

  @spec do_get_assets(binary()) :: Result.t(binary())
  defp do_get_assets(path) do
    case File.stat(path) do
      {:ok, %File.Stat{type: :directory}} -> {:ok, path}
      {:ok, %File.Stat{}} -> {:error, {:enotdir, path, 0}}
      {:error, reason} -> {:error, {reason, path, 0}}
    end
  end

  @spec call_function(atom(), atom(), list()) :: Result.t(term())
  defp call_function(module, fun, args) do
    {:ok, apply(module, fun, args)}
  rescue
    exception ->
      ex_name = module_name(exception.__struct__)
      ex_msg = Exception.message(exception)
      mod_name = module_name(module)
      msg = "#{ex_name} from #{mod_name}.#{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
