Модуль поведение

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

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

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

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

Атрибуты типов

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