@spec children(t()) :: Enumerable.t(t() | Yex.XmlText.t())

Returns a stream of all child nodes of the XML element.

@spec delete(t(), integer(), integer()) :: :ok | :error

Deletes a range of child nodes starting at the specified index. Returns :ok on success, :error on failure.

@spec fetch(t(), integer()) :: {:ok, t() | Yex.XmlText.t()} | :error

Retrieves the child node at the specified index. Returns {:ok, node} if found, :error if index is out of bounds.

@spec fetch!(t(), integer()) :: t() | Yex.XmlText.t()

Similar to fetch/2 but raises ArgumentError if the index is out of bounds.

@spec first_child(t()) :: t() | Yex.XmlText.t() | nil

Returns the first child node of the XML element. Returns nil if the element has no children.

@spec get(t(), integer(), default :: term()) :: t() | Yex.XmlText.t() | term()

Gets a child node by index from the XML element, or returns the default value if the index is out of bounds.

Parameters

• xml_element - The XML element to query
• index - The index to look up
• default - The default value to return if index is out of bounds (defaults to nil)

Examples

iex> doc = Yex.Doc.new()
iex> xml = Yex.Doc.get_xml_fragment(doc, "xml")
iex> elem = Yex.XmlFragment.push_and_get(xml, Yex.XmlElementPrelim.empty("div"))
iex> Yex.XmlElement.push(elem, Yex.XmlTextPrelim.from("content"))
iex> text = Yex.XmlElement.get(elem, 0)
iex> match?(%Yex.XmlText{}, text)
true
iex> Yex.XmlElement.get(elem, 10)
nil
iex> Yex.XmlElement.get(elem, 10, :not_found)
:not_found

@spec get_attribute(t(), binary()) :: binary() | Yex.SharedType.t() | nil

Returns the value of the specified attribute. Returns nil if the attribute does not exist.

@spec get_attributes(t()) :: %{required(binary()) => binary() | Yex.SharedType.t()}

Returns a map of all attributes for this XML element.

@spec get_lazy(t(), integer(), fun :: (-> term())) :: t() | Yex.XmlText.t() | term()

Gets a child node by index from the XML element, or lazily evaluates the given function if the index is out of bounds. This is useful when the default value is expensive to compute and should only be evaluated when needed.

Parameters

• xml_element - The XML element to query
• index - The index to look up
• fun - A function that returns the default value (only called if index is out of bounds)

Examples

iex> doc = Yex.Doc.new()
iex> xml = Yex.Doc.get_xml_fragment(doc, "xml")
iex> elem = Yex.XmlFragment.push_and_get(xml, Yex.XmlElementPrelim.empty("div"))
iex> Yex.XmlElement.push(elem, Yex.XmlTextPrelim.from("Hello"))
iex> Yex.XmlElement.get_lazy(elem, 0, fn -> Yex.XmlElement.push_and_get(elem, Yex.XmlTextPrelim.from("Computed")) end) |> to_string()
"Hello"
iex> Yex.XmlElement.get_lazy(elem, 10, fn -> Yex.XmlElement.push_and_get(elem, Yex.XmlTextPrelim.from("Computed")) end) |> to_string()
"Computed"

Particularly useful with *_and_get functions for get-or-create patterns:

iex> doc = Yex.Doc.new()
iex> xml = Yex.Doc.get_xml_fragment(doc, "xml")
iex> elem = Yex.XmlFragment.push_and_get(xml, Yex.XmlElementPrelim.empty("div"))
iex> # Get existing child or create and return new one
iex> child = Yex.XmlElement.get_lazy(elem, 0, fn ->
...>   Yex.XmlElement.push_and_get(elem, Yex.XmlElementPrelim.empty("span"))
...> end)
iex> Yex.XmlElement.get_tag(child)
"span"

@spec get_tag(t()) :: binary() | nil

Returns the tag name of the XML element. Returns nil if the element has no tag.

@spec insert(t(), integer(), Yex.XmlElementPrelim.t() | Yex.XmlTextPrelim.t()) ::
  :ok | :error

Inserts a new child node at the specified index. Returns :ok on success, :error on failure.

@spec insert_after(
  t(),
  t() | Yex.XmlText.t(),
  Yex.XmlElementPrelim.t() | Yex.XmlTextPrelim.t()
) :: :ok | :error

Inserts a new child node after the specified reference node. If the reference node is not found, inserts at the beginning. Returns :ok on success, :error on failure.

@spec insert_after_and_get(
  t(),
  t() | Yex.XmlText.t(),
  Yex.XmlElementPrelim.t() | Yex.XmlTextPrelim.t()
) :: t() | Yex.XmlText.t()

Inserts a new child node after the specified reference node and returns the inserted node. If the reference node is not found, inserts at the beginning. Returns the inserted node on success, raises on failure.

@spec insert_and_get(t(), integer(), Yex.XmlElementPrelim.t() | Yex.XmlTextPrelim.t()) ::
  t() | Yex.XmlText.t()

Inserts a new child node at the specified index and returns the inserted node. Returns the inserted node on success, raises on failure.

@spec insert_attribute(t(), binary(), binary() | Yex.PrelimType.t()) :: :ok | :error

Adds or updates an attribute with the specified key and value. Returns :ok on success, :error on failure.

@spec length(t()) :: integer()

Returns the number of child nodes in the XML element.

@spec next_sibling(t()) :: t() | Yex.XmlText.t() | nil

The next sibling of this type. Is null if this is the last child of its parent.

@spec parent(t()) :: t() | Yex.XmlFragment.t() | nil

The parent that holds this type. Is null if this xml is a top-level XML type.

@spec prev_sibling(t()) :: t() | Yex.XmlText.t() | nil

The previous sibling of this type. Is null if this is the first child of its parent.

@spec push(t(), Yex.XmlElementPrelim.t() | Yex.XmlTextPrelim.t()) :: :ok | :error

Appends a new child node at the end of the children list. Returns :ok on success, :error on failure.

@spec push_and_get(t(), Yex.XmlElementPrelim.t() | Yex.XmlTextPrelim.t()) ::
  t() | Yex.XmlText.t()

Appends a new child node at the end of the children list and returns the inserted node. Returns the inserted node on success, raises on failure.

@spec remove_attribute(t(), binary()) :: :ok | :error

Removes the attribute with the specified key. Returns :ok on success, :error on failure.

@spec unshift(t(), Yex.XmlElementPrelim.t() | Yex.XmlTextPrelim.t()) :: :ok | :error

Inserts a new child node at the beginning of the children list. Returns :ok on success, :error on failure.