XmlQuery (XmlQuery v0.2.1)
A concise API for querying XML. XML parsing is handled by Erlang/OTP’s built-in xmerl library.
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
Functions
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.
Returns the value of attr
from the outermost element of xml
.
Finds the first element, attribute, or element text in xml
that matches xpath
.
Like find/2
but raises unless exactly one node is found.
Parses an XML document using :xmerl_scan.string/2
, returning an XmlQuery.Element
struct.
Returns xml
as a prettified string.
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()
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.
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)
Returns xml
as a prettified string.
Elements and text nodes are sorted and indented relative to parent elements.
text(xml)
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"