{xpath:string:query:attr:delimiter}

Description

Runs an XPath query against an XML or HTML string and returns the matching content. The first parameter is the markup to search - usually a remote page or feed loaded with the include command, but any literal XML/HTML string works. The second parameter is the XPath query (for example //title, //book[2]/title, or //book[@id="b2"]/author). The engine first tries a strict XML parse and falls back to a more tolerant HTML parse if that fails. By default only the first matching node is returned, as its text value. The optional third parameter changes what is returned from each match: give an attribute name to return that attribute (for example id or width), or the literal XML to return the matched node as inner markup. The optional fourth parameter is a delimiter: supply it to return all matching nodes joined by that delimiter instead of just the first - note the delimiter is appended after every match, including the last, so a trailing delimiter remains. A query that matches nothing returns an empty string; markup that cannot be parsed at all returns an error message. Because a colon separates parameters, an XPath axis written with a double colon such as following-sibling must be escaped in the query as following-sibling#:#: so the colons are not read as parameter separators.

Parameters

string required

The XML or HTML markup to search. Usually a remote page or feed loaded with the include command, but any literal XML or HTML string works. If empty, the command returns an empty string.

query required

The XPath query that selects the nodes to return, for example //title, //book[2], or //book[@id=b2]/author. A colon inside the query (such as an axis like following-sibling::) must be escaped as hash-colon so it is not read as a parameter separator. If empty, the command returns an empty string.

attr optional

What to return from each matching node. Empty (the default) returns the node text value. An attribute name (for example id or width) returns that attribute. The literal value XML returns the matched node as inner markup.

Allowed values (empty) = node text value; <attribute name> = that attribute; XML = the matched node as inner markup
delimiter optional default (first match only)

By default only the first matching node is returned. Supply a delimiter to return all matches joined by it. The delimiter is appended after every match, including the last, so a trailing delimiter remains. Leading and trailing spaces in the delimiter are preserved.

Examples

test{xpath:<books><book>Dune</book><book>Solaris</book></books>://book}
ExpectedDune
ActualDune
Returns the text of the first node matching the XPath query. The query //book selects every book element; with no delimiter, only the first match is returned.
test{xpath:<row><label>Date</label><value>2026</value></row>:/row/label/following-sibling#:#:value}
Expected2026
Actual2026
An XPath axis uses a double colon (following-sibling::value), but a colon separates xpath parameters. Escape each colon in the query as hash-colon so it is not read as a parameter separator: following-sibling hash-colon hash-colon value becomes following-sibling::value.
test{xpath:<rss><channel><item><title>First post</title></item><item><title>Second post</title></item></channel></rss>://item/title}
ExpectedFirst post
ActualFirst post
A typical scraping shape: pull one value out of a feed. In real templates the literal markup is replaced by include of a live URL, for example xpath of include of a feed URL with the query //item/title. The markup is inlined here so the example stays deterministic and never makes a network request.
test{xpath:<books><book>Dune</book><book>Solaris</book></books>://book::|}
ExpectedDune|Solaris|
ActualDune|Solaris|
Supply a fourth parameter (the attribute, third, is left empty here) to return every match joined by that delimiter instead of only the first. The delimiter is appended after each match, including the last, so the result ends with a trailing delimiter.
test[{xpath:<books><book>Dune</book></books>://magazine}]
Expected[]
Actual[]
A query that matches nothing returns an empty string. The square brackets here are literal, added only to make the empty result visible.
test{xpath:<ul><li>Apple</li><li>Pear</li><li>Plum</li></ul>://li[2]}
ExpectedPear
ActualPear
The same query works on HTML markup. When a strict XML parse fails the engine retries with a tolerant HTML parser, so ordinary web markup is queryable.
test{xpath:<books><book id="b2">Solaris</book></books>://book:id}
Expectedb2
Actualb2
Give an attribute name as the third parameter to return that attribute instead of the element text. Here the id attribute of the matched book is returned.
test{xpath:<books><book>Dune</book><book>Solaris</book></books>://book[2]}
ExpectedSolaris
ActualSolaris
An XPath positional predicate [2] picks the second matching element. XPath positions are 1-based.