XmlQuery (XmlQuery v1.0.0)

A concise API for querying XML. XML parsing is handled by Erlang/OTP’s built-in xmerl library.

We created a related library called HtmlQuery which has the same API but is used for querying HTML. You can read more about them in Querying HTML and XML in Elixir with HtmlQuery and XmlQuery.

Data types

All functions accept XML in the form of a string, an Xmerl.xml_attribute, an Xmerl.xml_document, an Xmerl.xml_element, an Xmler.xml_text, an XmlQuery.Element, or anything that implements the String.Chars protocol.

Query functions

`all/2`	return all elements matching the selector
`find/2`	return the first element that matches the selector
`find!/2`	return the only element that matches the selector, or raise

Extraction functions

`attr/2`	returns the attribute value as a string
`text/1`	returns the text contents as a single string

Parsing & utility functions

`parse/1`	parses XML into an `XmlQuery.Element`, `XmlQuery.Attribute`, or XmlQuery.Text.t()
`pretty/1`	prettifies XML

Alias

If you use XmlQuery a lot, you may want to alias it to the recommended shortcut "Xq":

alias XmlQuery, as: Hq

Summary

Types

xml()

xml_attribute()

xml_binary()

xml_document()

xml_element()

xml_text()

xpath()

Functions

all(xml, xpath)

Finds all elements in an XML document that match xpath, returning a list of records. Depending on the given xpath, the type of the record may be different.

attr(xml, attr)

Returns the value of attr from the outermost element of xml.

find(xml, xpath)

Finds the first element, attribute, or element text in xml that matches xpath.

find!(xml, xpath)

Like find/2 but raises unless exactly one node is found.

is_xml_struct(struct)

parse(node)

Parses an XML document using :xmerl_scan.string/2, returning an XmlQuery.Element struct.

pretty(node)

Returns xml as a prettified string.

text(xml)

Returns the text value of xml.

Types

xml()

@type xml() ::
  xml_binary()
  | xml_document()
  | xml_element()
  | XmlQuery.Element.t()
  | String.Chars.t()

xml_attribute()

@type xml_attribute() :: XmlQuery.Xmerl.xml_attribute()

xml_binary()

@type xml_binary() :: binary()

xml_document()

@type xml_document() :: XmlQuery.Xmerl.xml_document()

xml_element()

@type xml_element() :: XmlQuery.Xmerl.xml_element()

xml_text()

@type xml_text() :: XmlQuery.Xmerl.xml_text()

xpath()

@type xpath() :: binary() | charlist()

Functions

all(xml, xpath)

@spec all(xml(), xpath()) :: [XmlQuery.Element.t()]

Finds all elements in an XML document that match xpath, returning a list of records. Depending on the given xpath, the type of the record may be different.

iex> xml = ~s|<cart id="123"> <fruit name="apple" color="red"/> <fruit name="banana" color="yellow"/> </cart>|
iex> XmlQuery.all(xml, "//fruit") |> Enum.map(&to_string/1)
["<fruit name=\"apple\" color=\"red\"/>",
 "<fruit name=\"banana\" color=\"yellow\"/>"]

attr(xml, attr)

@spec attr(xml(), String.t()) :: XmlQuery.Attribute.t() | nil

Returns the value of attr from the outermost element of xml.

iex> xml = ~s|<cart id="123"> <fruit name="apple" color="red"/> <fruit name="banana" color="yellow"/> </cart>|
iex> XmlQuery.attr(xml, :id)
"123"

find(xml, xpath)

@spec find(xml(), xpath()) ::
  XmlQuery.Element.t() | XmlQuery.Attribute.t() | XmlQuery.Text.t() | nil

Finds the first element, attribute, or element text in xml that matches xpath.

iex> alias XmlQuery, as: Xq
iex> xml = """
...> <?xml version="1.0"?>
...> <root><child property="oldest" /><child property="youngest" /></root>
...> """
iex> %Xq.Element{name: :child, attributes: [%Xq.Attribute{value: ~c"oldest"}]} = Xq.find(xml, "//child")

find!(xml, xpath)

@spec find!(xml(), xpath()) ::
  XmlQuery.Element.t() | XmlQuery.Attribute.t() | XmlQuery.Text.t()

Like find/2 but raises unless exactly one node is found.

is_xml_struct(struct)

(macro)

parse(node)

@spec parse(xml()) ::
  XmlQuery.Element.t() | XmlQuery.Attribute.t() | XmlQuery.Text.t()

Parses an XML document using :xmerl_scan.string/2, returning an XmlQuery.Element struct.

Given an xml tuple that has already been created by :xmerl, wraps the tuple in an XmlQuery-specific struct.

iex> xml = """
...> <?xml version="1.0"?>
...> <root />
...> """
iex> %Xq.Element{name: :root} = XmlQuery.parse(xml)

iex> xml = """
...> <?xml version="1.0"?>
...> <root property="root-value" />
...> """
iex> %Xq.Attribute{name: :property, value: ~c"root-value"} = XmlQuery.find(xml, "//root/@property") |> XmlQuery.parse()

pretty(node)

@spec pretty(xml()) :: binary()

Returns xml as a prettified string.

Elements and text nodes are sorted and indented relative to parent elements.

text(xml)

@spec text(xml()) :: binary()

Returns the text value of xml.

iex> xml = "<name><first>Alice</first><middle>A.</middle><last>Aliceston</last></name>"
iex> XmlQuery.text(xml)
"Alice A. Aliceston"
iex> xml |> XmlQuery.find("//name/first") |> XmlQuery.text()
"Alice"