exfmt v0.4.0 Exfmt.Algebra
A set of functions for creating and manipulating algebra documents.
This module implements the functionality described in “Strictly Pretty” (2000) by Christian Lindig, with a few extensions detailed below.
It serves an alternative printer to the one defined in
Inspect.Algebra
, which is part of the Elixir standard library
but does not entirely conform to the algorithm described by Christian
Lindig in a way that makes it unsuitable for use in ExFmt.
Extensions
nest/1
can take the atom:current
instead of an integer. With this value the formatter will set the indentation level to the current column position.break/2
allows the user to specify a string that can be rendered in the document when the break is rendering in a flat layout. This was added to insert trailing newlines.
Link to this section Summary
Functions
Returns a document entity with the " "
string as break
Returns a document entity with the " "
string as break
Returns a document entity representing a break based on the given
string
Concatenates a list of documents returning a new document
Concatenates two document entities returning a new document
Formats a given document for a given width
Glues two documents together inserting " "
as a break between them
Glues two documents (doc1
and doc2
) together inserting the given
break break_string
between them
Insert a new line
Nests the given document at the given level
Maps and glues a collection of items
Converts an Elixir term to an algebra document
according to the Inspect
protocol
Link to this section Types
t :: :doc_nil | :doc_line | doc_cons | doc_nest | doc_break | doc_group | binary
Link to this section Functions
Returns a document entity with the " "
string as break.
See break/2
for more information.
Returns a document entity with the " "
string as break.
See break/2
for more information.
Returns a document entity representing a break based on the given
string
.
This break can be rendered as a broken
followed by a linebreak and or as
the given unbroken
, depending on the mode
of the chosen layout or the
provided separator.
Examples
Let’s create a document by concatenating two strings with a break between them:
iex> doc = Inspect.Algebra.concat(["a", Inspect.Algebra.break("\t"), "b"])
iex> Inspect.Algebra.format(doc, 80)
["a", "\t", "b"]
Notice the break was represented with the given string, because we didn’t reach a line limit. Once we do, it is replaced by a newline:
iex> break = Inspect.Algebra.break("\t")
iex> doc = Inspect.Algebra.concat([String.duplicate("a", 20), break, "b"])
iex> Inspect.Algebra.format(doc, 10)
["aaaaaaaaaaaaaaaaaaaa", "\n", "b"]
Concatenates a list of documents returning a new document.
Examples
iex> doc = concat(["a", "b", "c"])
...> format(doc, 80)
["a", "b", "c"]
Concatenates two document entities returning a new document.
Examples
iex> doc = concat("hello", "world")
...> format(doc, 80)
["hello", "world"]
Formats a given document for a given width.
Takes the maximum width and a document to print as its arguments and returns an IO data representation of the best layout for the document to fit in the given width.
Examples
iex> doc = glue("hello", " ", "world")
iex> format(doc, 30) |> IO.iodata_to_binary()
"hello world"
iex> format(doc, 10) |> IO.iodata_to_binary()
"hello\nworld"
Glues two documents together inserting " "
as a break between them.
This means the two documents will be separated by " "
in case they
fit in the same line. Otherwise a line break is used.
Examples
iex> doc = glue("hello", "world")
...> format(doc, 80)
["hello", " ", "world"]
Glues two documents (doc1
and doc2
) together inserting the given
break break_string
between them.
For more information on how the break is inserted, see break/1
.
Examples
iex> doc = glue("hello", "\t", "world")
...> format(doc, 80)
["hello", "\t", "world"]
Insert a new line
Nests the given document at the given level
.
Nesting will be appended to the line breaks.
Examples
iex> doc = Inspect.Algebra.nest(Inspect.Algebra.glue("hello", "world"), 5)
iex> Inspect.Algebra.format(doc, 5)
["hello", "\n ", "world"]
Maps and glues a collection of items.
It uses the given left
and right
documents as surrounding and the
separator document separator
to separate items in docs
.
Examples
iex> doc = surround_many("[", Enum.to_list(1..5), "]", &to_string/1)
iex> format(doc, 5) |> IO.iodata_to_binary
"[1,\n 2,\n 3,\n 4,\n 5]"
Converts an Elixir term to an algebra document
according to the Inspect
protocol.