# XML<no value>
// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4

[cols="1^,1^,1^",options=header]
|===
| source | condition | target
| &#10004; | &#10004; | &#10004;
|===

== Description

The `xml` resource reads and writes a single node in an XML document, located with an link:https://www.w3.org/TR/1999/REC-xpath-19991116/[XPath] query. It is most often used against a Maven `pom.xml`.

**source**::
Returns the text content of the node matched by `path`.

**condition**::
Checks that the node holds `value`, or the source output when `value` is unset.

**target**::
Writes the value into the node. A document already holding it is reported as up to date and left untouched.

== Parameters

{{< resourceparameters "sources" "xml" >}}

Both `file` and `path` are mandatory. Omitting either aborts the run with `wrong spec content`, preceded by the specific reason (`xml file not specified` or `xml path undefined`).

IMPORTANT: This resource takes a single `file` only. There is no `files` attribute, unlike the `yaml`, `json`, `toml`, `csv` and `hcl` resources (update several documents with one target each).

== XPath

`path` is a standard XPath expression, evaluated against the whole document:

[cols="2,3",options=header]
|===
| Expression | Matches
| `/project/parent/version` | An absolute path from the document root.
| `//breakfast_menu/food[0]/name` | The first `food` entry, indexed from zero.
| `//book[@category='WEB']/title` | Selected by attribute value.
|===

A `path` matching nothing makes a source fail, and a condition report a failure rather than error.

== Remote files

`file` accepts `https://`, `http://` and `file://` for a source and a condition. A target must write to a local file and refuses a URL:

[source,text]
----
URL scheme is not supported for XML target: "https://example.com/pom.xml"
----

== Example

[source,yaml]
----
# updatecli.yaml
{{<include "assets/code_example/docs/plugins/resources/xml/updatecli.d/default.yaml">}}
----

== Links

* link:https://www.w3.org/TR/1999/REC-xpath-19991116/[XPath 1.0 specification]