Предоставляет функции для работы с модулями во время компиляции.

Это позволяет разработчику динамически добавлять, удалять и регистрировать атрибуты, прикреплять документацию и так далее.

После компиляции модуля, использование многих функций этого модуля вызовет ошибки, так как они не предназначены для проверки данных во время выполнения. Большинство данных во время выполнения можно проверить с помощью функции __info__/1, прикрепленной к каждому скомпилированному модулю.

Атрибуты модуля

Каждый модуль может быть снабжен одним или несколькими атрибутами. Следующие из них в настоящее время определены Elixir:

@after_compile

Обработчик, который будет вызван сразу после компиляции текущего модуля. Принимает модуль или {module, function_name}. См. раздел «Обработчики компиляции» ниже.

@before_compile

Обработчик, который будет вызван перед компиляцией модуля. Принимает модуль или {module, function_or_macro_name} кортеж. См. раздел «Обработчики компиляции» ниже.

@behaviour

Обратите внимание на британское написание!

Модули могут ссылаться на реализации, чтобы гарантировать, что они реализуют требуемые специфические сигнатуры функций, определенные @callback.

Например, вы можете указать поведение URI.Parser следующим образом:

defmodule URI.Parser do
  @doc "Defines a default port"
  @callback default_port() :: integer

  @doc "Parses the given URL"
  @callback parse(uri_info :: URI.t()) :: URI.t()
end

А затем модуль может использовать его так:

defmodule URI.HTTP do
  @behaviour URI.Parser
  def default_port(), do: 80
  def parse(info), do: info
end

Если поведение изменяется или URI.HTTP не реализует одну из обратных функций, будет выведено предупреждение.

Для подробной документации см. документацию типов спецификаций поведения.

@impl

Для помощи в правильной реализации поведений, вы можете дополнительно объявить @impl для реализованных обратных функций поведения. Это делает обратные функции явными и может помочь вам обнаружить ошибки в вашем коде. Компилятор выведет предупреждение в этих случаях:

• если вы помечаете функцию @impl, когда эта функция не является обратной функцией.

• если вы не помечаете функцию @impl, когда другие функции помечены @impl. Если вы пометили одну функцию @impl, вы должны пометить все другие обратные функции для данного поведения как @impl.

@impl работает на основе контекста. Если вы генерируете функцию с помощью макроса и помечаете её как @impl, это не повлияет на модуль, в котором эта функция генерируется.

@impl также помогает с поддержанием, сделав ясным для других разработчиков, что функция реализует обратную функцию.

Используя @impl, приведенный выше пример можно переписать как:

defmodule URI.HTTP do
  @behaviour URI.Parser

  @impl true
  def default_port(), do: 80

  @impl true
  def parse(info), do: info
end

Вы можете передать либо false, true, или конкретное поведение в @impl.

defmodule Foo do
  @behaviour Bar
  @behaviour Baz

  # Will warn if neither Bar nor Baz specify a callback named bar/0.
  @impl true
  def bar(), do: :ok

  # Will warn if Baz does not specify a callback named baz/0.
  @impl Baz
  def baz(), do: :ok
end

Код стал более читабельным, поскольку теперь понятно, какие функции являются частью вашего API, а какие — реализациями обратных функций. Чтобы усилить эту идею, @impl true автоматически помечает функцию как @doc false, отключая документацию, если @doc явно не установлено.

@compile

Определяет параметры для компиляции модуля. Это используется для настройки как Elixir, так и Erlang компиляторов, а также любых других этапов компиляции, добавленных внешними инструментами. Например:

defmodule MyModule do
  @compile {:inline, my_fun: 1}

  def my_fun(arg) do
    to_string(arg)
  end
end

Несколько применений @compile будут накапливаться вместо переопределения предыдущих. Смотрите раздел «Параметры компиляции» ниже.

@deprecated

Предоставляет причину устаревания функции. Например:

defmodule Keyword do
  @deprecated "Use Kernel.length/1 instead"
  def size(keyword) do
    length(keyword)
  end
end

Компилятор Mix автоматически ищет вызовы устаревших модулей и выводит предупреждения во время компиляции.

Использование атрибута @deprecated также будет отражено в документации данной функции и макроса. Вы можете выбрать между атрибутом @deprecated и метаданными документации для предоставления жестких (с предупреждениями) и мягких (без предупреждений) устаревших версий:

Это мягкое устаревание, так как оно просто отмечает документацию как устаревшую:

@doc deprecated: "Use Kernel.length/1 instead"
def size(keyword)

Это жесткое устаревание, так как оно выводит предупреждения и отмечает документацию как устаревшую:

@deprecated "Use Kernel.length/1 instead"
def size(keyword)

В настоящее время @deprecated поддерживает только функции и макросы. Однако вы можете использовать ключ :deprecated в метаданных аннотации для аннотации документации модулей, типов и обратных функций.

Мы рекомендуем использовать эту функцию с осторожностью, особенно авторам библиотек. Устаревание кода всегда перекладывает бремя на пользователей библиотек. Мы также рекомендуем поддерживать устаревшую функциональность в течение длительного времени, даже после устаревания, давая разработчикам достаточно времени для обновления (за исключением случаев, когда сохранение устаревшего API нежелательно, например, в случае проблем с безопасностью).

@doc и @typedoc

Предоставляет документацию для сущности, которая следует за атрибутом. @doc следует использовать с функцией, макросом, обратной функцией или макрообратной функцией, в то время как @typedoc с типом (публичным или неявным).

Принимает строку (часто heredoc) или false, где @doc false сделает сущность невидимой для инструментов извлечения документации, таких как ExDoc. Например:

defmodule MyModule do
  @typedoc "This type"
  @typedoc since: "1.1.0"
  @type t :: term

  @doc "Hello world"
  @doc since: "1.1.0"
  def hello do
    "world"
  end

  @doc """
  Sums `a` to `b`.
  """
  def sum(a, b) do
    a + b
  end
end

Как видно из примера выше, @doc и @typedoc также принимают список ключевых слов, который служит способом предоставления произвольных метаданных о сущности. Инструменты, такие как ExDoc и IEx, могут использовать эту информацию для отображения аннотаций. Распространенный случай использования — since, который может использоваться для аннотирования версии, в которой функция была добавлена.

Как показано в примере, можно использовать эти атрибуты более одного раза перед сущностью. Однако компилятор выдаст предупреждение, если они будут использованы дважды с двоичными данными, так как это заменит текст документации из предыдущего использования. Несколько применений со списками ключевых слов будут объединять списки в один.

Обратите внимание, что поскольку компилятор также определяет некоторые дополнительные метаданные, есть несколько зарезервированных ключей, которые будут игнорироваться и по которым будет выведено предупреждение при использовании. В настоящее время это: :opaque и :defaults.

После компиляции этого модуля эта информация станет доступной через функцию Code.fetch_docs/1.

@dialyzer

Определяет предупреждения для запроса или подавления при использовании версии :dialyzer, которая поддерживает атрибуты модулей.

Принимает атом, кортеж или список атомов и кортежей. Например:

defmodule MyModule do
  @dialyzer {:nowarn_function, my_fun: 1}

  def my_fun(arg) do
    M.not_a_function(arg)
  end
end

Для списка поддерживаемых предупреждений см. :dialyzer модуль.

Несколько применений @dialyzer будут накапливаться вместо переопределения предыдущих.

@external_resource

Указывает внешний ресурс для текущего модуля.

Иногда модуль встраивает информацию из внешнего файла. Этот атрибут позволяет модулю аннотировать, какие внешние ресурсы использовались.

Инструменты могут использовать эту информацию, чтобы гарантировать, что модуль будет перекомпилирован в случае изменения каких-либо внешних ресурсов, см., например: mix compile.elixir.

Если внешний ресурс не существует, модуль всё ещё имеет зависимость от него, что приводит к перекомпиляции модуля как только файл будет добавлен.

@file

Изменяет имя файла, используемое в трассировках стека для функции или макроса, за которым следует атрибут, например:

defmodule MyModule do
  @doc "Hello world"
  @file "hello.ex"
  def hello do
    "world"
  end
end

@moduledoc

Предоставляет документацию для текущего модуля.

defmodule MyModule do
  @moduledoc """
  A very useful module.
  """
  @moduledoc authors: ["Alice", "Bob"]
end

Принимает строку (часто heredoc) или false, где @moduledoc false сделает модуль невидимым для инструментов извлечения документации, таких как ExDoc.

Аналогично @doc также принимает список ключевых слов для предоставления метаданных о модуле. Для более подробной информации см. документацию по @doc выше.

После компиляции этого модуля эта информация станет доступной через функцию Code.fetch_docs/1.

@on_definition

Обработчик, который будет вызван при определении каждой функции или макроса в текущем модуле. Полезно при аннотировании функций.

Принимает модуль или {module, function_name} кортеж. См. раздел «Обработчики компиляции» ниже.

@on_load

Обработчик, который будет вызван всякий раз, когда модуль загружается.

Принимает имя функции (в виде атома) функции в текущем модуле или {function_name, 0} кортеж, где function_name — имя функции в текущем модуле. Функция должна иметь арность 0 (без аргументов). Если функция не возвращает :ok, загрузка модуля будет прервана. Например:

defmodule MyModule do
  @on_load :load_check

  def load_check do
    if some_condition() do
      :ok
    else
      :abort
    end
  end

  def some_condition do
    false
  end
end

Модули, скомпилированные с HiPE, не вызовут этот обработчик.

@vsn

Укажите версию модуля. Принимает любое допустимое значение Elixir, например:

defmodule MyModule do
  @vsn "1.0"
end

Атрибуты структур

• @derive — выводит реализацию для данного протокола для структуры, определенной в текущем модуле

• @enforce_keys — гарантирует, что заданные ключи всегда устанавливаются при построении структуры, определенной в текущем модуле

См. Kernel.defstruct/1 для получения дополнительной информации о создании и использовании структур.

Атрибуты типов спецификаций

Следующие атрибуты являются частью типов спецификаций и также являются встроенными в Elixir:

• @type - определяет тип, используемый в @spec
• @typep - определяет закрытый тип, используемый в @spec
• @opaque - определяет непрозрачный тип, используемый в @spec
• @spec - предоставляет спецификацию для функции
• @callback - предоставляет спецификацию для обратного вызова поведения
• @macrocallback - предоставляет спецификацию для обратного вызова макроса поведения
• @optional_callbacks - указывает, какие обратные вызовы поведения и обратные вызовы макроса поведения являются необязательными
• @impl - объявляет реализацию функции обратного вызова или макроса

Для получения подробной документации см. документацию по типам.

Настраиваемые атрибуты

В дополнение к встроенным атрибутам, описанным выше, можно также добавить настраиваемые атрибуты. Настраиваемые атрибуты выражаются с помощью оператора @/1 за которым следует допустимое имя переменной. Значение, присваиваемое настраиваемому атрибуту, должно быть допустимым значением Elixir:

defmodule MyModule do
  @custom_attr [some: "stuff"]
end

Для получения более подробной информации об расширенных возможностях при определении настраиваемых атрибутов, см. register_attribute/3.

Обратные вызовы компиляции

Существует три обратных вызова, которые вызываются при определении функций, а также до и сразу после генерации байткода модуля.

@after_compile

Обратный вызов, который будет вызван сразу после компиляции текущего модуля.

Принимает модуль или кортеж {module, function_name}. Функция должна принимать два аргумента: среду модуля и его байткод. Если предоставлен только модуль, функция предполагается __after_compile__/2.

Обратные вызовы будут выполняться в порядке их регистрации.

Пример

defmodule MyModule do
  @after_compile __MODULE__

  def __after_compile__(env, _bytecode) do
    IO.inspect(env)
  end
end

@before_compile

Обратный вызов, который будет вызван перед компиляцией модуля.

Принимает модуль или кортеж {module, function_or_macro_name}. Функция/макрос должны принимать один аргумент: среду модуля. Если это макрос, возвращаемое им значение будет вставлено в конец определения модуля перед началом компиляции.

Если предоставлен только модуль, функция/макрос предполагается __before_compile__/1.

Обратные вызовы будут выполняться в порядке их регистрации. Любое переопределяемое определение будет сделано конкретным до запуска первого обратного вызова. Определение может быть снова сделано переопределяемым в другом обратном вызове до компиляции, и оно будет окончательно сделано конкретным после выполнения всех обратных вызовов.

Примечание: в отличие от @after_compile, функция/макрос обратного вызова должен быть помещен в отдельный модуль (потому что при вызове обратного вызова текущий модуль еще не существует).

Пример

defmodule A do
  defmacro __before_compile__(_env) do
    quote do
      def hello, do: "world"
    end
  end
end

defmodule B do
  @before_compile A
end

B.hello()
#=> "world"

@on_definition

Обратный вызов, который будет вызван при определении каждой функции или макроса в текущем модуле. Полезно при аннотировании функций.

Принимает модуль или кортеж {module, function_name}. Функция должна принимать 6 аргументов:

• среду модуля
• вид функции/макроса: :def, :defp, :defmacro, или :defmacrop
• имя функции/макроса
• список скобочных аргументов
• список скобочных условий
• скобочное тело функции

Если функция/макрос, подлежащий определению, имеет несколько разделов, обратный вызов будет вызван для каждого раздела.

В отличие от других обратных вызовов, @on_definition будет вызывать только функции, а не макросы. Это для предотвращения @on_definition обратных вызовов от переопределения только что определенных функций в пользу более явных подходов.

Если предоставлен только модуль, функция предполагается __on_definition__/6.

Пример

defmodule Hooks do
  def on_def(_env, kind, name, args, guards, body) do
    IO.puts("Defining #{kind} named #{name} with args:")
    IO.inspect(args)
    IO.puts("and guards")
    IO.inspect(guards)
    IO.puts("and body")
    IO.puts(Macro.to_string(body))
  end
end

defmodule MyModule do
  @on_definition {Hooks, :on_def}

  def hello(arg) when is_binary(arg) or is_list(arg) do
    "Hello" <> to_string(arg)
  end

  def hello(_) do
    :ok
  end
end

Опции компиляции

Атрибут @compile принимает различные параметры, которые используются как компиляторами Elixir, так и Erlang. Некоторые распространенные случаи использования описаны ниже:

• @compile :debug_info - включает :debug_info независимо от соответствующего параметра в Code.get_compiler_option/1

• @compile {:debug_info, false} - отключает :debug_info независимо от соответствующего параметра в Code.get_compiler_option/1

• @compile {:inline, some_fun: 2, other_fun: 3} - встраивает заданные пары имя/арность. Встраивание применяется локально, вызовы из другого модуля не затрагиваются этой опцией

• @compile {:autoload, false} - отключает автоматическую загрузку модулей после компиляции. Вместо этого модуль загрузится после его отправки

• @compile {:no_warn_undefined, Mod} или @compile {:no_warn_undefined, {Mod, fun, arity}} - не выдает предупреждение, если указанный модуль или указанный Mod.fun/arity не определены