community.general.xml – Manage bits and pieces of XML files or strings¶
Note
This plugin is part of the community.general collection (version 2.5.1).
To install it use: ansible-galaxy collection install community.general
.
To use it in a playbook, specify: community.general.xml
.
Requirements¶
The below requirements are needed on the host that executes this module.
lxml >= 2.3.0
Parameters¶
Notes¶
Note
Use the
--check
and--diff
options when testing your expressions.The diff output is automatically pretty-printed, so may not reflect the actual file content, only the file structure.
This module does not handle complicated xpath expressions, so limit xpath selectors to simple expressions.
Beware that in case your XML elements are namespaced, you need to use the
namespaces
parameter, see the examples.Namespaces prefix should be used for all children of an element where namespace is defined, unless another namespace is defined for them.
See Also¶
See also
- Xml module development community wiki
More information related to the development of this xml module.
- Introduction to XPath
A brief tutorial on XPath (w3schools.com).
- XPath Reference document
The reference documentation on XSLT/XPath (developer.mozilla.org).
Examples¶
# Consider the following XML file:
#
# <business type="bar">
# <name>Tasty Beverage Co.</name>
# <beers>
# <beer>Rochefort 10</beer>
# <beer>St. Bernardus Abbot 12</beer>
# <beer>Schlitz</beer>
# </beers>
# <rating subjective="true">10</rating>
# <website>
# <mobilefriendly/>
# <address>http://tastybeverageco.com</address>
# </website>
# </business>
- name: Remove the 'subjective' attribute of the 'rating' element
community.general.xml:
path: /foo/bar.xml
xpath: /business/rating/@subjective
state: absent
- name: Set the rating to '11'
community.general.xml:
path: /foo/bar.xml
xpath: /business/rating
value: 11
# Retrieve and display the number of nodes
- name: Get count of 'beers' nodes
community.general.xml:
path: /foo/bar.xml
xpath: /business/beers/beer
count: yes
register: hits
- ansible.builtin.debug:
var: hits.count
# Example where parent XML nodes are created automatically
- name: Add a 'phonenumber' element to the 'business' element
community.general.xml:
path: /foo/bar.xml
xpath: /business/phonenumber
value: 555-555-1234
- name: Add several more beers to the 'beers' element
community.general.xml:
path: /foo/bar.xml
xpath: /business/beers
add_children:
- beer: Old Rasputin
- beer: Old Motor Oil
- beer: Old Curmudgeon
- name: Add several more beers to the 'beers' element and add them before the 'Rochefort 10' element
community.general.xml:
path: /foo/bar.xml
xpath: '/business/beers/beer[text()="Rochefort 10"]'
insertbefore: yes
add_children:
- beer: Old Rasputin
- beer: Old Motor Oil
- beer: Old Curmudgeon
# NOTE: The 'state' defaults to 'present' and 'value' defaults to 'null' for elements
- name: Add a 'validxhtml' element to the 'website' element
community.general.xml:
path: /foo/bar.xml
xpath: /business/website/validxhtml
- name: Add an empty 'validatedon' attribute to the 'validxhtml' element
community.general.xml:
path: /foo/bar.xml
xpath: /business/website/validxhtml/@validatedon
- name: Add or modify an attribute, add element if needed
community.general.xml:
path: /foo/bar.xml
xpath: /business/website/validxhtml
attribute: validatedon
value: 1976-08-05
# How to read an attribute value and access it in Ansible
- name: Read an element's attribute values
community.general.xml:
path: /foo/bar.xml
xpath: /business/website/validxhtml
content: attribute
register: xmlresp
- name: Show an attribute value
ansible.builtin.debug:
var: xmlresp.matches[0].validxhtml.validatedon
- name: Remove all children from the 'website' element (option 1)
community.general.xml:
path: /foo/bar.xml
xpath: /business/website/*
state: absent
- name: Remove all children from the 'website' element (option 2)
community.general.xml:
path: /foo/bar.xml
xpath: /business/website
children: []
# In case of namespaces, like in below XML, they have to be explicitly stated.
#
# <foo xmlns="http://x.test" xmlns:attr="http://z.test">
# <bar>
# <baz xmlns="http://y.test" attr:my_namespaced_attribute="true" />
# </bar>
# </foo>
# NOTE: There is the prefix 'x' in front of the 'bar' element, too.
- name: Set namespaced '/x:foo/x:bar/y:baz/@z:my_namespaced_attribute' to 'false'
community.general.xml:
path: foo.xml
xpath: /x:foo/x:bar/y:baz
namespaces:
x: http://x.test
y: http://y.test
z: http://z.test
attribute: z:my_namespaced_attribute
value: 'false'
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Authors¶
Tim Bielawa (@tbielawa)
Magnus Hedemark (@magnus919)
Dag Wieers (@dagwieers)