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

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

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

Принимает модуль или {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 не определены