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

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

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

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

Для большего контроля над перекомпиляцией модуля см. __mix_recompile__?/0.

@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 - предоставляет описание для обратного вызова поведения (и генерирует функцию behaviour_info/1 в модуле, см. ниже)
• @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 не определены

Сгенерированные функции

Иногда компилятор генерирует публичные функции внутри модулей. Они документированы ниже.

behaviour_info/1

Эта функция генерируется для модулей, которые определяют поведение, то есть которые имеют одно или несколько определений @callback. Подпись этой функции, выраженная как спецификация, имеет вид:

@spec behaviour_info(:callbacks) :: [function_info]
  when function_info: {function_name :: atom(), arity :: non_neg_integer()}

@spec behaviour_info(:optional_callbacks) :: [function_info]
  when function_info: {function_name :: atom(), arity :: non_neg_integer()}

behaviour_info(:callbacks) включает необязательные обратные вызовы.

Например:

iex> Enum.sort(GenServer.behaviour_info(:callbacks))
[
  code_change: 3,
  format_status: 1,
  format_status: 2,
  handle_call: 3,
  handle_cast: 2,
  handle_continue: 2,
  handle_info: 2,
  init: 1,
  terminate: 2
]

module_info/0

Эта функция генерируется для всех модулей. Она возвращает все атрибуты, возвращаемые module_info/1 (см. ниже), но в виде одного списка ключевых слов. См. также документацию Erlang.

module_info/1

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

@spec module_info(:module) :: module() # Returns the module itself
@spec module_info(:attributes) :: keyword()
@spec module_info(:compile) :: keyword()
@spec module_info(:md5) :: binary()
@spec module_info(:nifs) :: module()
@spec module_info(:exports) :: [function_info]
  when function_info: {function_name :: atom(), arity :: non_neg_integer()}
@spec module_info(:functions) :: [function_info]
  when function_info: {function_name :: atom(), arity :: non_neg_integer()}

Например:

iex> URI.module_info(:module)
URI
iex> {:decode_www_form, 1} in URI.module_info(:exports)
true

Для получения дополнительной информации о module_info/1, также ознакомьтесь с документацией Erlang.

__info__/1

Эта функция генерируется для всех модулей. Она похожа на module_info/1 , но включает некоторую дополнительную информацию, специфичную для Elixir, такую как информация о структуре и макросах. Для получения документации см. Module.__info__/1.