ansible-xml

Ansible module for manipulating bits and pieces of XML files and strings. This module is currently in devel version of Ansible. It should be released as part of Ansible 2.4.0 in Mid-September. As a consequence, all the issues should be reported to ansible.

Installation

• This module requires Python bindings to libxml version 2.3 or later. This is usually in a package called python-lxml. Install with apt-get install python-lxml, yum install python-lxml, or pip install lxml.
• This module is NOT included with Ansible v2.3 and below. Install with git clone https://github.com/cmprescott/ansible-xml.git, or ansible-galaxy install cmprescott.xml. Valid installation paths are the playbook's library directory, the playbook's roles directory and include in the playbook, or Ansible's modules path.

Notes

• Original module created by @github_rhinception.
• On 2015-05-05, @tbielawa transferred the project over to @cmprescott to resolve issue #16.
• On 2017-08-08, this module was merged upstream into Ansible.
• This software is available under the terms of the GPLv3 license.
• Hi there, we have unit tests!

What is XPath?

"XPath uses path expressions to select nodes or node-sets in an XML document. The node is selected by following a path or steps."

Basically, it's a syntax which allows you to select a specific, or collection, of elements or attributes in an XML file.

Learn more at the Mozilla Developer Network

Unittests

Also included in this repository are Unittests. Reference these, in addition to the Travis-CI configuration, if you need some more examples.

Examples

Given:

<?xml version='1.0' encoding='UTF-8'?>
<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>

Remove the subjective attribute of the rating element:

xml:
  path: /foo/bar.xml
  xpath: /business/rating/@subjective
  state: absent

Set the rating to 11

xml:
  path: /foo/bar.xml
  xpath: /business/rating
  value: 11

Get count of beers nodes

xml:
  path: /foo/bar.xml
  xpath: /business/beers/beer
  count: yes
register: hits

debug:
  var: hits.count

Add a phonenumber element to the business element Implicit mkdir -p behavior where applicable (parent xml nodes created automatically)

xml:
  path: /foo/bar.xml
  xpath: /business/phonenumber
  value: 555-555-1234

Add several more beers to the beers element, assuming a vars.yaml file with:

new_beers:
    - beer: "Old Rasputin"
    - beer: "Old Motor Oil"
    - beer: "Old Curmudgeon"

Then the playbook syntax would look like this:

xml:
  path: /foo/bar.xml
  xpath: /business/beers
  add_children: '{{ new_beers }}'

The same, but do it inline

xml:
  path: /foo/bar.xml
  xpath: /business/beers
  add_children:
      - beer: "Old Rasputin"
      - beer: "Old Motor Oil"
      - beer: "Old Curmudgeon"

Add a validxhtml element to the website element. Note that state is present by default, and value defaults to null for elements. The result is something like <website><validxhtml />...</website>

xml:
  path: /foo/bar.xml
  xpath: /business/website/validxhtml

Add an empty validatedon attribute to the validxhtml element. This actually makes the last example redundant because of the implicit parent-node creation behavior. The result is something like <website><validxhtml validatedon='' />...</website>

xml:
  path: /foo/bar.xml
  xpath: /business/website/validxhtml/@validatedon

(1/2) Remove all children from the website element:

xml:
  path: /foo/bar.xml
  xpath: /business/website/*
  state: absent

(2/2) Remove all children from the website element:

xml:
  path: /foo/bar.xml
  xpath: /business/website
  children: []

Question? If You have <beers><child01 /><child02 /></beers>

What happens if you say:

xml:
  path: /foo/bar.xml
  xpath: /beers

value defaults to an element, so then this would erase the children elements.