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

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

После компиляции модуля использование многих функций в этом модуле приведет к ошибкам, так как они не предназначены для проверки данных во время выполнения. Большинство данных во время выполнения можно проверить с помощью функции __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

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

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

@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}. Функция должна принимать 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 для получения дополнительной информации о построении и использовании структур.

Атрибуты typespec

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

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

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

Пользовательские атрибуты

В дополнение к встроенным атрибутам, перечисленным выше, можно добавить пользовательские атрибуты. Пользовательские атрибуты выражаются с использованием оператора @/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__/2.

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

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