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

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

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

Примеры

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

iex> !List.first([])
true

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

Представляет собой оператор короткого замыкания, который вычисляет и возвращает второе выражение только если первое выражение вычисляется как истинное значение (не 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()

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

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

Примеры

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> 'foo' ++ 'bar'
'foobar'

# returns an improper list
iex> [1] ++ 2
[1 | 2]

# returns a proper list
iex> [1] ++ [2]
[1, 2]

# improper list on the right will return an improper list
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]

Создаёт диапазон от 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)
[]

Оператор конкатенации бинарных данных. Конкатенирует два бинарных данных.

Генерирует исключение 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()

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

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

Если right является строкой, возвращает 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]

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

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

Если заданный 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]

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

Примеры

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

Поскольку исключения являются структурами, доступен также 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 InheritMod do
  use DefaultMod

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

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

Если @behaviour было определено, defoverridable также может быть вызван с модулем в качестве аргумента. Все реализованные обратные вызовы из поведения выше вызова defoverridable будут помечены как переопределяемые.

Пример

defmodule Behaviour do
  @callback foo :: any
end

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

      def foo do
        "Override me"
      end

      defoverridable Behaviour
    end
  end
end

defmodule InheritMod do
  use DefaultMod

  def foo do
    "Overridden"
  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

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

Хотя структуры являются отображениями, по умолчанию структуры не реализуют ни один из протоколов, реализованных для отображений. Например, попытка использования протокола со структурой 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: 10 + 11
end

MyProtocol.call(john) # it works!

Для каждого протокола в списке @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, возвращается 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 не является функцией, что подробно описано в последующем разделе.

Примеры

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> get_in(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> users = nil
iex> get_in(users, [Access.all(), :age])
nil

Основная особенность get_in/2 заключается именно в том, что она прерывает обход, когда обнаруживает значение nil. Если вам не нужна проверка на nil, вы, скорее всего, можете написать «обычный» код Elixir:

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

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

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

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('bar')
"'bar'"

iex> inspect([0 | '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()
[]

Кроме того, помните, что оператор фиксации сопоставляет значения, а не шаблоны:

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 для списков символов.

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

Примеры

iex> ~C(foo)
'foo'

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

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

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

Примеры

iex> ~c(foo)
'foo'

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

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

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

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

~D[yyyy-mm-dd]

например:

~D[2015-01-13]

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

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

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

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

Дополнительную информацию о простых датах и времени можно найти в модуле 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 для регулярных выражений.

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

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

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

Примеры

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
['foo', 'bar', '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()}

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

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

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

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

Примеры

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

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

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

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

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

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

@spec struct(module() | struct(), Enum.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"}

Передаёт value в заданную fun и возвращает исходное значение value.

Полезно для выполнения синхронных побочных эффектов в конвейере.

Примеры

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

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

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

Передаёт value в заданную fun.

Другими словами, это вызывает fun с value в качестве аргумента. Это наиболее часто используется в конвейерах, позволяя вам передать значение в функцию вне её первого аргумента.

Примеры

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()

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

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

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

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

Примеры

iex> to_charlist(:foo)
'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

макрос __using__/1 из модуля MyModule вызывается со вторым аргументом, переданным в use, в качестве аргумента. Поскольку __using__/1 является макросом, применяются все обычные правила макросов, а его возвращаемое значение должно быть кодом в кавычках, который затем вставляется туда, где вызывается use/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, если эти функции не являются реализацией по умолчанию ранее определенного @callback или являются функциями, предназначенными для переопределения (см. defoverridable/1). Даже в этих случаях определение функций следует рассматривать как "последнее средство".

Если вы хотите предоставить существующую функциональность модулю пользователя, определите ее в модуле, который будет импортироваться соответственно; например, ExUnit.Case не определяет макрос test/3 в модуле, вызывающем use ExUnit.Case, но он определяет ExUnit.Case.test/3 и просто импортирует его в вызывающий модуль при использовании.

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

Этот макрос ожидает переменную и обычно вызывается внутри 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]).

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

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). В противном случае возвращает первое выражение.

Не допускается в операторах-условиях.

Примеры

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, этот оператор принимает любое выражение в качестве первого аргумента, а не только булевы значения.