Ansible Module xml: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
Line 94: Line 94:
Elements default to no value (but present). Attributes default to an empty string.
Elements default to no value (but present). Attributes default to an empty string.
==<tt>attribute</tt>==
==<tt>attribute</tt>==
The attribute to select when using parameter <code>[[#value]]</code>. This is a string, not prepended with @.
The attribute to select when using parameter <code>[[#value|value]]</code>. This is a string, not prepended with @.


==<tt>xmlstring</tt>==
==<tt>xmlstring</tt>==

Revision as of 21:39, 4 July 2021

External

Internal

Overview

The plugin is named community.general.xml and it offers functionality aimed at interacting with XML files, using XPath.

Example

<box>
    <object name="A" color="red">square</child>
    <object name="B" color="green">circle</child>
    <object name="C" color="blue">triangle</child>
</box>
- name: XML manipulation
  xml:
    path: /tmp/test.xml # the file must exist
    xpath: /box/object[@name='B']

Module Parameters

path (dest, file)

The path to the file to operate on. The file must exists, otherwise the module will fail, with a message similar to: The target XML source '...' does not exist.. The parameter is required unless xmlstring is provided.

- name: test
  xml:
    path: /tmp/test.xml # the file must exist
    ...

xpath

A valid XPath expression describing the file item(s) to manipulate. Operates on the document root, /, by default.

- name: test
  xml:
    ...
    xpath: /box/object[@name='B']
    ...

content

Specifies the kind of content we want to get from the matching XPath expression:

xpath must be set.

attribute

The matches result key contains a JSON document listing the matching elements and the value of all their attributes. The count result key contains the number of matching elements.

- name: test
  xml:
    path: test.xml
    xpath: /box/object[@name='B']
    content: attribute
  register: xpath_result

produces the following xpath_result.matches:

[
  {
    "object": {
      "color": "green",
       "name": "B"
    }
  }
]

text

The matches result key contains a JSON document listing the matching elements name and its element text. The count result key contains the number of matching elements.

- name: test
  xml:
    path: test.xml
    xpath: /box/object[@name='B']
    content: text
  register: xpath_result

produces the following xpath_result.matches:

[
  {
    "object": "circle"
  }
]

value

Configuration element useful when updating or deleting XML content. value represents the desired state of the selected attribute. It could be either a string, or to unset a value, the Python None keyword (YAML Equivalent, null).

Elements default to no value (but present). Attributes default to an empty string.

attribute

The attribute to select when using parameter value. This is a string, not prepended with @.

xmlstring

A string containing in-line XML content on which to operate. This parameter is required, unless path is given.

Use Cases

Query

Insertion

Update

Deletion

- name: Bump Java build heap size to {{build.jvm.heap_max}} MB
  xml:
    path: "{{ansible_env.PROJECT_ROOT}}/.idea/compiler.xml"
    xpath: /project/component[@name='CompilerConfiguration']/option[@name='BUILD_PROCESS_HEAP_SIZE']
    attribute: "value"
    value: "{{build.jvm.heap_max}}"
- name: Set Eclipse as default compiler
  xml:
    path: "{{idea_path}}/.idea/compiler.xml"
    xpath: /project/component[@name='CompilerConfiguration']/option[@name='DEFAULT_COMPILER']
    attribute: "value"
    value: "Eclipse"