Inspect.Algebra

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

Этот модуль реализует функциональность, описанную в “Strictly Pretty” (2000) by Christian Lindig с небольшими дополнениями, такими как поддержка бинарных узлов и режим разрыва, который максимизирует использование горизонтального пространства.

iex> Inspect.Algebra.empty()
:doc_nil

iex> "foo"
"foo"

С помощью функций в этом модуле мы можем конкатенировать различные элементы и отобразить их:

iex> doc = Inspect.Algebra.concat(Inspect.Algebra.empty(), "foo")
iex> Inspect.Algebra.format(doc, 80)
["foo"]

Функции nest/2, space/2 и line/2 помогают объединить документ в жёсткую структуру. Однако алгебра документов становится интересной при использовании функций, таких как glue/3 и group/1. Glue вставляет разрыв между двумя документами. Группа указывает документ, который должен поместиться в текущей строке, в противном случае разрывы отображаются как новые строки. Давайте склеим два документа с разрывом, сгруппируем их и отобразим:

iex> doc = Inspect.Algebra.glue("a", " ", "b")
iex> doc = Inspect.Algebra.group(doc)
iex> Inspect.Algebra.format(doc, 80)
["a", " ", "b"]

Обратите внимание, что разрыв был представлен как есть, потому что мы не достигли предела строки. Как только мы это сделаем, он заменяется новой строкой:

iex> doc = Inspect.Algebra.glue(String.duplicate("a", 20), " ", "b")
iex> doc = Inspect.Algebra.group(doc)
iex> Inspect.Algebra.format(doc, 10)
["aaaaaaaaaaaaaaaaaaaa", "\n", "b"]

Этот модуль использует размер в байтах для вычисления оставшегося пространства. Если ваш документ содержит строки, то их необходимо заключить в string/1, который затем полагается на String.length/1 для предварительного вычисления размера документа.

Наконец, этот модуль также содержит функции, связанные с Elixir, немного связанные с форматированием Elixir, такие как to_doc/2.

Детали реализации

Реализация Inspect.Algebra основана на статье Strictly Pretty от Lindig, которая основана на предыдущих алгоритмах красивой печати, но адаптирована для строгих языков, таких как Elixir. Основная идея в статье — использование явных групп документов, которые отображаются как плоские (разрывы как пробелы) или как разрывы (разрывы как новые строки).

Эта реализация предоставляет два типа разрывов: :strict и :flex. Когда группа не помещается, все строгие разрывы обрабатываются как новые строки. Гибкие разрывы, однако, переоцениваются при каждом появлении и могут по-прежнему отображаться как плоские. Более подробную информацию см. в break/1 и flex_break/1.

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

Резюме

Типы

t()

Функции

break(string \\ " "): Возвращает документ-разрыв на основе заданного string
collapse_lines(max): Сжимает любые новые строки и пробелы после этого узла, выведя до max новых строк
color(doc, color_key, opts): Окрашивает документ, если color_key имеет цвет в параметрах
concat(docs): Конкатенирует список документов, возвращая новый документ
concat(doc1, doc2): Конкатенирует два сущности документов, возвращая новый документ
container_doc(left, collection, right, inspect, fun, opts \\ []): Оборачивает collection в left и right в соответствии с лимитом и содержимым
empty(): Возвращает сущность документа, используемую для представления пустоты
flex_break(string \\ " "): Возвращает документ гибкого разрыва на основе заданного string
flex_glue(doc1, break_string \\ " ", doc2): Склеивает два документа (doc1 и doc2) вставляя flex_break/1, заданный break_string между ними
fold_doc(docs, folder_fun): Складывает список документов в документ с помощью заданной функции слияния
force_unfit(doc): Принудительно делает текущую группу непригодной
format(doc, width): Форматирует данный документ для заданной ширины
glue(doc1, break_string \\ " ", doc2): Склеивает два документа (doc1 и doc2) вставляя заданный разрыв break_string между ними
group(doc, mode \\ :self): Возвращает группу, содержащую указанный документ doc
is_doc(doc)
line(): Обязательный разрыв строки
line(doc1, doc2): Вставляет обязательный разрыв строки между двумя документами
nest(doc, level, mode \\ :always): Вкладывает данный документ на заданном level
next_break_fits(doc, mode \\ :enabled): Рассматривает следующий разрыв как подходящий
space(doc1, doc2): Вставляет обязательный одиночный пробел между двумя документами
string(string): Создаёт документ, представленный строкой
to_doc(term, opts): Преобразует термин Elixir в документ алгебры в соответствии с протоколом Inspect

Типы

t()

t() ::
  binary()
  | :doc_nil
  | :doc_line
  | doc_string()
  | doc_cons()
  | doc_nest()
  | doc_break()
  | doc_group()
  | doc_color()
  | doc_force()
  | doc_fits()
  | doc_collapse()

Функции

break(string \\ " ")

break(binary()) :: doc_break()

Возвращает документ-разрыв на основе заданного string.

Этот разрыв может быть отображён как разрыв строки или как заданный string, в зависимости от mode выбранного макета.

Примеры

Давайте создадим документ, конкатенируя две строки с разрывом между ними:

iex> doc = Inspect.Algebra.concat(["a", Inspect.Algebra.break("\t"), "b"])
iex> Inspect.Algebra.format(doc, 80)
["a", "\t", "b"]

Обратите внимание, что разрыв был представлен заданной строкой, потому что мы не достигли предела строки. Как только мы это сделаем, он заменяется новой строкой:

iex> break = Inspect.Algebra.break("\t")
iex> doc = Inspect.Algebra.concat([String.duplicate("a", 20), break, "b"])
iex> doc = Inspect.Algebra.group(doc)
iex> Inspect.Algebra.format(doc, 10)
["aaaaaaaaaaaaaaaaaaaa", "\n", "b"]

collapse_lines(max) (since 1.6.0)

collapse_lines(pos_integer()) :: doc_collapse()

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

color(doc, color_key, opts) (since 1.4.0)

color(t(), Inspect.Opts.color_key(), Inspect.Opts.t()) :: doc_color()

Окрашивает документ, если color_key имеет цвет в параметрах.

concat(docs)

concat([t()]) :: t()

Конкатенирует список документов, возвращая новый документ.

Примеры

iex> doc = Inspect.Algebra.concat(["a", "b", "c"])
iex> Inspect.Algebra.format(doc, 80)
["a", "b", "c"]

concat(doc1, doc2)

concat(t(), t()) :: t()

Конкатенирует два сущности документов, возвращая новый документ.

Примеры

iex> doc = Inspect.Algebra.concat("hello", "world")
iex> Inspect.Algebra.format(doc, 80)
["hello", "world"]

container_doc(left, collection, right, inspect, fun, opts \\ []) (since 1.6.0)

container_doc(
  t(),
  [any()],
  t(),
  Inspect.Opts.t(),
  (term(), Inspect.Opts.t() -> t()),
  keyword()
) :: t()

Оборачивает collection в left и right в соответствии с лимитом и содержимым.

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

Лимит в заданном Inspect.Opts соблюдается, и при достижении этого лимита эта функция прекращает обработку и выводит "..." вместо.

Параметры

:separator - разделитель, используемый между каждым документом
:break - Если :strict, всегда вставлять разрыв между каждым элементом. Если :flex, разрывы вставлять только по необходимости. Если :maybe, выбирает :flex только если все элементы являются текстовыми, в противном случае :strict

Примеры

iex> doc = Inspect.Algebra.container_doc("[", Enum.to_list(1..5), "]",
...>         %Inspect.Opts{limit: :infinity}, fn i, _opts -> to_string(i) end)
iex> Inspect.Algebra.format(doc, 5) |> IO.iodata_to_binary()
"[1,\n 2,\n 3,\n 4,\n 5]"

iex> doc = Inspect.Algebra.container_doc("[", Enum.to_list(1..5), "]",
...>         %Inspect.Opts{limit: 3}, fn i, _opts -> to_string(i) end)
iex> Inspect.Algebra.format(doc, 20) |> IO.iodata_to_binary()
"[1, 2, 3, ...]"

iex> doc = Inspect.Algebra.container_doc("[", Enum.to_list(1..5), "]",
...>         %Inspect.Opts{limit: 3}, fn i, _opts -> to_string(i) end, separator: "!")
iex> Inspect.Algebra.format(doc, 20) |> IO.iodata_to_binary()
"[1! 2! 3! ...]"

empty()

empty() :: :doc_nil

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

Примеры

iex> Inspect.Algebra.empty()
:doc_nil

flex_break(string \\ " ") (since 1.6.0)

flex_break(binary()) :: doc_break()

Возвращает документ гибкого разрыва на основе заданного string.

Гибкий разрыв всё ещё вызывает разрыв группы, как break/1, но переоценивается при отображении документа.

Например, рассмотрим документ группы, представленный как [1, 2, 3], где пробел после каждой запятой является разрывом. Когда документ выше не помещается на одной строке, все разрывы активируются, что приводит к отображению документа как:

[1,
 2,
 3]

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

[1, 2,
 3]

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

Эта функция используется container_doc/4 и дружественными функциями для определения максимального количества записей в одной строке.

flex_glue(doc1, break_string \\ " ", doc2) (с 1.6.0)

flex_glue(t(), binary(), t()) :: t()

Склеивает два документа (doc1 и doc2) с вставкой flex_break/1, заданного break_string между ними.

Эта функция используется container_doc/6 и дружественными функциями для определения максимального количества записей в одной строке.

fold_doc(docs, folder_fun)

fold_doc([t()], (t(), t() -> t())) :: t()

Складывает список документов в один документ, используя заданную функцию складывания.

Список документов складывается «справа»; в этом отношении эта функция похожа на List.foldr/3, за исключением того, что она не ожидает начального аккумулятора и использует последний элемент docs в качестве начального аккумулятора.

Примеры

iex> docs = ["A", "B", "C"]
iex> docs = Inspect.Algebra.fold_doc(docs, fn(doc, acc) ->
...>   Inspect.Algebra.concat([doc, "!", acc])
...> end)
iex> Inspect.Algebra.format(docs, 80)
["A", "!", "B", "!", "C"]

force_unfit(doc) (с 1.6.0)

force_unfit(t()) :: doc_force()

Принудительно делает текущую группу непригодной.

format(doc, width)

format(t(), non_neg_integer() | :infinity) :: iodata()

Форматирует данный документ для заданной ширины.

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

Документ начинается плоским (без разрывов), пока не найдена группа.

Примеры

iex> doc = Inspect.Algebra.glue("hello", " ", "world")
iex> doc = Inspect.Algebra.group(doc)
iex> doc |> Inspect.Algebra.format(30) |> IO.iodata_to_binary()
"hello world"
iex> doc |> Inspect.Algebra.format(10) |> IO.iodata_to_binary()
"hello\nworld"

glue(doc1, break_string \\ " ", doc2)

glue(t(), binary(), t()) :: t()

Склеивает два документа (doc1 и doc2) с вставкой заданного разрыва break_string между ними.

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

Примеры

iex> doc = Inspect.Algebra.glue("hello", "world")
iex> Inspect.Algebra.format(doc, 80)
["hello", " ", "world"]

iex> doc = Inspect.Algebra.glue("hello", "\t", "world")
iex> Inspect.Algebra.format(doc, 80)
["hello", "\t", "world"]

group(doc, mode \\ :self)

group(t(), :self | :inherit) :: doc_group()

Возвращает группу, содержащую указанный документ doc.

Документы в группе пытаются отображаться вместе в соответствии с возможностями рендерера.

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

Примеры

iex> doc = Inspect.Algebra.group(
...>   Inspect.Algebra.concat(
...>     Inspect.Algebra.group(
...>       Inspect.Algebra.concat(
...>         "Hello,",
...>         Inspect.Algebra.concat(
...>           Inspect.Algebra.break,
...>           "A"
...>         )
...>       )
...>     ),
...>     Inspect.Algebra.concat(
...>       Inspect.Algebra.break,
...>       "B"
...>     )
...> ))
iex> Inspect.Algebra.format(doc, 80)
["Hello,", " ", "A", " ", "B"]
iex> Inspect.Algebra.format(doc, 6)
["Hello,", "\n", "A", "\n", "B"]

is_doc(doc) (макрос)

line() (с 1.6.0)

line() :: t()

Обязательный разрыв строки.

Группа с разрывами строк поместится, если все строки в группе поместятся.

Примеры

iex> doc =
...>   Inspect.Algebra.concat(
...>     Inspect.Algebra.concat(
...>       "Hughes",
...>       Inspect.Algebra.line()
...>     ), "Wadler"
...>   )
iex> Inspect.Algebra.format(doc, 80)
["Hughes", "\n", "Wadler"]

line(doc1, doc2)

line(t(), t()) :: t()

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

См. line/1.

Примеры

iex> doc = Inspect.Algebra.line("Hughes", "Wadler")
iex> Inspect.Algebra.format(doc, 80)
["Hughes", "\n", "Wadler"]

nest(doc, level, mode \\ :always)

nest(t(), non_neg_integer() | :cursor | :reset, :always | :break) ::
  doc_nest()

Вкладывает данный документ на заданный level.

Если level является целым числом, это отступ, добавляемый к разрывам строк при их появлении. Если уровень равен :cursor, текущая позиция «курсора» в документе становится вложенностью. Если уровень равен :reset, он устанавливается обратно в 0.

mode может быть :always, что означает, что вложение всегда происходит, или :break, что означает, что вложение происходит только внутри группы, которая была разорвана.

Примеры

iex> doc = Inspect.Algebra.nest(Inspect.Algebra.glue("hello", "world"), 5)
iex> doc = Inspect.Algebra.group(doc)
iex> Inspect.Algebra.format(doc, 5)
["hello", "\n     ", "world"]

next_break_fits(doc, mode \\ :enabled) (с 1.6.0)

next_break_fits(t(), :enabled | :disabled) :: doc_fits()

Рассматривает следующий разрыв как подходящий.

mode может быть :enabled или :disabled. При :enabled, документ будет рассматриваться как подходящий, как только он найдёт следующий разрыв, фактически отменяя разрыв. Он также проигнорирует любые force_unfit/1 при поиске следующего разрыва.

При отключении он ведёт себя как обычно и проигнорирует любые дальнейшие инструкции next_break_fits/2.

Примеры

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

some_function_call(%{..., key: value, ...})

Теперь представьте, что этот код не помещается в строку. Форматировщик кода вводит разрывы внутри ( и ) и внутри %{ и }. Поэтому документ будет разбит как:

some_function_call(
  %{
    ...,
    key: value,
    ...
  }
)

Форматировщик оборачивает алгебраический документ, представляющий карту, в next_break_fits/1, так что код отформатирован как:

some_function_call(%{
  ...,
  key: value,
  ...
})

space(doc1, doc2)

space(t(), t()) :: t()

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

Примеры

iex> doc = Inspect.Algebra.space("Hughes", "Wadler")
iex> Inspect.Algebra.format(doc, 5)
["Hughes", " ", "Wadler"]

string(string) (с 1.6.0)

string(String.t()) :: doc_string()

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

Хотя Inspect.Algebra принимает двоичные данные как документы, они подсчитываются по размеру двоичных данных. С другой стороны, документы string измеряются в терминах графем по отношению к размеру документа.

Примеры

Следующий документ имеет 10 байт, и поэтому он не форматируется до ширины 9 без разрывов:

iex> doc = Inspect.Algebra.glue("olá", " ", "mundo")
iex> doc = Inspect.Algebra.group(doc)
iex> Inspect.Algebra.format(doc, 9)
["olá", "\n", "mundo"]

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

iex> string = Inspect.Algebra.string("olá")
iex> doc = Inspect.Algebra.glue(string, " ", "mundo")
iex> doc = Inspect.Algebra.group(doc)
iex> Inspect.Algebra.format(doc, 9)
["olá", " ", "mundo"]

to_doc(term, opts)

to_doc(any(), Inspect.Opts.t()) :: t()

Преобразует термин Elixir в алгебраический документ в соответствии с протоколом Inspect.

© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.7.4/Inspect.Algebra.html