Характеристики

camelize(String.t()) :: String.t()

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

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

Примеры

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

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

iex> Macro.camelize("API.V1")
"API.V1"
iex> Macro.camelize("API_SPEC")
"API_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

Характеристики

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.

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

Сравнение с Kernel.SpecialForms.quote/2

Функция escape/2 иногда путают с Kernel.SpecialForms.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)
{:a, :b, :c}

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

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

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

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

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

Расширяются следующие элементы:

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

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

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

Характеристики

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

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

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

Примеры

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

Характеристики

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

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

Характеристики

pipe(t(), t(), integer()) :: t()

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

Характеристики

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

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

Характеристики

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

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

Характеристики

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

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

Характеристики

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

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

Характеристики

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

Характеристики

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

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

Характеристики

struct!(module, Macro.Env.t()) :: %module{} when module: module()

Расширяет структуру, заданную module, в заданной env.

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

Будет выброшено исключение CompileError, если структура недоступна.

Характеристики

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

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

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

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

Примеры

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

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

Характеристики

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

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

Спецификации

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

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

Если задан атом, предполагается, что это модуль 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"

Спецификации

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 и других), которые получают необработанную, неэкранированную строку.

Примеры

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

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

Спецификации

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

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

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

Карта

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

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, символ не экранирован, и обратный слэш сохраняется в строке.

Шестнадцатеричные и кодовые точки Unicode будут экранированы, если функция карты возвращает true для ?x. Кодовые точки Unicode, если функция карты возвращает true для ?u.

Примеры

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

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

Спецификации

unpipe(t()) :: [t()]

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

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

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

В примере выше, конвейер |> – это самый правый конвейер; 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)).

Спецификации

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, [], []}

Спецификации

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}}

Спецификации

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

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

Примеры

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

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

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

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