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

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

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

@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

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

Следующие атрибуты являются частью типов спецификаций и также являются встроенными в 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 не определены

Вы можете увидеть еще несколько опций, используемых компилятором Erlang, в документации для :compile модуля.