SimpleForm.Element (SimpleForm v1.0.14)
View SourceSimpleForm.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
@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"}]
@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"]
@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]
@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"]}]}]
@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"
@spec find_recursive([element], (element -> boolean()), default) :: element | default when element: SimpleForm.element(), default: var
@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
@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"