defmodule TypedStruct.Plugin do
  @moduledoc """
  This module defines the plugin interface for TypedStruct.

  ## Rationale

  Sometimes you may want to define helpers on your structs, for all their fields
  or for the struct as a whole. This plugin interface lets you integrate your
  own needs with TypedStruct.

  ## Plugin definition

  A TypedStruct plugin is a module that implements `TypedStruct.Plugin`. Three
  callbacks are available to you for injecting code at different steps:

    * `c:init/1` lets you inject code where the `TypedStruct.plugin/2` macro is
      called,
    * `c:field/4` lets you inject code on each field definition,
    * `c:after_definition/1` lets you insert code after the struct and its type
      have been defined.

  `use`-ing this module will inject default implementations of all
  three, so you only have to implement those you care about.

  ### Example

  As an example, let’s define a plugin that allows users to add an optional
  description to their structs and fields. This plugin also takes an `upcase`
  option. If set to `true`, all the descriptions are then upcased. It would be
  used this way:

      defmodule MyStruct do
        use TypedStruct

        typedstruct do
          # We import the plugin with the upcase option set to `true`.
          plugin DescribedStruct, upcase: true

          # We can now set a description for the struct.
          description "My struct"

          # We can also set a description on a field.
          field :a_field, String.t(), description: "A field"
          field :second_field, boolean()
        end
      end

  Once compiled, we would optain:

      iex> MyStruct.struct_description()
      "MY STRUCT"
      iex> MyStruct.field_description(:a_field)
      "A FIELD"

  Follows the plugin definition:

      defmodule DescribedStruct do
        use TypedStruct.Plugin

        # The init macro lets you inject code where the plugin macro is called.
        # You can think a bit of it like a `use` but for the scope of the
        # typedstruct block.
        @impl true
        @spec init(keyword()) :: Macro.t()
        defmacro init(opts) do
          quote do
            # Let’s import our custom `description` macro defined below so our
            # users can use it when defining their structs.
            import TypedStructDemoPlugin, only: [description: 1]

            # Let’s also store the upcase option in an attribute so we can
            # access it from the code injected by our `description/1` macro.
            @upcase unquote(opts)[:upcase]
          end
        end

        # This is a public macro our users can call in their typedstruct blocks.
        @spec description(String.t()) :: Macro.t()
        defmacro description(description) do
          quote do
            # Here we simply evaluate the result of __description__/2. We need
            # this indirection to be able to use @upcase after is has been
            # evaluated, but still in the code generation process. This way, we
            # can upcase the strings *at build time* if needed. It’s just a tiny
            # refinement :-)
            Module.eval_quoted(
              __MODULE__,
              TypedStructDemoPlugin.__description__(__MODULE__, unquote(description))
            )
          end
        end

        @spec __description__(module(), String.t()) :: Macro.t()
        def __description__(module, description) do
          # Maybe upcase the description at build time.
          description =
            module
            |> Module.get_attribute(:upcase)
            |> maybe_upcase(description)

          quote do
            # Let’s just generate a constant function that returns the
            # description.
            def struct_description, do: unquote(description)
          end
        end

        # The field callback is called for each field defined in the typedstruct
        # block. You get exactly what the user has passed to the field macro,
        # plus options from every plugin init. The `env` variable contains the
        # environment as it stood at the moment of the corresponding
        # `TypedStruct.field/3` call.
        @impl true
        @spec field(atom(), any(), keyword(), Macro.Env.t()) :: Macro.t()
        def field(name, _type, opts, _env) do
          # Same as for the struct description, we want to upcase at build time
          # if necessary. As we do not have access to the module here, we cannot
          # access @upcase. This is not an issue since the option is
          # automatically added to `opts`, in addition to the options passed to
          # the field macro.
          description = maybe_upcase(opts[:upcase], opts[:description] || "")

          quote do
            # We define a clause matching the field name returning its optional
            # description.
            def field_description(unquote(name)), do: unquote(description)
          end
        end

        defp maybe_upcase(true, description), do: String.upcase(description)
        defp maybe_upcase(_, description), do: description

        # The after_definition callback is called after the struct and its type
        # have been defined, at the end of the `typedstruct` block.
        @impl true
        @spec after_definition(opts :: keyword()) :: Macro.t()
        def after_definition(_opts) do
          quote do
            # Here we just clean the @upcase attribute so that it does not
            # pollute our user’s modules.
            Module.delete_attribute(__MODULE__, :upcase)
          end
        end
      end
  """

  @doc """
  Injects code where `TypedStruct.plugin/2` is called.
  """
  @macrocallback init(opts :: keyword()) :: Macro.t()

  @doc deprecated: "Use TypedStruct.Plugin.field/4 instead"
  @callback field(name :: atom(), type :: any(), opts :: keyword()) ::
              Macro.t()

  @doc """
  Injects code after each field definition.

  `name` and `type` are the exact values passed to the `TypedStruct.field/3`
  macro in the `typedstruct` block. `opts` is the concatenation of the options
  passed to the `field` macro and those from the plugin init. `env` is the
  environment at the time of each field definition.
  """
  @callback field(
              name :: atom(),
              type :: any(),
              opts :: keyword(),
              env :: Macro.Env.t()
            ) ::
              Macro.t()

  @doc """
  Injects code after the struct and its type have been defined.
  """
  @callback after_definition(opts :: keyword()) :: Macro.t()

  @optional_callbacks [field: 3, field: 4]

  @doc false
  defmacro __using__(_opts) do
    quote do
      @behaviour TypedStruct.Plugin
      @before_compile {unquote(__MODULE__), :maybe_define_field_4}

      @doc false
      defmacro init(_opts), do: nil

      @doc false
      def after_definition(_opts), do: nil

      defoverridable init: 1, after_definition: 1
    end
  end

  @doc false
  defmacro maybe_define_field_4(env) do
    case {Module.defines?(env.module, {:field, 3}, :def),
          Module.defines?(env.module, {:field, 4}, :def)} do
      {false, false} ->
        # If none is present, let’s define a default implementation for field/4.
        quote do
          @doc false
          def field(_name, _type, _opts, _env), do: nil
        end

      {false, true} ->
        # If field/4 is present, allright.
        nil

      {true, false} ->
        # If field/3 is present, let’s define field/4 from it for compatibility.
        IO.warn([
          Atom.to_string(env.module),
          " defines field/3, which is deprecated. Please use field/4 instead"
        ])

        quote do
          @doc false
          def field(name, type, opts, _env) do
            field(name, type, opts)
          end
        end

      {true, true} ->
        # If both are present, this is an issue.
        IO.warn([
          Atom.to_string(env.module),
          " defines both field/3 and field/4 callbacks.",
          " Only field/4 will be invoked"
        ])
    end
  end
end