1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/xml_find.R
3\name{xml_find_all}
4\alias{xml_find_all}
5\alias{xml_find_all.xml_nodeset}
6\alias{xml_find_first}
7\alias{xml_find_num}
8\alias{xml_find_chr}
9\alias{xml_find_lgl}
10\alias{xml_find_one}
11\title{Find nodes that match an xpath expression.}
12\usage{
13xml_find_all(x, xpath, ns = xml_ns(x), ...)
14
15\method{xml_find_all}{xml_nodeset}(x, xpath, ns = xml_ns(x), flatten = TRUE, ...)
16
17xml_find_first(x, xpath, ns = xml_ns(x))
18
19xml_find_num(x, xpath, ns = xml_ns(x))
20
21xml_find_chr(x, xpath, ns = xml_ns(x))
22
23xml_find_lgl(x, xpath, ns = xml_ns(x))
24}
25\arguments{
26\item{x}{A document, node, or node set.}
27
28\item{xpath}{A string containing an xpath (1.0) expression.}
29
30\item{ns}{Optionally, a named vector giving prefix-url pairs, as produced
31by \code{\link[=xml_ns]{xml_ns()}}. If provided, all names will be explicitly
32qualified with the ns prefix, i.e. if the element \code{bar} is defined
33in namespace \code{foo}, it will be called \code{foo:bar}. (And
34similarly for attributes). Default namespaces must be given an explicit
35name. The ns is ignored when using \code{\link[=xml_name<-]{xml_name<-()}} and
36\code{\link[=xml_set_name]{xml_set_name()}}.}
37
38\item{...}{Further arguments passed to or from other methods.}
39
40\item{flatten}{A logical indicating whether to return a single, flattened
41nodeset or a list of nodesets.}
42}
43\value{
44\code{xml_find_all} returns a nodeset if applied to a node, and a nodeset
45or a list of nodesets if applied to a nodeset. If there are no matches,
46the nodeset(s) will be empty. Within each nodeset, the result will always
47be unique; repeated nodes are automatically de-duplicated.
48
49\code{xml_find_first} returns a node if applied to a node, and a nodeset
50if applied to a nodeset. The output is \emph{always} the same size as
51the input. If there are no matches, \code{xml_find_first} will return a
52missing node; if there are multiple matches, it will return the first
53only.
54
55\code{xml_find_num}, \code{xml_find_chr}, \code{xml_find_lgl} return
56numeric, character and logical results respectively.
57}
58\description{
59Xpath is like regular expressions for trees - it's worth learning if
60you're trying to extract nodes from arbitrary locations in a document.
61Use \code{xml_find_all} to find all matches - if there's no match you'll
62get an empty result. Use \code{xml_find_first} to find a specific match -
63if there's no match you'll get an \code{xml_missing} node.
64}
65\section{Deprecated functions}{
66
67\code{xml_find_one()} has been deprecated. Instead use
68\code{xml_find_first()}.
69}
70
71\examples{
72x <- read_xml("<foo><bar><baz/></bar><baz/></foo>")
73xml_find_all(x, ".//baz")
74xml_path(xml_find_all(x, ".//baz"))
75
76# Note the difference between .// and //
77# //  finds anywhere in the document (ignoring the current node)
78# .// finds anywhere beneath the current node
79(bar <- xml_find_all(x, ".//bar"))
80xml_find_all(bar, ".//baz")
81xml_find_all(bar, "//baz")
82
83# Find all vs find one -----------------------------------------------------
84x <- read_xml("<body>
85  <p>Some <b>text</b>.</p>
86  <p>Some <b>other</b> <b>text</b>.</p>
87  <p>No bold here!</p>
88</body>")
89para <- xml_find_all(x, ".//p")
90
91# By default, if you apply xml_find_all to a nodeset, it finds all matches,
92# de-duplicates them, and returns as a single nodeset. This means you
93# never know how many results you'll get
94xml_find_all(para, ".//b")
95
96# If you set flatten to FALSE, though, xml_find_all will return a list of
97# nodesets, where each nodeset contains the matches for the corresponding
98# node in the original nodeset.
99xml_find_all(para, ".//b", flatten = FALSE)
100
101# xml_find_first only returns the first match per input node. If there are 0
102# matches it will return a missing node
103xml_find_first(para, ".//b")
104xml_text(xml_find_first(para, ".//b"))
105
106# Namespaces ---------------------------------------------------------------
107# If the document uses namespaces, you'll need use xml_ns to form
108# a unique mapping between full namespace url and a short prefix
109x <- read_xml('
110 <root xmlns:f = "http://foo.com" xmlns:g = "http://bar.com">
111   <f:doc><g:baz /></f:doc>
112   <f:doc><g:baz /></f:doc>
113 </root>
114')
115xml_find_all(x, ".//f:doc")
116xml_find_all(x, ".//f:doc", xml_ns(x))
117}
118\seealso{
119\code{\link[=xml_ns_strip]{xml_ns_strip()}} to remove the default namespaces
120}
121