@spec camelize(String.t()) :: String.t()

Преобразует заданную строку в формат CamelCase.

Эта функция была разработана для преобразования идентификаторов/токенов языка, поэтому она принадлежит модулю Macro. Не используйте её как общий механизм преобразования строк в CamelCase, так как она не поддерживает Unicode или символы, которые не являются допустимыми в идентификаторах Elixir.

Примеры

iex> Macro.camelize("foo_bar")
"FooBar"

iex> Macro.camelize("foo/bar")
"Foo.Bar"

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

iex> Macro.camelize("API.V1")
"API.V1"
iex> Macro.camelize("API_SPEC")
"API_SPEC"

@spec classify_atom(atom()) :: :alias | :identifier | :quoted | :unquoted

Классифицирует atom на основе возможного расположения в AST.

Возвращает один из следующих атомов:

• :alias — атом представляет алиас

• :identifier — атом может использоваться в качестве переменной или локального вызова функции (а также быть нецитируемым атомом)

• :unquoted — атом может использоваться в нецитируемой форме, включает операторы и атомы с @ в них

• :quoted — все остальные атомы, которые могут использоваться только в цитируемой форме

Большинство операторов будут :unquoted, такие как :+, за некоторыми исключениями, возвращающими :quoted из-за неоднозначности, например, :"::". Используйте operator?/2, чтобы проверить, является ли данный атом оператором.

Примеры

iex> Macro.classify_atom(:foo)
:identifier
iex> Macro.classify_atom(Foo)
:alias
iex> Macro.classify_atom(:foo@bar)
:unquoted
iex> Macro.classify_atom(:+)
:unquoted
iex> Macro.classify_atom(:Foo)
:unquoted
iex> Macro.classify_atom(:"with spaces")
:quoted

Применяет mod, function, и args во время компиляции в caller.

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

@spec dbg(t(), t(), Macro.Env.t()) :: t()

По умолчанию бэкенд для Kernel.dbg/2.

Эта функция предоставляет бэкенд по умолчанию для Kernel.dbg/2. Для получения дополнительной информации см. документацию к Kernel.dbg/2.

Эта функция:

• выводит информацию о заданном env
• выводит информацию о code и его возвращаемом значении (используя opts для проверки терминов)
• возвращает значение, возвращённое при вычислении code

Вы можете напрямую вызывать эту функцию для создания бэкендов Kernel.dbg/2, которые обращаются к этой функции по умолчанию.

Функция вызывает исключение, если контекст данного env является :match или :guard.

@spec decompose_call(t()) :: {atom(), [t()]} | {t(), atom(), [t()]} | :error

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

Возвращает :error при предоставлении некорректного синтаксиса вызова.

Примеры

iex> Macro.decompose_call(quote(do: foo))
{:foo, []}

iex> Macro.decompose_call(quote(do: foo()))
{:foo, []}

iex> Macro.decompose_call(quote(do: foo(1, 2, 3)))
{:foo, [1, 2, 3]}

iex> Macro.decompose_call(quote(do: Elixir.M.foo(1, 2, 3)))
{{:__aliases__, [], [:Elixir, :M]}, :foo, [1, 2, 3]}

iex> Macro.decompose_call(quote(do: 42))
:error

iex> Macro.decompose_call(quote(do: {:foo, [], []}))
:error

@spec escape(
  term(),
  keyword()
) :: t()

Рекурсивно экранирует значение, чтобы его можно было вставить в дерево синтаксического анализа.

Примеры

iex> Macro.escape(:foo)
:foo

iex> Macro.escape({:a, :b, :c})
{:{}, [], [:a, :b, :c]}

iex> Macro.escape({:unquote, [], [1]}, unquote: true)
1

Параметры

• :unquote - если true, эта функция оставляет выражения unquote/1 и unquote_splicing/1 неэкранированными, фактически снимая цитирование содержимого при экранировании. Этот параметр полезен только при экранировании AST, которые могут содержать цитированные фрагменты. По умолчанию false.

• :prune_metadata - если true, удаляет большую часть метаданных из экранированных узлов AST. Обратите внимание, что этот параметр изменяет семантику экранированного кода, и его следует использовать только при экранировании AST. По умолчанию false.

  Например, для :prune_metadata, ExUnit сохраняет AST каждого утверждения, поэтому, когда утверждение не выполняется, мы можем показать фрагменты кода пользователям. Без этого параметра каждый раз, когда модуль теста компилируется, мы получим разный MD5 байтового кода модуля, потому что AST содержит метаданные, такие как счётчики, специфичные для среды компиляции. Удаляя метаданные, мы обеспечиваем детерминированность модуля и уменьшаем объём данных, который ExUnit должен хранить. Сохраняется только минимальный объём метаданных, такие как :line, :no_parens и :delimiter.

Сравнение с quote/2

Функция escape/2 иногда путают с quote/2, потому что примеры выше ведут себя одинаково с обеими функциями. Ключевое различие лучше всего иллюстрируется, когда значение для экранирования хранится в переменной.

iex> Macro.escape({:a, :b, :c})
{:{}, [], [:a, :b, :c]}
iex> quote do: {:a, :b, :c}
{:{}, [], [:a, :b, :c]}

iex> value = {:a, :b, :c}
iex> Macro.escape(value)
{:{}, [], [:a, :b, :c]}

iex> quote do: value
{:value, [], __MODULE__}

iex> value = {:a, :b, :c}
iex> quote do: unquote(value)
** (ArgumentError) tried to unquote invalid AST: {:a, :b, :c}
Did you forget to escape term using Macro.escape/1?

escape/2 используется для экранирования значений (либо непосредственно переданных, либо привязанных к переменной), в то время как quote/2 создаёт деревья синтаксического анализа для выражений.

@spec expand(input(), Macro.Env.t()) :: output()

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

Обратите внимание, что эта функция не обходит AST, а только расширяет корневой узел.

Эта функция использует expand_once/2 в подпрограммах. Ознакомьтесь с ней для получения дополнительной информации и примеров.

@spec expand_literals(input(), Macro.Env.t()) :: output()

Расширяет все литералы в ast с использованием данного env.

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

Macro.expand_literals(ast, %{env | function: {:my_code, 1}})

На данный момент единственными расширяемыми литеральными узлами в AST являются алиасы, поэтому эта функция расширяет только алиасы (и делает это повсюду в литерале).

Однако будьте осторожны при удалении зависимостей от компиляции между модулями. Если вы их удалите, но всё ещё вызываете модуль во время компиляции, Elixir не сможет правильно перекомпилировать модули при их изменении.

@spec expand_literals(t(), acc, (t(), acc -> {t(), acc})) :: t() when acc: term()

Расширяет все литералы в ast с использованием заданной acc и fun.

fun будет вызвана с расширяемым узлом AST и acc и должна вернуть новый узел с acc. Это обобщённая версия expand_literals/2, которая поддерживает пользовательскую функцию расширения. Пожалуйста, обратитесь к expand_literals/2 для использования и потенциальных проблем.

@spec expand_once(input(), Macro.Env.t()) :: output()

Принимает узел AST и расширяет его один раз.

Следующие содержимые расширяются:

• Макросы (локальные или удалённые)
• Псевдонимы расширяются (если возможно) и возвращают атомы
• Макросы среды компиляции (__CALLER__/0, __DIR__/0, __ENV__/0 и __MODULE__/0)
• Чтение атрибутов модуля (@foo)

Если выражение не может быть расширено, оно возвращает само выражение. Эта функция не обходит AST, расширяется только корневой узел. Расширение происходит так, как если бы оно расширялось компилятором Elixir, и поэтому во время расширения будут вызываться отслеживатели компиляции и будут выводиться предупреждения об устаревании.

expand_once/2 выполняет расширение только один раз. Проверьте expand/2, чтобы выполнить расширение до тех пор, пока узел больше не сможет быть расширен.

Примеры

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

Рассмотрим реализацию ниже:

defmacro defmodule_with_length(name, do: block) do
  length = length(Atom.to_charlist(name))

  quote do
    defmodule unquote(name) do
      def name_length, do: unquote(length)
      unquote(block)
    end
  end
end

При вызове так:

defmodule_with_length My.Module do
  def other_function, do: ...
end

Компиляция завершится ошибкой, потому что My.Module при цитировании не является атомом, а деревом синтаксического анализа, как показано ниже:

{:__aliases__, [], [:My, :Module]}

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

alias MyHelpers, as: My

defmodule_with_length My.Module do
  def other_function, do: ...
end

Итоговое имя модуля будет MyHelpers.Module, а не My.Module. С Macro.expand/2 такие псевдонимы учитываются. Также расширяются локальные и удалённые макросы. Мы могли бы переписать наш макрос выше, используя эту функцию следующим образом:

defmacro defmodule_with_length(name, do: block) do
  expanded = Macro.expand(name, __CALLER__)
  length = length(Atom.to_charlist(expanded))

  quote do
    defmodule unquote(name) do
      def name_length, do: unquote(length)
      unquote(block)
    end
  end
end

@spec generate_arguments(0, context :: atom()) :: []

@spec generate_arguments(pos_integer(), context) :: [{atom(), [], context}, ...]
when context: atom()

Генерирует узлы AST для заданного количества переменных аргументов, используя Macro.var/2.

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

Примеры

iex> Macro.generate_arguments(2, __MODULE__)
[{:arg1, [], __MODULE__}, {:arg2, [], __MODULE__}]

@spec generate_unique_arguments(0, context :: atom()) :: []

@spec generate_unique_arguments(pos_integer(), context) :: [
  {atom(), [{:counter, integer()}], context},
  ...
]
when context: atom()

Генерирует узлы AST для заданного количества необходимых переменных аргументов, используя Macro.unique_var/2.

Примеры

iex> [var1, var2] = Macro.generate_unique_arguments(2, __MODULE__)
iex> {:arg1, [counter: c1], __MODULE__} = var1
iex> {:arg2, [counter: c2], __MODULE__} = var2
iex> is_integer(c1) and is_integer(c2)
true

@spec inspect_atom(:literal | :key | :remote_call, atom(), keyword()) :: binary()

Отображает atom в соответствии с различными форматами исходного кода.

Атом можно отобразить в соответствии с тремя различными форматами, в которых он появляется в AST: как литерал (:literal), как ключ (:key) или как имя функции удалённого вызова (:remote_call).

Параметры

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

Примеры

В качестве литерала

Литералы включают обычные атомы, цитируемые атомы, операторы, псевдонимы и специальные nil, true, и false атомы.

iex> Macro.inspect_atom(:literal, nil)
"nil"
iex> Macro.inspect_atom(:literal, :foo)
":foo"
iex> Macro.inspect_atom(:literal, :<>)
":<>"
iex> Macro.inspect_atom(:literal, :Foo)
":Foo"
iex> Macro.inspect_atom(:literal, Foo.Bar)
"Foo.Bar"
iex> Macro.inspect_atom(:literal, :"with spaces")
":\"with spaces\""

В качестве ключа

Отобразите атом как ключ списка ключевых слов или карты.

iex> Macro.inspect_atom(:key, :foo)
"foo:"
iex> Macro.inspect_atom(:key, :<>)
"<>:"
iex> Macro.inspect_atom(:key, :Foo)
"Foo:"
iex> Macro.inspect_atom(:key, :"with spaces")
"\"with spaces\":"

В качестве имени удалённого вызова

Отобразите атом как имя функции удалённого вызова.

iex> Macro.inspect_atom(:remote_call, :foo)
"foo"
iex> Macro.inspect_atom(:remote_call, :<>)
"<>"
iex> Macro.inspect_atom(:remote_call, :Foo)
"\"Foo\""
iex> Macro.inspect_atom(:remote_call, :"with spaces")
"\"with spaces\""

@spec operator?(name :: atom(), arity()) :: boolean()

Возвращает true если данное имя и арность — оператор.

Примеры

iex> Macro.operator?(:not_an_operator, 3)
false
iex> Macro.operator?(:.., 0)
true
iex> Macro.operator?(:+, 1)
true
iex> Macro.operator?(:++, 2)
true
iex> Macro.operator?(:..//, 3)
true

@spec path(t(), (t() -> as_boolean(term()))) :: [t()] | nil

Возвращает путь к узлу в ast, для которого fun возвращает значение, истинное для логического выражения.

Путь — список, начинающийся с узла, в котором fun возвращает истинное значение, за которым следуют все его родительские узлы.

Возвращает nil если fun возвращает только ложные значения.

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

Примеры

iex> Macro.path(quote(do: [1, 2, 3]), & &1 == 3)
[3, [1, 2, 3]]

iex> Macro.path(quote(do: [1, 2]), & &1 == 5)
nil

iex> Macro.path(quote(do: Foo.bar(3)), & &1 == 3)
[3, quote(do: Foo.bar(3))]

iex> Macro.path(quote(do: %{foo: [bar: :baz]}), & &1 == :baz)
[
  :baz,
  {:bar, :baz},
  [bar: :baz],
  {:foo, [bar: :baz]},
  {:%{}, [], [foo: [bar: :baz]]}
]

@spec pipe(t(), t(), integer()) :: t()

Перенаправляет expr в call_args в заданной position.

Эта функция может использоваться для реализации функциональности типа «потока». Например, сам |> реализован как:

defmacro left |> right do
  Macro.pipe(left, right, 0)
end

expr — AST выражения. call_args должен быть AST вызова, в противном случае эта функция вызовет ошибку. Например, рассмотрите оператор потока |>/2, который использует эту функцию для построения конвейеров.

Даже если выражение перенаправлено в AST, это не обязательно означает, что AST валиден. Например, вы можете перенаправить аргумент в div/2, фактически превращая его в вызов div/3, который по умолчанию не является функцией. Код вызовет ошибку, если функция div/3 не определена локально.

@spec postwalk(t(), (t() -> t())) :: t()

Эта функция ведет себя как prewalk/2, но выполняет обход выражений в цитировании по глубине, в порядке постфиксной записи.

@spec postwalk(t(), any(), (t(), any() -> {t(), any()})) :: {t(), any()}

Эта функция ведет себя как prewalk/3, но выполняет обход выражений в цитировании по глубине, в порядке постфиксной записи, используя накопитель.

@spec postwalker(t()) :: Enumerable.t()

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

Примеры

iex> ast = quote do: foo(1, "abc")
iex> Enum.map(Macro.postwalker(ast), & &1)
[1, "abc", {:foo, [], [1, "abc"]}]

@spec prewalk(t(), (t() -> t())) :: t()

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

Возвращает новый AST, где каждый узел является результатом вызова fun для каждого соответствующего узла ast.

Примеры

iex> ast = quote do: 5 + 3 * 7
iex> {:+, _, [5, {:*, _, [3, 7]}]} = ast
iex> new_ast = Macro.prewalk(ast, fn
...>   {:+, meta, children} -> {:*, meta, children}
...>   {:*, meta, children} -> {:+, meta, children}
...>   other -> other
...> end)
iex> {:*, _, [5, {:+, _, [3, 7]}]} = new_ast
iex> Code.eval_quoted(ast)
{26, []}
iex> Code.eval_quoted(new_ast)
{50, []}

@spec prewalk(t(), any(), (t(), any() -> {t(), any()})) :: {t(), any()}

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

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

Примеры

iex> ast = quote do: 5 + 3 * 7
iex> {:+, _, [5, {:*, _, [3, 7]}]} = ast
iex> {new_ast, acc} = Macro.prewalk(ast, [], fn
...>   {:+, meta, children}, acc -> {{:*, meta, children}, [:+ | acc]}
...>   {:*, meta, children}, acc -> {{:+, meta, children}, [:* | acc]}
...>   other, acc -> {other, acc}
...> end)
iex> {{:*, _, [5, {:+, _, [3, 7]}]}, [:*, :+]} = {new_ast, acc}
iex> Code.eval_quoted(ast)
{26, []}
iex> Code.eval_quoted(new_ast)
{50, []}

@spec prewalker(t()) :: Enumerable.t()

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

Примеры

iex> ast = quote do: foo(1, "abc")
iex> Enum.map(Macro.prewalker(ast), & &1)
[{:foo, [], [1, "abc"]}, 1, "abc"]

@spec quoted_literal?(t()) :: boolean()

Возвращает true, если данное выражение с цитированием представляет собой цитируемую литерал.

Атомы и числа всегда являются литералами. Двоичные данные, списки, кортежи, карты и структуры являются литералами только в том случае, если все их элементы также являются литералами.

Примеры

iex> Macro.quoted_literal?(quote(do: "foo"))
true
iex> Macro.quoted_literal?(quote(do: {"foo", 1}))
true
iex> Macro.quoted_literal?(quote(do: {"foo", 1, :baz}))
true
iex> Macro.quoted_literal?(quote(do: %{foo: "bar"}))
true
iex> Macro.quoted_literal?(quote(do: %URI{path: "/"}))
true
iex> Macro.quoted_literal?(quote(do: URI.parse("/")))
false
iex> Macro.quoted_literal?(quote(do: {foo, var}))
false

@spec special_form?(name :: atom(), arity()) :: boolean()

Возвращает true, если данное имя и арность являются специальной формой.

@spec struct_info!(module(), Macro.Env.t()) :: [
  %{field: atom(), required: boolean(), default: term()}
]

Извлекает информацию о структуре (эквивалентно вызову module.__info__(:struct)).

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

Она вызовет исключение ArgumentError, если структура недоступна.

@spec to_string(t()) :: String.t()

Преобразует данное выражение AST в строку.

Это удобная функция для преобразования AST в строку, которая отбрасывает все форматирование исходного кода и заключает новые строки в 98 символов. См. Code.quoted_to_algebra/2 как функцию более низкого уровня с большим контролем над форматированием.

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

Примеры

iex> Macro.to_string(quote(do: foo.bar(1, 2, 3)))
"foo.bar(1, 2, 3)"

@spec to_string(t(), (t(), String.t() -> String.t())) :: String.t()

Преобразует данное выражение AST в строку.

Указанная fun вызывается для каждого узла в AST с двумя аргументами: AST узла, который печатается, и строковое представление того же узла. Возвращаемое значение этой функции используется в качестве окончательного строкового представления этого узла AST.

Эта функция отбрасывает всё форматирование исходного кода.

Примеры

Macro.to_string(quote(do: 1 + 2), fn
  1, _string -> "one"
  2, _string -> "two"
  _ast, string -> string
end)
#=> "one + two"

@spec traverse(t(), any(), (t(), any() -> {t(), any()}), (t(), any() -> {t(), any()})) ::
  {t(), any()}

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

Возвращает кортеж, где первый элемент — новый AST, а второй — конечный аккумулятор. Новый AST является результатом вызова pre для каждого узла ast во время фазы обхода по предшествующим узлам и post во время фазы обхода по последующим узлам.

Примеры

iex> ast = quote do: 5 + 3 * 7
iex> {:+, _, [5, {:*, _, [3, 7]}]} = ast
iex> {new_ast, acc} =
...>  Macro.traverse(
...>    ast,
...>    [],
...>    fn
...>      {:+, meta, children}, acc -> {{:-, meta, children}, [:- | acc]}
...>      {:*, meta, children}, acc -> {{:/, meta, children}, [:/ | acc]}
...>      other, acc -> {other, acc}
...>    end,
...>    fn
...>      {:-, meta, children}, acc -> {{:min, meta, children}, [:min | acc]}
...>      {:/, meta, children}, acc -> {{:max, meta, children}, [:max | acc]}
...>      other, acc -> {other, acc}
...>    end
...>  )
iex> {:min, _, [5, {:max, _, [3, 7]}]} = new_ast
iex> [:min, :max, :/, :-] = acc
iex> Code.eval_quoted(new_ast)
{5, []}

@spec underscore(atom() | String.t()) :: String.t()

Преобразует заданный аргумент в строку с форматом подчёркивания-слэша.

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

Эта функция была разработана для форматирования идентификаторов/токенов языка с форматом подчёркивание-слэш, поэтому она принадлежит модулю Macro. Не используйте её в качестве общего механизма подчёркивания строк, так как она не поддерживает Unicode или символы, которые не являются допустимыми в идентификаторах Elixir.

Примеры

iex> Macro.underscore("FooBar")
"foo_bar"

iex> Macro.underscore("Foo.Bar")
"foo/bar"

iex> Macro.underscore(Foo.Bar)
"foo/bar"

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

iex> Macro.underscore("SAPExample")
"sap_example"

iex> Macro.camelize("sap_example")
"SapExample"

iex> Macro.camelize("hello_10")
"Hello10"

iex> Macro.camelize("foo/bar")
"Foo.Bar"

@spec unescape_string(String.t()) :: String.t()

Распаковывает символы в строке.

Это поведение распаковки, используемое по умолчанию в одинарных и двойных кавычках строк Elixir. См. unescape_string/2 для получения информации о том, как настроить карту экранирования.

В этом случае Elixir будет экранировать следующие: \0, \a, \b, \d, \e, \f, \n, \r, \s, \t и \v. Байты могут быть заданы в шестнадцатеричном формате с помощью \xNN, а коды Unicode — с помощью \uNNNN экранирования.

Эта функция часто используется в реализациях сигил (например, ~r, ~s и других), которые получают исходную, неэкранированную строку, и её можно использовать везде, где нужно имитировать обработку строк Elixir.

Примеры

iex> Macro.unescape_string("example\\n")
"example\n"

В примере выше мы передаём строку с \n экранированием и возвращаем версию без него.

@spec unescape_string(String.t(), (non_neg_integer() -> non_neg_integer() | false)) ::
  String.t()

Распаковывает символы в строке в соответствии с заданной схемой.

См. unescape_string/1, если вы хотите использовать ту же схему, что и одинарные и двойные кавычки строк Elixir.

Функция сопоставления

Функция сопоставления получает целое число, представляющее код символа, который нужно распаковать. Также есть специальные атомы :newline, :unicode, и :hex, которые управляют переходом на новую строку, кодами Unicode и экранированием соответственно.

Вот функция сопоставления по умолчанию, реализованная в Elixir:

def unescape_map(:newline), do: true
def unescape_map(:unicode), do: true
def unescape_map(:hex), do: true
def unescape_map(?0), do: ?0
def unescape_map(?a), do: ?\a
def unescape_map(?b), do: ?\b
def unescape_map(?d), do: ?\d
def unescape_map(?e), do: ?\e
def unescape_map(?f), do: ?\f
def unescape_map(?n), do: ?\n
def unescape_map(?r), do: ?\r
def unescape_map(?s), do: ?\s
def unescape_map(?t), do: ?\t
def unescape_map(?v), do: ?\v
def unescape_map(e), do: e

Если функция unescape_map/1 возвращает false, символ не экранирован, и обратная косая черта сохраняется в строке.

Примеры

Использование функции unescape_map/1 определённой выше просто:

Macro.unescape_string("example\\n", &unescape_map(&1))

@spec unique_var(var, context) :: {var, [{:counter, integer()}], context}
when var: atom(), context: atom()

Генерирует узел AST, представляющий уникальную переменную, заданную атомами var и context.

Вызов этой функции с теми же аргументами сгенерирует другую переменную со своим уникальным счётчиком. См. var/2 для альтернативы.

Примеры

iex> {:foo, [counter: c], __MODULE__} = Macro.unique_var(:foo, __MODULE__)
iex> is_integer(c)
true

@spec unpipe(t()) :: [t()]

Разбивает выражение конвейера на список.

AST для конвейера (последовательности применений |>/2) похож на AST последовательности бинарных операторов или применений функций: выражение верхнего уровня — это правое :|> (которое выполняется последним), а его левая и правая части — его аргументы:

quote do: 100 |> div(5) |> div(2)
#=> {:|>, _, [arg1, arg2]}

В примере выше, труба |>/2 — правая труба; arg1 — AST для 100 |> div(5), а arg2 — AST для div(2).

Часто бывает полезно иметь AST такого конвейера в виде списка применений функций. Эта функция делает именно это:

Macro.unpipe(quote do: 100 |> div(5) |> div(2))
#=> [{100, 0}, {{:div, [], [5]}, 0}, {{:div, [], [2]}, 0}]

Мы получаем список, который непосредственно следует за конвейером: сначала 100, затем div(5) (точнее, его AST), затем div(2). 0 как второй элемент кортежа — это позиция предыдущего элемента в конвейере внутри текущего применения функции: {{:div, [], [5]}, 0} означает, что предыдущий элемент (100) будет вставлен в качестве 0-го (первого) аргумента функции div/2, так что AST для этой функции станет {:div, [], [100, 5]} (div(100, 5)).

@spec update_meta(t(), (keyword() -> keyword())) :: t()

Применяет заданную функцию к метаданным узла, если они содержатся.

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

Примеры

iex> quoted = quote line: 10, do: sample()
{:sample, [line: 10], []}
iex> Macro.update_meta(quoted, &Keyword.delete(&1, :line))
{:sample, [], []}

@spec validate(term()) :: :ok | {:error, term()}

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

См. тип Macro.t/0 для полного описания допустимого цитируемого выражения.

Возвращает :ok если выражение допустимо. В противном случае возвращает кортеж в формате {:error, remainder}, где remainder — недопустимая часть цитируемого выражения.

Примеры

iex> Macro.validate({:two_element, :tuple})
:ok
iex> Macro.validate({:three, :element, :tuple})
{:error, {:three, :element, :tuple}}

iex> Macro.validate([1, 2, 3])
:ok
iex> Macro.validate([1, 2, 3, {4}])
{:error, {4}}

@spec var(var, context) :: {var, [], context} when var: atom(), context: atom()

Генерирует узел AST, представляющий переменную, заданную атомами var и context.

Обратите внимание, что эта переменная не уникальна. Если позже вам нужно получить доступ к той же переменной, вы можете снова вызвать var/2 с теми же аргументами. Используйте unique_var/2 для генерации уникальной переменной, которую нельзя переопределить.

Примеры

Для построения переменной требуется контекст. В большинстве случаев для сохранения гигиены контекст должен быть __MODULE__/0:

iex> Macro.var(:foo, __MODULE__)
{:foo, [], __MODULE__}

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

iex> Macro.var(:foo, nil)
{:foo, [], nil}