SimpleForm.Element (SimpleForm v1.0.10)

View Source

SimpleForm.Element implements functions for manipulating SimpleForm elements, such as finding one by name in a list of elements or in the children of another element.

Summary

Functions

Get the attributes of an element.

Get the children of an element.

Find an element by name in a list of elements.

Find multiple elements by their names in a list of elements. The order and placement of the elements in the list is preserved w.r.t. the given names.

Recursively find the first element to match the given predicate, or return the given default value.

Get the name of an element.

Recursively get the text content of an element or list of elements.

Functions

attrs(arg1)

@spec attrs(element :: nil) :: nil
@spec attrs(element :: SimpleForm.element()) :: SimpleForm.attribute()

Get the attributes of an element.

Examples

iex> SimpleForm.Element.attrs(nil)
nil
iex> SimpleForm.Element.attrs({"w:p", [], ["some text"]})
[]
iex> SimpleForm.Element.attrs({"w:p", [{"id", "1"}], ["some text"]})
[{"id", "1"}]

children(arg1)

@spec children(element :: nil) :: nil
@spec children(element :: SimpleForm.element()) :: SimpleForm.content()

Get the children of an element.

Examples

iex> SimpleForm.Element.children(nil)
nil
iex> SimpleForm.Element.children({"w:p", [], []})
[]
iex> SimpleForm.Element.children({"w:p", [], ["some text"]})
["some text"]
iex> SimpleForm.Element.children({"w:p", [{"id", "1"}], ["some text", "more text"]})
["some text", "more text"]

find_by_name(elements, name, default \\ nil, opts \\ [recursive: false])

@spec find_by_name(
  elements :: [SimpleForm.element()],
  name :: String.t(),
  default :: default,
  opts :: [{:recursive, boolean()}] | nil
) :: SimpleForm.element() | default
when default: var

Find an element by name in a list of elements.

Options

  • recursive (boolean): If true, the function will perform a recursive, depth-first search through the children of each element in the list.

Examples

By default, SimpleForm.Element.find_by_name/4 only searches the list's elements.

iex> SimpleForm.Element.find_by_name([{"w:p", [], []}, {"w:tbl", [], []}], "w:tbl")
{"w:tbl", [], []}
iex> SimpleForm.Element.find_by_name([{"w:p", [], []}, {"w:tbl", [], []}], "w:sdt")
nil
iex> SimpleForm.Element.find_by_name([{"w:p", [], []}, {"w:tbl", [], []}], "w:sdt", {"w:sdt", [], []})
{"w:sdt", [], []}

For a recursive, depth-first search through the children of each element in the list, set the recursive option to true.

iex> SimpleForm.Element.find_by_name([{"w:p", [], [{"w:r", [], ["some text"]}]}], "w:r", nil, recursive: true)
{"w:r", [], ["some text"]}
iex> SimpleForm.Element.find_by_name([{"w:p", [], [{"w:r", [], ["some text"]}]}], "w:sdt", nil, recursive: true)
nil
iex> SimpleForm.Element.find_by_name([{"w:p", [], [{"w:r", [], ["some text"]}, "  ", {"w:sdt", [], []}]}], "w:sdt", nil, recursive: true)
{"w:sdt", [], []}
iex> SimpleForm.Element.find_by_name([{"w:p", [], [{"w:r", [], ["first text"]}]}, "  ", {"w:p", [], [{"w:r", [], ["second text"]}]}], "w:r", nil, recursive: true)
{"w:r", [], ["first text"]}

Note: the option recursive: true requires setting a default value explicitly, otherwise this option is assumed as the default value.

iex> SimpleForm.Element.find_by_name([{"w:p", [], [{"w:r", [], ["some text"]}]}], "w:r", recursive: true)
[recursive: true]
iex> SimpleForm.Element.find_by_name([{"w:p", [], [{"w:r", [], ["some text"]}]}], "w:r", recursive: false)
[recursive: false]

find_many_by_name(elements, names)

@spec find_many_by_name(
  elements :: [SimpleForm.element()],
  names :: [String.t()]
) :: [SimpleForm.element() | nil]

Find multiple elements by their names in a list of elements. The order and placement of the elements in the list is preserved w.r.t. the given names.

This function is more performant than calling find_by_name/3 multiple times, as it only iterates over elements once.

Examples

iex> elements = [{"w:p", [], [{"w:r", [], ["some text"]}]}, {"w:tbl", [], []}]
iex> SimpleForm.Element.find_many_by_name(elements, ["w:p"])
[{"w:p", [], [{"w:r", [], ["some text"]}]}]
iex> SimpleForm.Element.find_many_by_name(elements, ["w:r"])
[nil]
iex> SimpleForm.Element.find_many_by_name(elements, ["w:tbl", "w:p"])
[{"w:tbl", [], []}, {"w:p", [], [{"w:r", [], ["some text"]}]}]
iex> SimpleForm.Element.find_many_by_name(elements, ["w:tbl", "w:r"])
[{"w:tbl", [], []}, nil]
iex> SimpleForm.Element.find_many_by_name(elements, ["w:sdt", "w:p"])
[nil, {"w:p", [], [{"w:r", [], ["some text"]}]}]

find_recursive(content, predicate)

@spec find_recursive(element | [element], (element -> boolean())) :: element | nil
when element: SimpleForm.element()

Recursively find the first element to match the given predicate, or return the given default value.

This function performs a depth-first search through the children of an element or list of elements, and returns the first element for which the predicate returns true.

Examples

iex> SimpleForm.Element.find_recursive(
...>   [{"w:p", [], []}, {"w:r", [], ["some text"]}],
...>   fn element -> element |> SimpleForm.Element.name() === "w:r" end
...> )
{"w:r", [], ["some text"]}
iex> SimpleForm.Element.find_recursive(
...>   [{"w:p", [], [{"w:r", [{"id", "1"}], ["text"]}]}, {"w:r", [{"id", "2"}], ["text"]}],
...>   fn element -> element |> SimpleForm.Element.name() === "w:r" end
...> )
{"w:r", [{"id", "1"}], ["text"]}
iex> SimpleForm.Element.find_recursive([], fn _ -> true end)
nil
iex> SimpleForm.Element.find_recursive([], fn _ -> true end, "test")
"test"
iex> SimpleForm.Element.find_recursive([{"w:p", [], ["text"]}], fn _ -> false end)
nil
iex> SimpleForm.Element.find_recursive([{"w:p", [], ["text"]}], fn _ -> false end, "default")
"default"

find_recursive(elements, predicate, default)

@spec find_recursive([element], (element -> boolean()), default) :: element | default
when element: SimpleForm.element(), default: var

name(arg1)

@spec name(element :: nil) :: nil
@spec name(element :: SimpleForm.element()) :: String.t()

Get the name of an element.

Examples

iex> SimpleForm.Element.name({"w:p", [], []})
"w:p"
iex> SimpleForm.Element.name(nil)
nil

text(text)

@spec text(nil) :: nil
@spec text(String.t()) :: String.t()
@spec text(SimpleForm.element() | [SimpleForm.element()]) :: String.t()

Recursively get the text content of an element or list of elements.

Examples

iex> SimpleForm.Element.text(nil)
nil
iex> SimpleForm.Element.text("some text")
"some text"
iex> SimpleForm.Element.text({"w:p", [], []})
""
iex> SimpleForm.Element.text([{"w:p", [], []}, {"w:tbl", [], []}])
""
iex> SimpleForm.Element.text({"w:p", [], ["some text"]})
"some text"
iex> SimpleForm.Element.text([{"w:p", [], ["some text", " other text."]}, {"w:tbl", [], ["more text"]}, {"w:tbl", [], []}])
"some text other text.more text"
iex> SimpleForm.Element.text([{"w:p", [], ["some text", " other text.", " "]}, {"w:tbl", [], ["more text"]}, {"w:tbl", [], []}])
"some text other text. more text"