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

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

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

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

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

@after_compile

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

@after_verify (с версии v1.14.0)

Хук, который будет вызван сразу после проверки текущего модуля на наличие неопределённых функций, устаревших и т. п. Принимает модуль или {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 (с версии v1.5.0)

Для помощи в правильной реализации поведения можно необязательно объявить @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 (с версии v1.6.0)

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

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, который сделает сущность невидимой для инструментов извлечения документации, таких как ExDoc
• список ключевых слов, начиная с Elixir 1.7.0

Например:

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

Как видно из примера, начиная с Elixir 1.7.0 @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.

Указанный путь к файлу интерпретируется как относительный к папке, содержащей проект mix.exs, которая является текущей рабочей директорией, а не файлом, где @external_resource объявлен.

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

@file

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

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

Обратите внимание, что это верно только для исключений/диагностики, которые исходят из внутреннего пространства определения (включая шаблоны и условия). Например:

defmodule MyModule do # <---- module definition
  @file "hello.ex"
  defp unused(a) do # <---- function definition
    "world" # <---- function scope
  end

  @file "bye.ex"
  def unused(_), do: true
end

Если вы запустите этот код со второй частью определения "unused" закомментированной, вы увидите, что hello.ex используется в трассировке стека при сообщении предупреждений, но если вы её раскомментируете, вы увидите, что ошибка не будет упоминать bye.ex, потому что это ошибка уровня модуля, а не уровня выражения.

@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.

@nifs (с версии v1.16.0)

Список функций и их арностей, которые будут переопределены с помощью нативного кода (NIF).

defmodule MyLibrary.MyModule do
  @nifs [foo: 1, bar: 2]

  def foo(arg1), do: :erlang.nif_error(:not_loaded)
  def bar(arg1, arg2), do: :erlang.nif_error(:not_loaded)
end

Для получения дополнительной информации см. документацию Erlang: https://www.erlang.org/doc/man/erl_nif

@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

@on_load

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

Принимает имя функции (как атом) функции в текущем модуле. Функция должна иметь арность 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

@vsn

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

defmodule MyModule do
  @vsn "1.0"
end

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

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

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

См. 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.

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

Существует три обратных вызова компиляции, которые вызываются в данном порядке: @before_compile, @after_compile, и @after_verify. Они описаны ниже.

@before_compile

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

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

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

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

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

Пример

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"

@after_compile

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

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

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

Module функции, ожидающие ещё не скомпилированные модули (например, definitions_in/1) всё ещё доступны на момент вызова @after_compile.

Пример

defmodule MyModule do
  @after_compile __MODULE__

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

@after_verify

Обработчик, который будет вызван сразу после проверки текущего модуля на наличие неопределённых функций, устаревших обозначений и т.д. Модуль всегда проверяется после компиляции. В проектах Mix модуль также проверяется при изменении любых его зависимостей времени выполнения. Поэтому это полезно для проверки текущего модуля, избегая зависимостей во время компиляции.

Принимает модуль или {module, function_name} кортеж. Функция должна принимать один аргумент: имя модуля. При указании только модуля функция предполагается __after_verify__/1.

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

Module функции, ожидающие ещё не скомпилированные модули, больше недоступны на момент вызова @after_verify.

Пример

defmodule MyModule do
  @after_verify __MODULE__

  def __after_verify__(module) do
    IO.inspect(module)
    :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. Обратите внимание, что отключение :debug_info не рекомендуется, так как это лишает компилятор Elixir и других инструментов возможности статического анализа кода. Если вы хотите удалить :debug_info во время развертывания, такие инструменты, как mix release, уже делают это по умолчанию.

• @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 не определены