Ядро

Логический оператор "и".

Обеспечивает оператор короткого замыкания, который вычисляет и возвращает второе выражение только в том случае, если первое выражение вычисляется как истинное значение (ни false ни nil). В противном случае возвращает первое выражение.

Запрещено в условиях охраны.

Примеры

iex> Enum.empty?([]) && Enum.empty?([])
true

iex> List.first([]) && true
nil

iex> Enum.empty?([]) && List.first([1])
1

iex> false && throw(:bad)
false

Обратите внимание, что в отличие от and/2, этот оператор принимает любое выражение в качестве первого аргумента, а не только булевы значения.

@spec integer() ** non_neg_integer() :: integer()

@spec integer() ** neg_integer() :: float()

@spec float() ** float() :: float()

@spec integer() ** float() :: float()

@spec float() ** integer() :: float()

Оператор возведения в степень.

Принимает два числа на вход. Если оба являются целыми числами и правая часть (показатель степени) также больше или равна 0, то результат также будет целым числом. В противном случае возвращается число с плавающей точкой.

Примеры

iex> 2 ** 2
4
iex> 2 ** -4
0.0625

iex> 2.0 ** 2
4.0
iex> 2 ** 2.0
4.0

@spec list() ++ term() :: maybe_improper_list()

Оператор конкатенации списков. Объединяет правильный список и элемент, возвращая список.

Сложность операции a ++ b пропорциональна length(a), поэтому следует избегать многократного добавления в списки произвольной длины, например, list ++ [element]. Вместо этого рассмотрите добавление в начало с помощью [element | rest] и последующего обращения списка.

Если операнд right не является правильным списком, возвращается неправильный список. Если операнд left не является правильным списком, генерируется исключение ArgumentError.

Встроен в компилятор.

Примеры

iex> [1] ++ [2, 3]
[1, 2, 3]

iex> ~c"foo" ++ ~c"bar"
~c"foobar"

# a non-list on the right will return an improper list
# with said element at the end
iex> [1, 2] ++ 3
[1, 2 | 3]
iex> [1, 2] ++ {3, 4}
[1, 2 | {3, 4}]

# improper list on the right will return an improper list
iex> [1] ++ [2 | 3]
[1, 2 | 3]

Оператор ++/2 является правоассоциативным, что означает:

iex> [1, 2, 3] -- [1] ++ [2]
[3]

Что эквивалентно:

iex> [1, 2, 3] -- ([1] ++ [2])
[3]

@spec list() -- list() :: list()

Оператор вычитания списков. Удаляет первое вхождение элемента из левого списка для каждого элемента в правом.

Эта функция оптимизирована, поэтому сложность a -- b пропорциональна length(a) * log(length(b)). См. также руководство по эффективности Erlang .

Встроен в компилятор.

Примеры

iex> [1, 2, 3] -- [1, 2]
[3]

iex> [1, 2, 3, 2, 1] -- [1, 2, 2]
[3, 1]

Оператор --/2 является правоассоциативным, что означает:

iex> [1, 2, 3] -- [2] -- [3]
[1, 3]

Что эквивалентно:

iex> [1, 2, 3] -- ([2] -- [3])
[1, 3]

Создаёт полный срез диапазона 0..-1//1.

Этот макрос возвращает диапазон со следующими свойствами:

• При перечислении он пустой

• При использовании в качестве slice, возвращает срезанный элемент как есть

См. ..///3 и модуль Range для получения дополнительной информации.

Примеры

iex> Enum.to_list(..)
[]

iex> String.slice("Hello world!", ..)
"Hello world!"

Создаёт диапазон от first до last.

Если first меньше last, диапазон будет возрастать от first до last. Если first равно last, диапазон будет содержать один элемент, который является самим числом.

Если first больше last, диапазон будет убывать от first до last, хотя это поведение устарело. Вместо этого используйте явное указание шага с помощью first..last//-1.

См. модуль Range для получения дополнительной информации.

Примеры

iex> 0 in 1..3
false
iex> 2 in 1..3
true

iex> Enum.to_list(1..3)
[1, 2, 3]

Создаёт диапазон от first до last с шагом step.

См. модуль Range для получения дополнительной информации.

Примеры

iex> 0 in 1..3//1
false
iex> 2 in 1..3//1
true
iex> 2 in 1..3//2
false

iex> Enum.to_list(1..3//1)
[1, 2, 3]
iex> Enum.to_list(1..3//2)
[1, 3]
iex> Enum.to_list(3..1//-1)
[3, 2, 1]
iex> Enum.to_list(1..0//1)
[]

Оператор логического "не".

Принимает любое значение (а не только булевы) и возвращает true если value равно false или nil; в противном случае возвращает false.

Запрещено в условиях охраны.

Примеры

iex> !Enum.empty?([])
false

iex> !List.first([])
true

Оператор бинарной конкатенации. Объединяет два бинарных значения.

Вызывает исключение ArgumentError, если один из аргументов не является бинарным.

Примеры

iex> "foo" <> "bar"
"foobar"

Оператор <>/2 также может использоваться в шаблонах соответствия (и условиях охраны), если левый аргумент является литеральным бинарным значением:

iex> "foo" <> x = "foobar"
iex> x
"bar"

x <> "bar" = "foobar" приведёт к исключению ArgumentError.

@spec String.t() =~ (String.t() | Regex.t()) :: boolean()

Оператор соответствия по тексту. Сопоставляет выражение слева со строкой или регулярным выражением справа.

Если справа стоит регулярное выражение, возвращает true если left соответствует правому выражению.

Если справа стоит строка, возвращает true если left содержит right.

Примеры

iex> "abcd" =~ ~r/c(d)/
true

iex> "abcd" =~ ~r/e/
false

iex> "abcd" =~ ~r//
true

iex> "abcd" =~ "bc"
true

iex> "abcd" =~ "ad"
false

iex> "abcd" =~ "abcd"
true

iex> "abcd" =~ ""
true

Для получения дополнительной информации о регулярных выражениях, пожалуйста, обратитесь к модулю Regex.

Унарный оператор атрибута модуля.

Читает и записывает атрибуты в текущем модуле.

Классический пример атрибутов — аннотирование модуля, реализующего поведение OTP, например GenServer:

defmodule MyServer do
  @behaviour GenServer
  # ... callbacks ...
end

По умолчанию Elixir поддерживает все атрибуты модулей, поддерживаемые Erlang, но также можно использовать пользовательские атрибуты:

defmodule MyServer do
  @my_data 13
  IO.inspect(@my_data)
  #=> 13
end

В отличие от Erlang, такие атрибуты по умолчанию не хранятся в модуле, так как в Elixir часто используются пользовательские атрибуты для хранения временных данных, доступных на этапе компиляции. Пользовательские атрибуты можно настроить, чтобы они вели себя более похоже на Erlang, используя Module.register_attribute/3.

Префикс атрибутов модуля

Библиотеки и фреймворки должны использовать префикс подчеркивания для атрибутов модуля, предназначенных для внутреннего использования, например @_my_data, чтобы средства автодополнения кода не отображали их в подсказках и запросах.

Наконец, обратите внимание, что атрибуты также можно читать внутри функций:

defmodule MyServer do
  @my_data 11
  def first_data, do: @my_data
  @my_data 13
  def second_data, do: @my_data
end

MyServer.first_data()
#=> 11

MyServer.second_data()
#=> 13

Важно отметить, что чтение атрибута создаёт моментальную копию его текущего значения. Другими словами, значение считывается во время компиляции, а не во время выполнения. Обратитесь к модулю Module для получения других функций управления атрибутами модулей.

Внимание! Несколько ссылок на один и тот же атрибут

Как упоминалось выше, каждый раз при чтении атрибута модуля делается моментальная копия его текущего значения. Поэтому, если вы храните большие значения в атрибутах модуля (например, встраиваете внешние файлы в атрибуты модуля), следует избегать многократных ссылок на один и тот же атрибут. Например, не делайте так:

@files %{
  example1: File.read!("lib/example1.data"),
  example2: File.read!("lib/example2.data")
}

def example1, do: @files[:example1]
def example2, do: @files[:example2]

В приведенном примере каждая ссылка на @files может привести к полной и независимой копии всего атрибута модуля @files. Вместо этого сделайте ссылку на атрибут модуля один раз в частной функции:

@files %{
  example1: File.read!("lib/example1.data"),
  example2: File.read!("lib/example2.data")
}

defp files(), do: @files
def example1, do: files()[:example1]
def example2, do: files()[:example2]

Внимание! Зависимости от компиляции

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

Например, рассмотрите этот распространенный шаблон:

@values [:foo, :bar, :baz]

def handle_arg(arg) when arg in @values do
  ...
end

Хотя приведенный выше пример корректен, представьте, что у вас есть фактические имена модулей в атрибуте модуля, как в этом примере:

@values [Foo, Bar, Baz]

def handle_arg(arg) when arg in @values do
  ...
end

Приведенный выше код определит зависимость от компиляции от модулей Foo, Bar, и Baz, таким образом, что при изменении любого из них текущий модуль должен будет перекомпилироваться. В таких случаях может быть предпочтительнее вообще отказаться от использования атрибута модуля:

def handle_arg(arg) when arg in [Foo, Bar, Baz] do
  ...
end

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

См. Kernel.SpecialForms.quote/2 для получения дополнительной информации.

@spec apply((... -> any()), [any()]) :: any()

Вызывает данную анонимную функцию fun со списком аргументов args.

Если количество аргументов известно на этапе компиляции, предпочтительнее использовать fun.(arg_1, arg_2, ..., arg_n), так как оно понятнее, чем apply(fun, [arg_1, arg_2, ..., arg_n]).

Встраивается компилятором.

Примеры

iex> apply(fn x -> x * 2 end, [2])
4

@spec apply(module(), function_name :: atom(), [any()]) :: any()

Вызывает указанную функцию из module со списком аргументов args.

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

Если количество аргументов и имя функции известны на этапе компиляции, предпочтительнее использовать module.function(arg_1, arg_2, ..., arg_n), так как оно понятнее, чем apply(module, :function, [arg_1, arg_2, ..., arg_n]).

apply/3 не может использоваться для вызова закрытых функций.

Встраивается компилятором.

Примеры

iex> apply(Enum, :reverse, [[1, 2, 3]])
[3, 2, 1]

Возвращает двоичную строку от смещения, заданного началом диапазона, до смещения, заданного концом диапазона.

Если начало или конец диапазона отрицательны, они преобразуются в положительные индексы на основе размера двоичной строки. Например, -1 означает последний байт двоичной строки.

Это аналогично binary_part/3, за исключением того, что оно работает с диапазонами и его нельзя использовать в защитах.

Функция работает с байтами. Для операции среза, учитывающей символы, см. String.slice/2.

Примеры

iex> binary_slice("elixir", 0..5)
"elixir"
iex> binary_slice("elixir", 1..3)
"lix"
iex> binary_slice("elixir", 1..10)
"lixir"

iex> binary_slice("elixir", -4..-1)
"ixir"
iex> binary_slice("elixir", -4..6)
"ixir"
iex> binary_slice("elixir", -10..10)
"elixir"

Для диапазонов, где start > stop, необходимо явно указать их как возрастающие:

iex> binary_slice("elixir", 2..-1//1)
"ixir"
iex> binary_slice("elixir", 1..-2//1)
"lixi"

Можно использовать ../0 как сокращение для 0..-1//1, что возвращает всю двоичную строку как есть:

iex> binary_slice("elixir", ..)
"elixir"

Шаг может быть любым положительным числом. Например, чтобы получить каждый второй символ двоичной строки:

iex> binary_slice("elixir", 0..-1//2)
"eii"

Если первая позиция находится после конца строки или после последней позиции диапазона, возвращается пустая строка:

iex> binary_slice("elixir", 10..3//1)
""
iex> binary_slice("elixir", -10..-7)
""
iex> binary_slice("a", 1..1500)
""

Возвращает двоичную строку, начинающуюся со смещения start и заданного size.

Это аналогично binary_part/3, за исключением того, что если start + size больше размера двоичной строки, она автоматически усекается до размера двоичной строки вместо вывода исключения. В отличие от binary_part/3, эта функция недопустима в защитах.

Функция работает с байтами. Для операции среза, учитывающей символы, см. String.slice/3.

Примеры

iex> binary_slice("elixir", 0, 6)
"elixir"
iex> binary_slice("elixir", 0, 5)
"elixi"
iex> binary_slice("elixir", 1, 4)
"lixi"
iex> binary_slice("elixir", 0, 10)
"elixir"

Если start отрицательное, оно нормализуется относительно размера двоичной строки и приводится к 0:

iex> binary_slice("elixir", -3, 10)
"xir"
iex> binary_slice("elixir", -10, 10)
"elixir"

Если size равно нулю, возвращается пустая двоичная строка:

iex> binary_slice("elixir", 1, 0)
""

Если start больше или равно размеру двоичной строки, возвращается пустая двоичная строка:

iex> binary_slice("elixir", 10, 10)
""

Возвращает связывание для данного контекста в виде списка ключевых слов.

В возвращаемом результате ключи — имена переменных, а значения — соответствующие значения переменных.

Если заданный context равен nil (по умолчанию), возвращается связывание для текущего контекста.

Примеры

iex> x = 1
iex> binding()
[x: 1]
iex> x = 2
iex> binding()
[x: 2]

iex> binding(:foo)
[]
iex> var!(x, :foo) = 1
1
iex> binding(:foo)
[x: 1]

Отлаживает заданный code.

dbg/2 может использоваться для отладки заданного code с помощью настраиваемой функции отладки. Возвращает результат заданного кода.

Примеры

Рассмотрим этот вызов dbg/2:

dbg(Atom.to_string(:debugging))
#=> "debugging"

Возвращает строку "debugging", которая является результатом вызова Atom.to_string/1. Кроме того, вышеприведённый вызов выводит:

[my_file.ex:10: MyMod.my_fun/0]
Atom.to_string(:debugging) #=> "debugging"

По умолчанию функция отладки печатает дополнительную отладочную информацию при работе с конвейерами. Она печатает значения на каждом «шаге» конвейера.

"Elixir is cool!"
|> String.trim_trailing("!")
|> String.split()
|> List.first()
|> dbg()
#=> "Elixir"

Приведённый выше код выводит:

[my_file.ex:10: MyMod.my_fun/0]
"Elixir is cool!" #=> "Elixir is cool!"
|> String.trim_trailing("!") #=> "Elixir is cool"
|> String.split() #=> ["Elixir", "is", "cool"]
|> List.first() #=> "Elixir"

Без аргументов dbg() отлаживает информацию о текущей области видимости. См. binding/1.

dbg в IEx

Вы можете включить IEx для замены dbg на его бэкенд IEx.pry/0 вызовом:

$ iex --dbg pry

В таких случаях dbg запустит сеанс pry, где вы можете взаимодействовать с импортами, псевдонимами и переменными текущей среды в месте вызова dbg.

Если вы вызываете dbg в конце конвейера (используя |> ) в IEx, вы сможете проходить по каждому шагу конвейера по одному, вводя «next» (или «n»).

Обратите внимание dbg поддерживает пошаговое выполнение только для конвейеров (то есть, он может выполнить только тот код, который видит). Для общего пошагового выполнения вы можете установить точки останова с помощью IEx.break!/4.

Для получения дополнительной информации см. документацию IEx по адресу IEx documentation.

Настройка функции отладки

Одно из преимуществ dbg/2 заключается в том, что её логика отладки настраиваема, что позволяет инструментам расширять dbg с расширенным поведением. Это делается, например, IEx, который расширяет dbg с интерактивной оболочкой, где вы можете напрямую инспектировать и получать доступ к значениям.

Функцию отладки можно настроить во время компиляции через ключ :dbg_callback приложения :elixir. Функция отладки должна быть кортежем {module, function, args}. Функция function в module будет вызываться с тремя аргументами, добавляемыми к args:

1. AST заданного code
2. AST заданного options
3. Среда Macro.Env окружения, где вызывается dbg/2

Функция отладки вызывается во время компиляции и должна также возвращать AST. Ожидается, что AST в конечном итоге вернёт результат оценки отлаживаемого выражения.

Вот простой пример:

defmodule MyMod do
  def debug_fun(code, options, caller, device) do
    quote do
      result = unquote(code)
      IO.inspect(unquote(device), result, label: unquote(Macro.to_string(code)))
    end
  end
end

Для настройки функции отладки:

# In config/config.exs
config :elixir, :dbg_callback, {MyMod, :debug_fun, [:stdio]}

Функция отладки по умолчанию

По умолчанию функция отладки, которую мы используем, это Macro.dbg/3. Она просто выводит информацию о коде в стандартный вывод и возвращает значение, возвращаемое оценкой code. options используются для управления тем, как интерпретируются термины. Это те же параметры, которые принимаются inspect/2.

Определяет публичную функцию с заданным именем и телом.

Примеры

defmodule Foo do
  def bar, do: :baz
end

Foo.bar()
#=> :baz

Функция, которая ожидает аргументы, может быть определена следующим образом:

defmodule Foo do
  def sum(a, b) do
    a + b
  end
end

В приведённом выше примере определена функция sum/2, которая принимает два аргумента и возвращает их сумму.

Аргументы по умолчанию

\\ используется для указания значения по умолчанию для параметра функции. Например:

defmodule MyMath do
  def multiply_by(number, factor \\ 2) do
    number * factor
  end
end

MyMath.multiply_by(4, 3)
#=> 12

MyMath.multiply_by(4)
#=> 8

Компилятор преобразует это в несколько функций с различной арностью, здесь MyMath.multiply_by/1 и MyMath.multiply_by/2, которые представляют случаи, когда аргументы для параметров со значениями по умолчанию передаются или нет.

При определении функции с аргументами по умолчанию и несколькими явно объявленными разделами, вы должны написать заголовок функции, который объявляет значения по умолчанию. Например:

defmodule MyString do
  def join(string1, string2 \\ nil, separator \\ " ")

  def join(string1, nil, _separator) do
    string1
  end

  def join(string1, string2, separator) do
    string1 <> separator <> string2
  end
end

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

Списки ключевых слов с аргументами по умолчанию

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

defmodule MyConfiguration do
  @default_opts [storage: "local"]

  def configure(resource, opts \\ []) do
    opts = Keyword.merge(@default_opts, opts)
    storage = opts[:storage]
    # ...
  end
end

Разница между использованием Map и Keyword для хранения множества аргументов заключается в ключах Keyword:

• должны быть атомами
• могут быть указаны несколько раз
• упорядочены, как указано разработчиком

Имена функций и переменных

Имена функций и переменных имеют следующий синтаксис: строчная буква ASCII или подчёркивание, за которыми следует любое количество строчных или прописных букв ASCII, цифр или подчёркиваний. Дополнительно они могут заканчиваться знаком восклицания или вопросительным знаком.

Для переменных любой идентификатор, начинающийся с подчёркивания, должен указывать на неиспользуемую переменную. Например:

def foo(bar) do
  []
end
#=> warning: variable bar is unused

def foo(_bar) do
  []
end
#=> no warning

def foo(_bar) do
  _bar
end
#=> warning: the underscored variable "_bar" is used after being set

rescue/catch/after/else

Тела функций поддерживают rescue, catch, after, и else как и Kernel.SpecialForms.try/1 (известный как «явный try»). Например, следующие две функции эквивалентны:

def convert(number) do
  try do
    String.to_integer(number)
  rescue
    e in ArgumentError -> {:error, e.message}
  end
end

def convert(number) do
  String.to_integer(number)
rescue
  e in ArgumentError -> {:error, e.message}
end

Определяет функцию, которая делегирует выполнение другой модули.

Функции, определённые с помощью defdelegate/2, являются публичными и могут быть вызваны извне модуля, в котором они определены, как если бы они были определены с помощью def/2. Поэтому defdelegate/2 относится к расширению публичного API текущего модуля. Если вы хотите вызвать функцию, определённую в другом модуле, не используя его полное имя модуля, используйте alias/2 для сокращения имени модуля или используйте import/2, чтобы вы могли вызвать функцию без имени модуля.

Делегирование работает только с функциями; делегирование макросов не поддерживается.

См. def/2 для правил именования и аргументов по умолчанию.

Параметры

• :to - модуль, которому будет делегировано выполнение.

• :as - функция, которая будет вызвана на целевом модуле, указанном в :to. Этот параметр необязателен и по умолчанию равен имени делегируемой функции (funs).

Примеры

defmodule MyList do
  defdelegate reverse(list), to: Enum
  defdelegate other_reverse(list), to: Enum, as: :reverse
end

MyList.reverse([1, 2, 3])
#=> [3, 2, 1]

MyList.other_reverse([1, 2, 3])
#=> [3, 2, 1]

Определяет исключение.

Исключения являются структурами, поддерживаемыми модулем, который реализует поведение Exception. Поведение Exception требует реализации двух функций:

• exception/1 - получает аргументы, переданные в raise/2, и возвращает структуру исключения. Реализация по умолчанию принимает либо набор ключевых аргументов, который сливается в структуру, либо строку, которая используется в качестве сообщения исключения.

• message/1 - получает структуру исключения и должна вернуть её сообщение. Чаще всего исключения имеют поле message, к которому по умолчанию обращается эта функция. Однако, если исключение не имеет поля message, эта функция должна быть реализована явно.

Поскольку исключения являются структурами, API, поддерживаемый defstruct/1, также доступен в defexception/1.

Выбрасывание исключений

Наиболее распространённый способ выброса исключения — использование raise/2:

defmodule MyAppError do
  defexception [:message]
end

value = [:hello]

raise MyAppError,
  message: "did not get what was expected, got: #{inspect(value)}"

Во многих случаях удобнее передать ожидаемое значение в raise/2 и сгенерировать сообщение в обратном вызове Exception.exception/1:

defmodule MyAppError do
  defexception [:message]

  @impl true
  def exception(value) do
    msg = "did not get what was expected, got: #{inspect(value)}"
    %MyAppError{message: msg}
  end
end

raise MyAppError, value

Приведённый выше пример демонстрирует предпочтительный способ настройки сообщений об исключениях.

@spec defguard(Macro.t()) :: Macro.t()

Генерирует макрос, подходящий для использования в выражениях фильтров.

Вызывает ошибку во время компиляции, если определение использует выражения, которые недопустимы в фильтрах, а в противном случае создает макрос, который можно использовать как внутри, так и вне фильтров.

Обратите внимание на соглашение в Elixir: все фильтры, возвращающие булево значение, должны предваряться префиксом is_, например, is_list/1. Однако, если функция/макрос возвращает булево значение, но не допускается в фильтрах, он не должен иметь префикса и заканчиваться вопросительным знаком, например, Keyword.keyword?/1.

Пример

defmodule Integer.Guards do
  defguard is_even(value) when is_integer(value) and rem(value, 2) == 0
end

defmodule Collatz do
  @moduledoc "Tools for working with the Collatz sequence."
  import Integer.Guards

  @doc "Determines the number of steps `n` takes to reach `1`."
  # If this function never converges, please let me know what `n` you used.
  def converge(n) when n > 0, do: step(n, 0)

  defp step(1, step_count) do
    step_count
  end

  defp step(n, step_count) when is_even(n) do
    step(div(n, 2), step_count + 1)
  end

  defp step(n, step_count) do
    step(3 * n + 1, step_count + 1)
  end
end

@spec defguardp(Macro.t()) :: Macro.t()

Генерирует частный макрос, подходящий для использования в выражениях фильтров.

Вызывает ошибку во время компиляции, если определение использует выражения, которые недопустимы в фильтрах, а в противном случае создает частный макрос, который можно использовать как внутри, так и вне фильтров в текущем модуле.

Аналогично defmacrop/2, defguardp/1 должен быть определен до его использования в текущем модуле.

Определяет реализацию для данного протокола.

См. модуль Protocol для получения дополнительной информации.

Определяет публичный макрос с заданным именем и телом.

Макросы должны быть определены перед их использованием.

См. def/2 для правил именования и аргументов по умолчанию.

Примеры

defmodule MyLogic do
  defmacro unless(expr, opts) do
    quote do
      if !unquote(expr), unquote(opts)
    end
  end
end

require MyLogic

MyLogic.unless false do
  IO.puts("It works")
end

Определяет частный макрос с заданным именем и телом.

Частные макросы доступны только из того же модуля, в котором они определены.

Частные макросы должны быть определены перед их использованием.

См. defmacro/2 для получения дополнительной информации и def/2 для правил именования и аргументов по умолчанию.

Определяет модуль с заданным именем и содержимым.

Этот макрос определяет модуль с заданным alias в качестве имени и с заданным содержимым. Он возвращает кортеж из четырёх элементов:

• :module
• имя модуля
• бинарное содержимое модуля
• результат вычисления блока содержимого

Примеры

defmodule Number do
  def one, do: 1
  def two, do: 2
end
#=> {:module, Number, <<70, 79, 82, ...>>, {:two, 0}}

Number.one()
#=> 1

Number.two()
#=> 2

Вложенность

Вложенность модуля внутри другого модуля влияет на имя вложенного модуля:

defmodule Foo do
  defmodule Bar do
  end
end

В примере выше создаются два модуля - Foo и Foo.Bar. При вложенности Elixir автоматически создаёт псевдоним для внутреннего модуля, позволяя обратиться ко второму модулю Foo.Bar как к Bar в той же лексической области, где он определен (в модуле Foo). Это происходит только если вложенный модуль определяется через псевдоним.

Если модуль Foo.Bar перемещен в другое место, ссылки на Bar в модуле Foo нужно обновить на полное имя (Foo.Bar) или установить псевдоним явно в модуле Foo с помощью Kernel.SpecialForms.alias/2.

defmodule Foo.Bar do
  # code
end

defmodule Foo do
  alias Foo.Bar
  # code here can refer to "Foo.Bar" as just "Bar"
end

Динамические имена

Имена модулей в Elixir могут быть сгенерированы динамически. Это очень полезно при работе с макросами. Например, можно написать:

defmodule String.to_atom("Foo#{1}") do
  # contents ...
end

Elixir примет любое имя модуля, если выражение, переданное в качестве первого аргумента к defmodule/2, вычисляется в атом. Обратите внимание, что при использовании динамического имени Elixir не будет вкладывать имя в текущий модуль и автоматически устанавливать псевдоним.

Зарезервированные имена модулей

Если вы попытаетесь определить модуль, который уже существует, вы получите предупреждение о том, что модуль был переопределён.

Существуют некоторые модули, которые Elixir пока не реализует, но возможно будут реализованы в будущем. Эти модули зарезервированы, и их определение приведёт к ошибке компиляции:

defmodule Any do
  # code
end
** (CompileError) iex:1: module Any is reserved and cannot be defined

Elixir зарезервировал следующие имена модулей: Elixir, Any, BitString, PID, и Reference.

Делает заданные определения в текущем модуле переопределяемыми.

Если пользователь определяет новую функцию или макрос с тем же именем и арностью, то переопределяемые определения отбрасываются. В противном случае используются исходные определения.

Возможна ситуация, когда переопределённое определение имеет другой уровень видимости, чем исходное: публичная функция может быть переопределена частной функцией и наоборот.

Макросы не могут быть переопределены как функции, и наоборот.

Пример

defmodule DefaultMod do
  defmacro __using__(_opts) do
    quote do
      def test(x, y) do
        x + y
      end

      defoverridable test: 2
    end
  end
end

defmodule ChildMod do
  use DefaultMod

  def test(x, y) do
    x * y + super(x, y)
  end
end

Как видно из примера выше, super можно использовать для вызова реализации по умолчанию.

Предупреждение

Используйте defoverridable с осторожностью. Если вам нужно определить несколько модулей с одинаковым поведением, может быть лучше перенести реализацию по умолчанию к вызывающему модулю и проверить, существует ли обратный вызов с помощью Code.ensure_loaded?/1 и function_exported?/3.

Например, в примере выше, представьте, что есть модуль, который вызывает функцию test/2. Этот модуль может быть определен следующим образом:

defmodule CallsTest do
  def receives_module_and_calls_test(module, x, y) do
    if Code.ensure_loaded?(module) and function_exported?(module, :test, 2) do
      module.test(x, y)
    else
      x + y
    end
  end
end

Пример с поведением

Вы также можете передать поведение в defoverridable и это пометит все обратные вызовы в поведении как переопределяемые:

defmodule Behaviour do
  @callback test(number(), number()) :: number()
end

defmodule DefaultMod do
  defmacro __using__(_opts) do
    quote do
      @behaviour Behaviour

      def test(x, y) do
        x + y
      end

      defoverridable Behaviour
    end
  end
end

defmodule ChildMod do
  use DefaultMod

  def test(x, y) do
    x * y + super(x, y)
  end
end

Определяет частную функцию с заданным именем и телом.

Частные функции доступны только изнутри модуля, в котором они определены. Попытка доступа к частной функции извне модуля, в котором она определена, приводит к исключению UndefinedFunctionError.

См. def/2 для получения дополнительной информации.

Примеры

defmodule Foo do
  def bar do
    sum(1, 2)
  end

  defp sum(a, b), do: a + b
end

Foo.bar()
#=> 3

Foo.sum(1, 2)
** (UndefinedFunctionError) undefined function Foo.sum/2

Определяет протокол.

См. модуль Protocol для получения дополнительной информации.

Определяет структуру.

Структура — это помеченная карта, которая позволяет разработчикам предоставлять значения по умолчанию для ключей, метки для использования в полиморфных диспатчах и утверждениях на этапе компиляции. Дополнительную информацию о структурах можно найти на странице Kernel.SpecialForms.%/2.

Определение структуры возможно только в пределах одного модуля, так как структура связана с самим модулем. Вызов defstruct/1 также определяет функцию __struct__/0, которая возвращает саму структуру.

Примеры

defmodule User do
  defstruct name: nil, age: nil
end

Поля структуры оцениваются на этапе компиляции, что позволяет им быть динамическими. В примере ниже 10 + 11 оценивается на этапе компиляции, и поле age хранится со значением 21:

defmodule User do
  defstruct name: nil, age: 10 + 11
end

Аргумент fields обычно представляет собой список ключевых слов со именами полей в качестве атомарных ключей и значениями по умолчанию в качестве соответствующих значений. defstruct/1 также поддерживает список атомов в качестве аргумента: в этом случае атомы в списке будут использоваться в качестве имён полей структуры, и все они будут иметь значение по умолчанию nil.

defmodule Post do
  defstruct [:title, :content, :author]
end

Добавьте документацию к структуре с помощью атрибута @doc аналогично функциям.

defmodule Post do
  @doc "A post. The content should be valid Markdown."
  defstruct [:title, :content, :author]
end

Наследование

Хотя структуры являются картами, по умолчанию структуры не реализуют ни один из протоколов, реализованных для карт. Например, попытка использовать протокол со структурой User приводит к ошибке:

john = %User{name: "John"}
MyProtocol.call(john)
** (Protocol.UndefinedError) protocol MyProtocol not implemented for %User{...}

defstruct/1, однако, позволяет реализовывать протоколы наследованием. Это можно сделать, определив атрибут @derive в виде списка перед вызовом defstruct/1:

defmodule User do
  @derive MyProtocol
  defstruct name: nil, age: nil
end

MyProtocol.call(john) # it works!

Частый пример — наследование Inspect протокола, чтобы скрыть определённые поля при выводе структуры:

defmodule User do
  @derive {Inspect, only: :name}
  defstruct name: nil, age: nil
end

Для каждого протокола в @derive, Elixir проверит, реализован ли протокол для Any. Если реализация Any определяет обратный вызов __deriving__/3, этот обратный вызов будет вызван, и он должен определить модуль реализации. В противном случае реализация, которая просто ссылается на реализацию Any, будет автоматически получена. Дополнительную информацию об обратном вызове __deriving__/3 можно найти по адресу Protocol.derive/3.

Выполнение проверок ключей

При создании структуры Elixir автоматически гарантирует, что все ключи принадлежат структуре:

%User{name: "john", unknown: :key}
** (KeyError) key :unknown not found in: %User{age: 21, name: nil}

Elixir также позволяет разработчикам обеспечить, что определённые ключи всегда должны быть предоставлены при создании структуры:

defmodule User do
  @enforce_keys [:name]
  defstruct name: nil, age: 10 + 11
end

Теперь попытка создать структуру без ключа name завершится ошибкой:

%User{age: 21}
** (ArgumentError) the following keys must also be given when building struct User: [:name]

Обратите внимание, что @enforce_keys — это просто гарантия на этапе компиляции, которая помогает разработчикам при создании структур. Она не применяется к обновлениям и не обеспечивает никакой проверки значений.

Типы

Рекомендуется определять типы для структур. По соглашению такой тип называется t. Чтобы определить структуру внутри типа, используется синтаксис литерала структуры:

defmodule User do
  defstruct name: "John", age: 25
  @type t :: %__MODULE__{name: String.t(), age: non_neg_integer}
end

Рекомендуется использовать синтаксис структуры только при определении типа структуры. При ссылке на другую структуру лучше использовать User.t() вместо %User{}.

Типы полей структуры, которые не включены в %User{}, по умолчанию принимают тип term() (см. term/0).

Структуры, внутренняя структура которых является частной для локального модуля (сопоставление с образцом или прямой доступ к полям не должен быть разрешён), должны использовать атрибут @opaque. Структуры, внутренняя структура которых является общедоступной, должны использовать атрибут @type.

Распаковывает два списка, присваивая каждый элемент в правом списке соответствующему элементу в левом списке.

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

Примеры

iex> destructure([x, y, z], [1, 2, 3, 4, 5])
iex> {x, y, z}
{1, 2, 3}

В примере выше, даже если правый список содержит больше элементов, чем левый, распаковка работает нормально. Если правый список меньше, оставшиеся элементы просто устанавливаются в nil:

iex> destructure([x, y, z], [1])
iex> {x, y, z}
{1, nil, nil}

Левая часть поддерживает любые выражения, которые можно использовать в левой части сопоставления:

x = 1
destructure([^x, y, z], [1, 2, 3])

Приведенный выше пример будет работать только в том случае, если x совпадает с первым значением в правом списке. В противном случае будет вызвана ошибка MatchError (как и оператор =).

@spec exit(term()) :: no_return()

Останавливает выполнение вызывающего процесса с заданным причиной.

Поскольку оценка этой функции приводит к завершению процесса, она не имеет значения возврата.

Встроена компилятором.

Примеры

При завершении процесса по умолчанию он завершается с причиной :normal. Вы также можете явно вызвать exit/1, если хотите завершить процесс, но не сигнализировать об ошибке:

exit(:normal)

В случае возникновения проблем, вы также можете использовать exit/1 с другой причиной:

exit(:seems_bad)

Если причина выхода не :normal, все процессы, связанные с завершившимся процессом, завершатся с ошибкой (если они не отлавливают выходы).

Выходы OTP

Выходы используются OTP для определения, завершился ли процесс аномально или нет. Следующие выходы считаются "нормальными":

• exit(:normal)
• exit(:shutdown)
• exit({:shutdown, term})

Выход с любой другой причиной считается аномальным и обрабатывается как ошибка. Это означает, что срабатывает поведение по умолчанию для менеджера ошибок, выводится сообщение об ошибке и так далее.

На этом поведении основаны многие разные места. Например, ExUnit использует exit(:shutdown) при выходе процесса тестирования, чтобы сигнализировать связанным процессам, деревьям управления и так далее о вежливом завершении.

Выходы CLI

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

Тем не менее, возможно настроить сигнал выхода операционной системы, вызвав:

exit({:shutdown, integer})

Это заставит процесс операционной системы завершиться со статусом, указанным integer, в то же время сигнализируя всем связанным процессам Erlang о вежливом завершении.

Любая другая причина выхода приведет к завершению процесса операционной системы со статусом 1 и к завершению связанных процессов Erlang с ошибкой.

@spec function_exported?(module(), atom(), arity()) :: boolean()

Возвращает true, если модуль module загружен и содержит общедоступную функцию function с заданным arity, в противном случае false.

Обратите внимание, что эта функция не загружает модуль в случае, если он не загружен. Дополнительную информацию см. в Code.ensure_loaded/1.

Встроена компилятором.

Примеры

iex> function_exported?(Enum, :map, 2)
true

iex> function_exported?(Enum, :map, 10)
false

iex> function_exported?(List, :to_string, 1)
true

Получает значение и обновляет вложенную структуру данных с помощью заданной path.

Это аналогично get_and_update_in/3, за исключением того, что путь извлекается с помощью макроса, а не путём передачи списка. Например:

get_and_update_in(opts[:foo][:bar], &{&1, &1 + 1})

Эквивалентно:

get_and_update_in(opts, [:foo, :bar], &{&1, &1 + 1})

Это также работает со вложенными структурами и способом указания путей struct.path.to.value:

get_and_update_in(struct.foo.bar, &{&1, &1 + 1})

Обратите внимание, что для работы этого макроса весь путь должен быть виден этому макросу. Смотрите раздел "Пути" ниже.

Примеры

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> get_and_update_in(users["john"].age, &{&1, &1 + 1})
{27, %{"john" => %{age: 28}, "meg" => %{age: 23}}}

Пути

Путь может начинаться с переменной, локального или удалённого вызова и должен быть продолжен одним или несколькими:

• foo[bar] - обращается к ключу bar в foo; в случае, если foo является пустым, возвращается nil

• foo.bar - обращается к полю карты/структуры; в случае, если поле отсутствует, возникает ошибка

Вот некоторые допустимые пути:

users["john"][:age]
users["john"].age
User.all()["john"].age
all_users()["john"].age

Вот некоторые недопустимые пути:

# Does a remote call after the initial value
users["john"].do_something(arg1, arg2)

# Does not access any key or field
users

@spec get_and_update_in(
  structure,
  keys,
  (term() | nil -> {current_value, new_value} | :pop)
) :: {current_value, new_structure :: structure}
when structure: Access.t(),
     keys: [any(), ...],
     current_value: Access.value(),
     new_value: Access.value()

Получает значение и обновляет вложенную структуру.

data — это вложенная структура (то есть, карта, список ключевых слов или структура, которая реализует поведение Access).

Аргумент fun получает значение key (или nil, если key отсутствует) и должен вернуть одно из следующих значений:

• двухэлементная кортеж {current_value, new_value}. В этом случае, current_value — это извлечённое значение, которое можно обработать перед возвратом. new_value — это новое значение, которое будет сохранено под key.

• :pop, что подразумевает удаление текущего значения под key из структуры и возврат этого значения.

Эта функция использует модуль Access для обхода структур в соответствии с заданными keys, если key не является функцией, что подробно описано в последующем разделе.

Примеры

Эта функция полезна, когда требуется получить текущее значение (или что-то вычисленное на основе текущего значения) и обновить его одновременно. Например, она может использоваться для чтения текущего возраста пользователя и увеличения его на единицу за один проход:

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> get_and_update_in(users, ["john", :age], &{&1, &1 + 1})
{27, %{"john" => %{age: 28}, "meg" => %{age: 23}}}

Обратите внимание, что текущее значение, переданное анонимной функции, может быть nil. Если любое из промежуточных значений равно nil, будет вызвано исключение:

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> get_and_update_in(users, ["jane", :age], &{&1, &1 + 1})
** (ArgumentError) could not put/update key :age on a nil value

Функции в качестве ключей

Если ключ — функция, функция будет вызвана с тремя аргументами:

• операция (:get_and_update)
• данные для доступа
• функция, которая будет вызвана далее

Это означает, что get_and_update_in/3 можно расширить для предоставления настраиваемых поисков. Недостатком является то, что функции не могут храниться в качестве ключей в доступных структурах данных.

Когда один из ключей — функция, функция вызывается. В примере ниже мы используем функцию для получения и увеличения всех возрастов в списке:

iex> users = [%{name: "john", age: 27}, %{name: "meg", age: 23}]
iex> all = fn :get_and_update, data, next ->
...>   data |> Enum.map(next) |> Enum.unzip()
...> end
iex> get_and_update_in(users, [all, :age], &{&1, &1 + 1})
{[27, 23], [%{name: "john", age: 28}, %{name: "meg", age: 24}]}

Если предыдущее значение перед вызовом функции было nil, функция будет получать nil в качестве значения и должна обрабатывать это соответствующим образом (будь то ошибка или разумный стандартный ответ).

Модуль Access поставляется со многими удобными функциями доступа, такими как анонимная функция all , определённая выше. См. Access.all/0, Access.key/2 и другие в качестве примеров.

@spec get_in(Access.t(), [term(), ...]) :: term()

Получает значение из вложенной структуры.

Использует модуль Access для обхода структур в соответствии с заданными keys, если key не является функцией, что подробно описано в последующем разделе.

Обратите внимание, что если ни один из заданных ключей не является функцией, редко бывает причина использовать get_in вместо написания обычного кода Elixir с использованием [].

Примеры

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> get_in(users, ["john", :age])
27
iex> # Equivalent to:
iex> users["john"][:age]
27

get_in/2 также может использовать средства доступа в модуле Access для обхода более сложных структур данных. Например, здесь мы используем Access.all/0 для обхода списка:

iex> users = [%{name: "john", age: 27}, %{name: "meg", age: 23}]
iex> get_in(users, [Access.all(), :age])
[27, 23]

В случае, если любой из компонентов возвращает nil, nil будет возвращено, и get_in/2 не будет продолжать обход:

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> get_in(users, ["unknown", :age])
nil
iex> # Equivalent to:
iex> users["unknown"][:age]
nil

iex> users = nil
iex> get_in(users, [Access.all(), :age])
nil

В качестве альтернативы, если вам нужно получить доступ к сложным структурам данных, вы можете использовать сопоставление с образцом:

case users do
  %{"john" => %{age: age}} -> age
  _ -> default_value
end

Функции в качестве ключей

Если ключ, переданный get_in/2, является функцией, функция будет вызвана с тремя аргументами:

• операция (:get)
• данные для доступа
• функция, которая будет вызвана далее

Это означает, что get_in/2 можно расширить для предоставления настраиваемых поисков. Именно так и работает ключ Access.all/0 в предыдущем разделе. Например, мы можем вручную реализовать такой обход следующим образом:

iex> users = [%{name: "john", age: 27}, %{name: "meg", age: 23}]
iex> all = fn :get, data, next -> Enum.map(data, next) end
iex> get_in(users, [all, :age])
[27, 23]

Модуль Access поставляется со многими удобными функциями доступа. См. Access.all/0, Access.key/2 и другие в качестве примеров.

Работа со структурами

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

get_in(some_struct, [:some_key, :nested_key])

Хорошая новость заключается в том, что структуры имеют предопределённую форму. Поэтому вы можете написать вместо этого:

some_struct.some_key.nested_key

Если some_key может вернуть nil, вы всегда можете перейти к сопоставлению с образцом, чтобы обеспечить обработку вложенных структур:

case some_struct do
  %{some_key: %{nested_key: value}} -> value
  %{} -> nil
end

Предоставляет макрос if/2.

Этот макрос ожидает, что первый аргумент будет условием, а второй — списком ключевых слов.

Примеры однострочных выражений

if(foo, do: bar)

В примере выше, bar будет возвращено, если foo вычисляется как истинное значение (ни false ни nil). В противном случае, будет возвращено nil.

Можно указать опцию else, чтобы указать обратное:

if(foo, do: bar, else: baz)

Примеры блоков

Также можно передать блок в макрос if/2. Первый пример выше будет переведён в:

if foo do
  bar
end

Обратите внимание, что do-end становятся разделителями. Второй пример будет переведён в:

if foo do
  bar
else
  baz
end

Для сравнения более двух пунктов необходимо использовать макрос cond/1.

@spec inspect(
  Inspect.t(),
  keyword()
) :: String.t()

Проверяет переданный аргумент согласно протоколу Inspect. Второй аргумент — список ключевых слов с параметрами для управления проверкой.

Параметры

inspect/2 принимает список параметров, которые интерпретируются внутри в структуру Inspect.Opts. Проверьте документацию Inspect.Opts, чтобы увидеть поддерживаемые параметры.

Примеры

iex> inspect(:foo)
":foo"

iex> inspect([1, 2, 3, 4, 5], limit: 3)
"[1, 2, 3, ...]"

iex> inspect([1, 2, 3], pretty: true, width: 0)
"[1,\n 2,\n 3]"

iex> inspect("olá" <> <<0>>)
"<<111, 108, 195, 161, 0>>"

iex> inspect("olá" <> <<0>>, binaries: :as_strings)
"\"olá\\0\""

iex> inspect("olá", binaries: :as_binaries)
"<<111, 108, 195, 161>>"

iex> inspect(~c"bar")
"~c\"bar\""

iex> inspect([0 | ~c"bar"])
"[0, 98, 97, 114]"

iex> inspect(100, base: :octal)
"0o144"

iex> inspect(100, base: :hex)
"0x64"

Обратите внимание, что протокол Inspect необязательно возвращает допустимое представление термина Elixir. В таких случаях возвращаемое значение проверки должно начинаться с #. Например, проверка функции вернёт:

inspect(fn a, b -> a + b end)
#=> #Function<...>

Протокол Inspect может быть выведен, чтобы скрыть определённые поля из структур, поэтому они не отображаются в журналах, результатах проверки и т. п. Подробнее см. раздел «Вывод» документации протокола Inspect.

@spec macro_exported?(module(), atom(), arity()) :: boolean()

Возвращает true, если module загружен и содержит общедоступный макрос macro с заданным arity, в противном случае false.

Обратите внимание, что эта функция не загружает модуль, если он не загружен. Дополнительную информацию см. в Code.ensure_loaded/1.

Если module является модулем Erlang (а не модулем Elixir), эта функция всегда возвращает false.

Примеры

iex> macro_exported?(Kernel, :use, 2)
true

iex> macro_exported?(:erlang, :abs, 1)
false

@spec make_ref() :: reference()

Возвращает почти уникальную ссылку.

Возвращённая ссылка будет повторяться примерно после 2^82 вызовов; поэтому она достаточно уникальна для практических целей.

Встроенная компилятором.

Примеры

make_ref()
#=> #Reference<0.0.0.135>

Удобный макрос, проверяющий, соответствует ли правая часть (выражение) левой части (шаблон).

Примеры

iex> match?(1, 1)
true

iex> match?({1, _}, {1, 2})
true

iex> map = %{a: 1, b: 2}
iex> match?(%{a: _}, map)
true

iex> a = 1
iex> match?(^a, 1)
true

match?/2 очень полезен при фильтрации или поиске значения в перечисляемом объекте:

iex> list = [a: 1, b: 2, a: 3]
iex> Enum.filter(list, &match?({:a, _}, &1))
[a: 1, a: 3]

Для соответствия также можно задать условия:

iex> list = [a: 1, b: 2, a: 3]
iex> Enum.filter(list, &match?({:a, x} when x < 2, &1))
[a: 1]

Переменные, присвоенные в соответствии, недоступны за пределами вызова функции (в отличие от обычного сопоставления с образцом с оператором =):

iex> match?(_x, 1)
true
iex> binding()
[]

Значения против шаблонов

Помните, что оператор привязки соответствует значениям, а не шаблонам. Передача переменной в качестве шаблона всегда вернёт true и вызовет предупреждение о том, что переменная не используется:

# don't do this
pattern = %{a: :a}
match?(pattern, %{b: :b})

Аналогично, перемещение выражения из шаблона может больше не сохранять его семантику. Например:

match?([_ | _], [1, 2, 3])
#=> true

pattern = [_ | _]
match?(pattern, [1, 2, 3])
** (CompileError) invalid use of _. _ can only be used inside patterns to ignore values and cannot be used in expressions. Make sure you are inside a pattern or change it accordingly

Ещё один пример: карта в качестве шаблона выполняет частичное соответствие, но не после присвоения переменной:

match?(%{x: 1}, %{x: 1, y: 2})
#=> true

attrs = %{x: 1}
match?(^attrs, %{x: 1, y: 2})
#=> false

Оператор привязки проверит, равны ли значения, используя ===/2, в то время как шаблоны имеют свои собственные правила при сопоставлении карт, списков и так далее. Такое поведение не специфично для match?/2. Следующий код также выбросит исключение:

attrs = %{x: 1}
^attrs = %{x: 1, y: 2}
#=> (MatchError) no match of right hand side value: %{x: 1, y: 2}

@spec max(first, second) :: first | second when first: term(), second: term()

Возвращает наибольшее из двух заданных терминов в соответствии с их структурным сравнением.

Если термины равны, возвращается первый.

Выполняет структурное сравнение, где все термины Elixir могут быть сравнены друг с другом. Дополнительную информацию см. в разделе "Структурное сравнение".

Встроено компилятором.

Примеры

iex> max(1, 2)
2
iex> max(:a, :b)
:b

@spec min(first, second) :: first | second when first: term(), second: term()

Возвращает наименьшее из двух заданных терминов в соответствии с их структурным сравнением.

Если термины равны, возвращается первый.

Выполняет структурное сравнение, где все термины Elixir могут быть сравнены друг с другом. Дополнительную информацию см. в разделе "Структурное сравнение".

Встроено компилятором.

Примеры

iex> min(1, 2)
1
iex> min("foo", "bar")
"bar"

Удаляет ключ из вложенной структуры по заданному path.

Аналогично pop_in/2, за исключением того, что путь извлекается с помощью макроса, а не передаётся в виде списка. Например:

pop_in(opts[:foo][:bar])

Эквивалентно:

pop_in(opts, [:foo, :bar])

Обратите внимание, что для работы этого макроса весь путь должен всегда быть видим этим макросом. Дополнительную информацию о поддерживаемых выражениях пути см. в документации get_and_update_in/2.

Примеры

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> pop_in(users["john"][:age])
{27, %{"john" => %{}, "meg" => %{age: 23}}}

iex> users = %{john: %{age: 27}, meg: %{age: 23}}
iex> pop_in(users.john[:age])
{27, %{john: %{}, meg: %{age: 23}}}

В случае, если какой-либо элемент возвращает nil, его ключ будет удалён, и удаление будет считаться успешным.

@spec pop_in(data, [Access.get_and_update_fun(term(), data) | term(), ...]) ::
  {term(), data}
when data: Access.container()

Удаляет ключ из заданной вложенной структуры.

Использует протокол Access для обхода структур в соответствии с заданным keys, если key не является функцией. Если ключ является функцией, она будет вызвана так, как указано в get_and_update_in/3.

Примеры

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> pop_in(users, ["john", :age])
{27, %{"john" => %{}, "meg" => %{age: 23}}}

В случае, если какой-либо элемент возвращает nil, его ключ будет удалён, и удаление будет считаться успешным.

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> pop_in(users, ["jane", :age])
{nil, %{"john" => %{age: 27}, "meg" => %{age: 23}}}

@spec put_elem(tuple(), non_neg_integer(), term()) :: tuple()

Вставляет value в заданный нулевой индекс index в tuple.

Встроено компилятором.

Примеры

iex> tuple = {:foo, :bar, 3}
iex> put_elem(tuple, 0, :baz)
{:baz, :bar, 3}

Вставляет значение во вложенную структуру по заданному path.

Аналогично put_in/3, за исключением того, что путь извлекается с помощью макроса, а не передаётся в виде списка. Например:

put_in(opts[:foo][:bar], :baz)

Эквивалентно:

put_in(opts, [:foo, :bar], :baz)

Это также работает со вложенными структурами и способом указания путей через struct.path.to.value:

put_in(struct.foo.bar, :baz)

Обратите внимание, что для работы этого макроса весь путь должен всегда быть видим этим макросом. Дополнительную информацию о поддерживаемых выражениях пути см. в документации get_and_update_in/2.

Примеры

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> put_in(users["john"][:age], 28)
%{"john" => %{age: 28}, "meg" => %{age: 23}}

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> put_in(users["john"].age, 28)
%{"john" => %{age: 28}, "meg" => %{age: 23}}

@spec put_in(Access.t(), [term(), ...], term()) :: Access.t()

Вставляет значение во вложенную структуру.

Использует модуль Access для обхода структур в соответствии с заданным keys, если key не является функцией. Если ключ является функцией, она будет вызвана так, как указано в get_and_update_in/3.

Примеры

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> put_in(users, ["john", :age], 28)
%{"john" => %{age: 28}, "meg" => %{age: 23}}

Если любое из промежуточных значений равно nil, будет выброшено исключение:

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> put_in(users, ["jane", :age], "oops")
** (ArgumentError) could not put/update key :age on a nil value

Выбрасывает исключение.

Если message — строка, выбросит исключение RuntimeError с ней.

Если message — атом, просто вызовет raise/2 с атомом в качестве первого аргумента и [] в качестве второго.

Если message — структура исключения, она выбросится как есть.

Если message — что-либо ещё, raise завершится исключением ArgumentError.

Примеры

iex> raise "oops"
** (RuntimeError) oops

try do
  1 + :foo
rescue
  x in [ArithmeticError] ->
    IO.puts("that was expected")
    raise x
end

Выбрасывает исключение.

Вызывает функцию exception/1 для заданного аргумента (который должен быть именем модуля, как ArgumentError или RuntimeError), передавая attributes для получения структуры исключения.

Любой модуль, содержащий вызов макроса defexception/1, автоматически реализует обратный вызов Exception.exception/1, ожидаемый raise/2. Дополнительную информацию см. в defexception/1.

Примеры

iex> raise(ArgumentError, "Sample")
** (ArgumentError) Sample

Выбрасывает исключение, сохраняя предыдущий стек вызовов.

Работает как raise/1, но не генерирует новый стек вызовов.

Обратите внимание, что __STACKTRACE__ может использоваться внутри catch/rescue для получения текущего стека вызовов.

Примеры

try do
  raise "oops"
rescue
  exception ->
    reraise exception, __STACKTRACE__
end

Выбрасывает исключение, сохраняя предыдущий стек вызовов.

reraise/3 работает как reraise/2, за исключением того, что он передаёт аргументы функции exception/1 так, как описано в raise/2.

Примеры

try do
  raise "oops"
rescue
  exception ->
    reraise WrapperError, [exception: exception], __STACKTRACE__
end

@spec send(dest :: Process.dest(), message) :: message when message: any()

Отправляет сообщение заданному dest и возвращает сообщение.

dest может быть удалённым или локальным PID, локальным портом, локально зарегистрированным именем или кортежем в формате {registered_name, node} для зарегистрированного имени на другом узле.

Компилируется встраиваемо.

Примеры

iex> send(self(), :hello)
:hello

Обрабатывает сигил ~C для списков символов.

Возвращает список символов без интерполяций и без управляющих символов, за исключением экранирования закрывающего символа сигила.

Список символов — это список целых чисел, где все целые числа являются допустимыми кодовыми точками. Три выражения ниже эквивалентны:

~C"foo\n"
[?f, ?o, ?o, ?\\, ?n]
[102, 111, 111, 92, 110]

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

Примеры

iex> ~C(foo)
~c"foo"

iex> ~C(f#{o}o)
~c"f\#{o}o"

iex> ~C(foo\n)
~c"foo\\n"

Обрабатывает сигил ~c для списков символов.

Возвращает список символов, убирая экранирование символов и заменяя интерполяции.

Список символов — это список целых чисел, где все целые числа являются допустимыми кодовыми точками. Три выражения ниже эквивалентны:

~c"foo"
[?f, ?o, ?o]
[102, 111, 111]

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

Примеры

iex> ~c(foo)
~c"foo"

iex> ~c(f#{:o}o)
~c"foo"

iex> ~c(f\#{:o}o)
~c"f\#{:o}o"

Список печатается как ~c сигил, только если все кодовые точки находятся в диапазоне ASCII:

iex> ~c"hełło"
[104, 101, 322, 322, 111]

iex> [104, 101, 108, 108, 111]
~c"hello"

См. Inspect.Opts для получения дополнительной информации.

Обрабатывает сигил ~D для дат.

По умолчанию этот сигил использует встроенный Calendar.ISO, который требует, чтобы даты были записаны в формате ISO8601:

~D[yyyy-mm-dd]

например:

~D[2015-01-13]

Если вы используете альтернативные календари, можно использовать любую запись, при условии, что за записью следует пробел и имя календаря:

~D[SOME-REPRESENTATION My.Alternative.Calendar]

Вариант с маленькой буквой ~d не существует, так как интерполяции и управляющие символы не нужны для сигилов дат.

Дополнительную информацию о датах можно найти в модуле Date.

Примеры

iex> ~D[2015-01-13]
~D[2015-01-13]

Обрабатывает сигил ~N для неявных дат и времён.

По умолчанию этот сигил использует встроенный Calendar.ISO, который требует, чтобы неявные даты и времена были записаны в формате ISO8601:

~N[yyyy-mm-dd hh:mm:ss]
~N[yyyy-mm-dd hh:mm:ss.ssssss]
~N[yyyy-mm-ddThh:mm:ss.ssssss]

например:

~N[2015-01-13 13:00:07]
~N[2015-01-13T13:00:07.123]

Если вы используете альтернативные календари, можно использовать любую запись, при условии, что за записью следует пробел и имя календаря:

~N[SOME-REPRESENTATION My.Alternative.Calendar]

Вариант с маленькой буквой ~n не существует, так как интерполяции и управляющие символы не нужны для сигилов дат и времён.

Дополнительную информацию о неявных датах и временах можно найти в модуле NaiveDateTime.

Примеры

iex> ~N[2015-01-13 13:00:07]
~N[2015-01-13 13:00:07]
iex> ~N[2015-01-13T13:00:07.001]
~N[2015-01-13 13:00:07.001]

Обрабатывает сигил ~R для регулярных выражений.

Возвращает шаблон регулярного выражения без интерполяций и без управляющих символов. Обратите внимание, что он всё ещё поддерживает экранирование токенов Regex (таких как экранирование + или ?) и также требует от вас экранировать закрывающий символ сигила, если он встречается в Regex.

Дополнительную информацию о регулярных выражениях можно найти в модуле Regex.

Примеры

iex> Regex.match?(~R(f#{1,3}o), "f#o")
true

Обрабатывает сигил ~r для регулярных выражений.

Возвращает шаблон регулярного выражения, убирая экранирование символов и заменяя интерполяции.

Дополнительную информацию о регулярных выражениях можно найти в модуле Regex.

Примеры

iex> Regex.match?(~r/foo/, "foo")
true

iex> Regex.match?(~r/a#{:b}c/, "abc")
true

Хотя сигил ~r позволяет использовать скобки и квадратные скобки в качестве разделителей, предпочтительнее использовать " или / для избежания конфликтов с экранированием служебных символов regex.

Обрабатывает сигил ~S для строк.

Возвращает строку без интерполяций и без управляющих символов, за исключением экранирования закрывающего символа сигила.

Примеры

iex> ~S(foo)
"foo"
iex> ~S(f#{o}o)
"f\#{o}o"
iex> ~S(\o/)
"\\o/"

Однако, если вы хотите повторно использовать сам символ сигила в строке, вам нужно его экранировать:

iex> ~S((\))
"()"

Обрабатывает сигил ~s для строк.

Возвращает строку так, как будто это строка в двойных кавычках, убирая экранирование символов и заменяя интерполяции.

Примеры

iex> ~s(foo)
"foo"

iex> ~s(f#{:o}o)
"foo"

iex> ~s(f\#{:o}o)
"f\#{:o}o"

Обрабатывает сигил ~T для времён.

По умолчанию этот сигил использует встроенный Calendar.ISO, который требует, чтобы времена были записаны в формате ISO8601:

~T[hh:mm:ss]
~T[hh:mm:ss.ssssss]

например:

~T[13:00:07]
~T[13:00:07.123]

Если вы используете альтернативные календари, можно использовать любую запись, при условии, что за записью следует пробел и имя календаря:

~T[SOME-REPRESENTATION My.Alternative.Calendar]

Вариант с маленькой буквой ~t не существует, так как интерполяции и управляющие символы не нужны для сигилов времён.

Дополнительную информацию о временах можно найти в модуле Time.

Примеры

iex> ~T[13:00:07]
~T[13:00:07]
iex> ~T[13:00:07.001]
~T[13:00:07.001]

Обрабатывает сигил ~U для создания UTC DateTime.

По умолчанию этот сигил использует встроенный Calendar.ISO, который требует, чтобы UTC даты и времена были записаны в формате ISO8601:

~U[yyyy-mm-dd hh:mm:ssZ]
~U[yyyy-mm-dd hh:mm:ss.ssssssZ]
~U[yyyy-mm-ddThh:mm:ss.ssssss+00:00]

например:

~U[2015-01-13 13:00:07Z]
~U[2015-01-13T13:00:07.123+00:00]

Если вы используете альтернативные календари, можно использовать любую запись, при условии, что за записью следует пробел и имя календаря:

~U[SOME-REPRESENTATION My.Alternative.Calendar]

Указанное datetime_string должно содержать «Z» или «00:00», что отмечает его как UTC, в противном случае возникает ошибка.

Вариант с маленькой буквой ~u не существует, так как интерполяции и управляющие символы не нужны для сигилов дат и времён.

Дополнительную информацию о датах и временах можно найти в модуле DateTime.

Примеры

iex> ~U[2015-01-13 13:00:07Z]
~U[2015-01-13 13:00:07Z]
iex> ~U[2015-01-13T13:00:07.001+00:00]
~U[2015-01-13 13:00:07.001Z]

Обрабатывает сигил ~W для списков слов.

Возвращает список «слов», разделённых пробелами, без интерполяций и без управляющих символов, за исключением экранирования закрывающего символа сигила.

Модификаторы

• s: слова в списке — это строки (по умолчанию)
• a: слова в списке — это атомы
• c: слова в списке — это списки символов

Примеры

iex> ~W(foo #{bar} baz)
["foo", "\#{bar}", "baz"]

Обрабатывает сигил ~w для списка слов.

Возвращает список "слов", разделенных пробелами. Для каждого слова выполняется экранирование символов и интерполяция.

Модификаторы

• s: слова в списке являются строками (по умолчанию)
• a: слова в списке являются атомами
• c: слова в списке являются списками символов

Примеры

iex> ~w(foo #{:bar} baz)
["foo", "bar", "baz"]

iex> ~w(foo #{" bar baz "})
["foo", "bar", "baz"]

iex> ~w(--source test/enum_test.exs)
["--source", "test/enum_test.exs"]

iex> ~w(foo bar baz)a
[:foo, :bar, :baz]

iex> ~w(foo bar baz)c
[~c"foo", ~c"bar", ~c"baz"]

@spec spawn((-> any())) :: pid()

Запускает заданную функцию и возвращает её PID.

Как правило, разработчики не используют функции spawn, вместо этого они используют абстракции, такие как Task, GenServer и Agent, построенные поверх spawn, которые запускают процессы с большими удобствами в плане интроспекции и отладки.

См. модуль Process для получения дополнительных функций, связанных с процессами.

Анонимная функция принимает 0 аргументов и может возвращать любое значение.

Встраивается компилятором.

Примеры

current = self()
child = spawn(fn -> send(current, {self(), 1 + 2}) end)

receive do
  {^child, 3} -> IO.puts("Received 3 back")
end

@spec spawn(module(), atom(), list()) :: pid()

Запускает заданную функцию fun из данного module, передавая ей данные args, и возвращает её PID.

Как правило, разработчики не используют функции spawn, вместо этого они используют абстракции, такие как Task, GenServer и Agent, построенные поверх spawn, которые запускают процессы с большими удобствами в плане интроспекции и отладки.

См. модуль Process для получения дополнительных функций, связанных с процессами.

Встраивается компилятором.

Примеры

spawn(SomeModule, :function, [1, 2, 3])

@spec spawn_link((-> any())) :: pid()

Запускает заданную функцию, связывает её с текущим процессом и возвращает её PID.

Как правило, разработчики не используют функции spawn, вместо этого они используют абстракции, такие как Task, GenServer и Agent, построенные поверх spawn, которые запускают процессы с большими удобствами в плане интроспекции и отладки.

См. модуль Process для получения дополнительных функций, связанных с процессами. Для получения дополнительной информации о связывании см. Process.link/1.

Анонимная функция принимает 0 аргументов и может возвращать любое значение.

Встраивается компилятором.

Примеры

current = self()
child = spawn_link(fn -> send(current, {self(), 1 + 2}) end)

receive do
  {^child, 3} -> IO.puts("Received 3 back")
end

@spec spawn_link(module(), atom(), list()) :: pid()

Запускает заданную функцию fun из данного module, передавая ей данные args, связывает её с текущим процессом и возвращает её PID.

Как правило, разработчики не используют функции spawn, вместо этого они используют абстракции, такие как Task, GenServer и Agent, построенные поверх spawn, которые запускают процессы с большими удобствами в плане интроспекции и отладки.

См. модуль Process для получения дополнительных функций, связанных с процессами. Для получения дополнительной информации о связывании см. Process.link/1.

Встраивается компилятором.

Примеры

spawn_link(SomeModule, :function, [1, 2, 3])

@spec spawn_monitor((-> any())) :: {pid(), reference()}

Запускает заданную функцию, контролирует её и возвращает её PID и ссылку на мониторинг.

Как правило, разработчики не используют функции spawn, вместо этого они используют абстракции, такие как Task, GenServer и Agent, построенные поверх spawn, которые запускают процессы с большими удобствами в плане интроспекции и отладки.

См. модуль Process для получения дополнительных функций, связанных с процессами.

Анонимная функция принимает 0 аргументов и может возвращать любое значение.

Встраивается компилятором.

Примеры

current = self()
spawn_monitor(fn -> send(current, {self(), 1 + 2}) end)

@spec spawn_monitor(module(), atom(), list()) :: {pid(), reference()}

Запускает данный модуль и функцию, передавая данные args, контролирует её и возвращает её PID и ссылку на мониторинг.

Как правило, разработчики не используют функции spawn, вместо этого они используют абстракции, такие как Task, GenServer и Agent, построенные поверх spawn, которые запускают процессы с большими удобствами в плане интроспекции и отладки.

См. модуль Process для получения дополнительных функций, связанных с процессами.

Встраивается компилятором.

Примеры

spawn_monitor(SomeModule, :function, [1, 2, 3])

@spec struct(module() | struct(), Enumerable.t()) :: struct()

Создает и обновляет структуру.

Аргумент struct может быть атомом (который определяет defstruct) или самой struct. Вторым аргументом является любой Enumerable, который выдает кортежи из двух элементов (пары ключ-значение) во время перечисления.

Ключи в Enumerable, которые не существуют в структуре, автоматически отбрасываются. Обратите внимание, что ключи должны быть атомами, так как только атомы разрешены при определении структуры. Если ключи в Enumerable дублируются, будет взята последняя запись (такое же поведение, как у Map.new/1).

Эта функция полезна для динамического создания и обновления структур, а также для преобразования карт в структуры; в последнем случае простого вставки соответствующего поля :__struct__ в карту может быть недостаточно, и вместо этого следует использовать struct/2.

Примеры

defmodule User do
  defstruct name: "john"
end

struct(User)
#=> %User{name: "john"}

opts = [name: "meg"]
user = struct(User, opts)
#=> %User{name: "meg"}

struct(user, unknown: "value")
#=> %User{name: "meg"}

struct(User, %{name: "meg"})
#=> %User{name: "meg"}

# String keys are ignored
struct(User, %{"name" => "meg"})
#=> %User{name: "john"}

@spec struct!(module() | struct(), Enumerable.t()) :: struct()

Аналогично struct/2, но проверяет правильность ключа.

Функция struct!/2 эмулирует поведение структур во время компиляции. Это означает, что:

• при построении структуры, как в struct!(SomeStruct, key: :value), это эквивалентно %SomeStruct{key: :value}, и поэтому эта функция будет проверять, принадлежит ли каждый заданный ключ-значение структуре. Если структура применяет какой-либо ключ через @enforce_keys, они также будут применены;

• при обновлении структуры, как в struct!(%SomeStruct{}, key: :value), это эквивалентно %SomeStruct{struct | key: :value}, и поэтому эта функция будет проверять, принадлежит ли каждый заданный ключ-значение структуре. Однако обновление структур не применяет ключи, поскольку ключи применяются только при построении;

Передает первый аргумент, value, во второй аргумент, функцию fun, и возвращает сам value.

Полезно для выполнения синхронных побочных эффектов в конвейере, используя оператор |>/2.

Примеры

iex> tap(1, fn x -> x + 1 end)
1

Чаще всего это используется в конвейерах с использованием оператора |>/2. Например, предположим, что вы хотите проверить часть структуры данных. Вы можете написать:

%{a: 1}
|> Map.update!(:a, & &1 + 2)
|> tap(&IO.inspect(&1.a))
|> Map.update!(:a, & &1 * 2)

Передает первый аргумент, value, во второй аргумент, функцию fun, и возвращает результат вызова fun.

Другими словами, она вызывает функцию fun с value в качестве аргумента и возвращает её результат.

Чаще всего используется в цепочках операций с помощью оператора |>/2, позволяющего передавать значение в функцию за пределами её первого аргумента.

Примеры

iex> 1 |> then(fn x -> x * 2 end)
2

iex> 1 |> then(fn x -> Enum.drop(["a", "b", "c"], x) end)
["b", "c"]

@spec throw(term()) :: no_return()

Нелокальное возвращение из функции.

Использование throw/1 обычно не рекомендуется, так как оно позволяет функции выйти за пределы её обычного потока выполнения, что может затруднить чтение кода. Кроме того, все брошенные значения должны быть перехвачены try/catch. Дополнительную информацию см. в try/1.

Встраивается компилятором.

Преобразует заданное значение в список символов в соответствии с протоколом List.Chars.

Примеры

iex> to_charlist(:foo)
~c"foo"

Преобразует аргумент в строку в соответствии с протоколом String.Chars.

Эта функция вызывается при интерполяции строк.

Примеры

iex> to_string(:foo)
"foo"

Предоставляет макрос unless.

Этот макрос оценивает и возвращает блок do , переданный во втором аргументе, если condition оценивается как ложное значение (false или nil). В противном случае он возвращает значение блока else, если он есть, или nil, если его нет.

См. также if/2.

Примеры

iex> unless(Enum.empty?([]), do: "Hello")
nil

iex> unless(Enum.empty?([1, 2, 3]), do: "Hello")
"Hello"

iex> unless Enum.sum([2, 2]) == 5 do
...>   "Math still works"
...> else
...>   "Math is broken"
...> end
"Math still works"

Обновляет вложенную структуру с помощью заданной функции path.

Аналогично update_in/3, за исключением того, что путь извлекается через макрос, а не передается в виде списка. Например:

update_in(opts[:foo][:bar], &(&1 + 1))

Эквивалентно:

update_in(opts, [:foo, :bar], &(&1 + 1))

Это также работает со вложенными структурами и способом указания путей struct.path.to.value:

update_in(struct.foo.bar, &(&1 + 1))

Обратите внимание, что для работы этого макроса полный путь должен быть всегда виден этим макросом. Более подробную информацию о поддерживаемых выражениях пути см. в документации get_and_update_in/2.

Примеры

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> update_in(users["john"][:age], &(&1 + 1))
%{"john" => %{age: 28}, "meg" => %{age: 23}}

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> update_in(users["john"].age, &(&1 + 1))
%{"john" => %{age: 28}, "meg" => %{age: 23}}

@spec update_in(Access.t(), [term(), ...], (term() -> term())) :: Access.t()

Обновляет ключ в вложенной структуре.

Использует модуль Access для обхода структур в соответствии с указанным keys, если key не является функцией. Если ключ является функцией, она будет вызвана как указано в get_and_update_in/3.

data — это вложенная структура (т. е. карта, список ключевых слов или структура, реализующая поведение Access). Аргумент fun получает значение key (или nil, если key отсутствует), и результат заменяет значение в структуре.

Примеры

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> update_in(users, ["john", :age], &(&1 + 1))
%{"john" => %{age: 28}, "meg" => %{age: 23}}

Обратите внимание, что текущее значение, переданное анонимной функции, может быть nil. Если какое-либо из промежуточных значений равно nil, будет возбуждено исключение:

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> update_in(users, ["jane", :age], & &1 + 1)
** (ArgumentError) could not put/update key :age on a nil value

Использует заданный модуль в текущем контексте.

При вызове:

use MyModule, some: :options

Elixir вызовет MyModule.__using__/1, передав второй аргумент use в качестве своего аргумента. Поскольку __using__/1 обычно является макросом, применяются все обычные правила для макросов, и её возвращаемое значение должно быть цитируемым кодом, который затем вставляется туда, где вызывается use/2.

Вставка кода

use MyModule работает как точка вставки кода в вызывающем коде. Поскольку вызывающий код имеет мало контроля над тем, как код вставляется, use/2 следует использовать с осторожностью. Если возможно, избегайте использования в пользу import/2 или alias/2 всякий раз, когда это возможно.

Примеры

Например, для написания тестовых случаев с использованием фреймворка ExUnit в Elixir, разработчик должен использовать модуль ExUnit.Case:

defmodule AssertionTest do
  use ExUnit.Case, async: true

  test "always pass" do
    assert true
  end
end

В этом примере Elixir вызовет макрос __using__/1 в модуле ExUnit.Case с списком ключевых слов [async: true] в качестве аргумента.

Другими словами, use/2 переводится в:

defmodule AssertionTest do
  require ExUnit.Case
  ExUnit.Case.__using__(async: true)

  test "always pass" do
    assert true
  end
end

где ExUnit.Case определяет макрос __using__/1:

defmodule ExUnit.Case do
  defmacro __using__(opts) do
    # do something with opts
    quote do
      # return some code to inject in the caller
    end
  end
end

Рекомендации по использованию

__using__/1 обычно используется, когда требуется установить некоторое состояние (через атрибуты модуля) или обратные вызовы (например, @before_compile, см. документацию по Module для получения дополнительной информации) в вызывающий код.

__using__/1 также может быть использован для алиасирования, требования или импорта функциональности из других модулей:

defmodule MyModule do
  defmacro __using__(_opts) do
    quote do
      import MyModule.Foo
      import MyModule.Bar
      import MyModule.Baz

      alias MyModule.Repo
    end
  end
end

Однако не передавайте __using__/1, если всё, что она делает, это импортирует, алиасирует или требует сам модуль. Например, избегайте этого:

defmodule MyModule do
  defmacro __using__(_opts) do
    quote do
      import MyModule
    end
  end
end

В таких случаях разработчики должны вместо этого напрямую импортировать или алиасить модуль, чтобы они могли настраивать их по своему желанию без косвенности через use/2. Разработчики также должны избегать определения функций внутри __using__/1.

Поскольку use MyModule может генерировать любой код, разработчикам может быть сложно понять влияние use MyModule.

По этой причине, чтобы обеспечить руководство и ясность, мы рекомендуем разработчикам включать блок предупреждений в свой @moduledoc , который объясняет, как use MyModule влияет на их код. Например, документация по GenServer описывает:

use GenServer

При использовании use GenServer, модуль GenServer установит @behaviour GenServer и определит функцию child_spec/1 , поэтому ваш модуль может быть использован как дочерний элемент в дереве контроля состояния.

Это предоставляет краткое описание того, как использование модуля влияет на пользовательский код. Имейте в виду, что нужно перечислять только изменения, внесённые в публичный API модуля. Например, если use MyModule устанавливает внутренний атрибут, называемый @_my_module_info, и этот атрибут никогда не предназначен для публичного использования, его не нужно указывать.

Для удобства, разметка для генерации блока предупреждения выше:

> #### `use GenServer` {: .info}
>
> When you `use GenServer`, the GenServer module will
> set `@behaviour GenServer` and define a `child_spec/1`
> function, so your module can be used as a child
> in a supervision tree.

Помечает, что заданная переменная не должна подвергаться гигиенизации.

Этот макрос ожидает переменную и обычно вызывается внутри Kernel.SpecialForms.quote/2 для обозначения того, что переменная не должна подвергаться гигиенизации. См. Kernel.SpecialForms.quote/2 для получения дополнительной информации.

Примеры

iex> Kernel.var!(example) = 1
1
iex> Kernel.var!(example)
1

Оператор конвейера.

Данный оператор вводит выражение слева в качестве первого аргумента вызова функции справа.

Примеры

iex> [1, [2], 3] |> List.flatten()
[1, 2, 3]

Приведённый выше пример эквивалентен вызову List.flatten([1, [2], 3]).

Оператор |>/2 преимущественно полезен при необходимости выполнения последовательности операций, напоминающих конвейер:

iex> [1, [2], 3] |> List.flatten() |> Enum.map(fn x -> x * 2 end)
[2, 4, 6]

В приведённом примере список [1, [2], 3] передаётся в качестве первого аргумента функции List.flatten/1, затем сглаженный список передаётся в качестве первого аргумента функции Enum.map/2, которая удваивает каждый элемент списка.

Другими словами, выражение выше просто переводится в:

Enum.map(List.flatten([1, [2], 3]), fn x -> x * 2 end)

Недостатки

Существует две распространённые проблемы при использовании оператора конвейера.

Первая связана с приоритетом операторов. Например, следующее выражение:

String.graphemes "Hello" |> Enum.reverse

Переводится в:

String.graphemes("Hello" |> Enum.reverse())

что приводит к ошибке, поскольку протокол Enumerable не определён для бинарных данных. Добавление явных скобок устраняет неоднозначность:

String.graphemes("Hello") |> Enum.reverse()

Или, ещё лучше:

"Hello" |> String.graphemes() |> Enum.reverse()

Вторая ограниченность заключается в том, что Elixir всегда выполняет конвейерную передачу в функцию. Поэтому, чтобы передать значение анонимной функции, её необходимо вызвать:

some_fun = &Regex.replace(~r/l/, &1, "L")
"Hello" |> some_fun.()

В качестве альтернативы, можно использовать then/2 для того же эффекта:

some_fun = &Regex.replace(~r/l/, &1, "L")
"Hello" |> then(some_fun)

then/2 чаще всего используется, когда требуется передать значение функции, но ожидается значение вне первого аргумента, как в примере выше. Заменив some_fun его значением, получаем:

"Hello" |> then(&Regex.replace(~r/l/, &1, "L"))

Булевый оператор «или».

Обеспечивает оператор короткого замыкания, который вычисляет и возвращает второе выражение только в том случае, если первое выражение не оценивается как истинное значение (то есть, оно либо nil , либо false). В противном случае возвращает первое выражение.

Запрещён в условиях guard.

Примеры

iex> Enum.empty?([1]) || Enum.empty?([1])
false

iex> List.first([]) || true
true

iex> Enum.empty?([1]) || 1
1

iex> Enum.empty?([]) || throw(:bad)
true

Обратите внимание, что в отличие от or/2, этот оператор принимает в качестве первого аргумента любое выражение, а не только булевы значения.