From 357119f3b7e67293359285eb7b2cd1c920ec5376 Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Fri, 25 Aug 2017 23:53:38 +0200 Subject: [PATCH] xml module: Improve documentation (#28667) Missing bits and pieces, clarifications and examples. This fixes #27951 This fixes #28119 This fixes cmprescott/ansible-xml#59 --- lib/ansible/modules/files/xml.py | 36 +++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/lib/ansible/modules/files/xml.py b/lib/ansible/modules/files/xml.py index 7ed5ad36ac3..e5b584162f2 100644 --- a/lib/ansible/modules/files/xml.py +++ b/lib/ansible/modules/files/xml.py @@ -51,6 +51,10 @@ options: default: present choices: [ absent, present ] aliases: [ ensure ] + attribute: + description: + - The attribute to select when using parameter C(value). + - This is a string, not prepended with C(@). value: description: - Desired state of the selected attribute. @@ -59,23 +63,27 @@ options: - Attributes default to an empty string. add_children: description: - - Add additional child-element(s) to a selected element. + - Add additional child-element(s) to a selected element for a given C(xpath). - Child elements must be given in a list and each item may be either a string (eg. C(children=ansible) to add an empty C() child element), or a hash where the key is an element name and the value is the element value. + - This parameter requires C(xpath) to be set. set_children: description: - - Set the child-element(s) of a selected element. + - Set the child-element(s) of a selected element for a given C(xpath). - Removes any existing children. - Child elements must be specified as in C(add_children). + - This parameter requires C(xpath) to be set. count: description: - Search for a given C(xpath) and provide the count of any matches. + - This parameter requires C(xpath) to be set. type: bool default: 'no' print_match: description: - Search for a given C(xpath) and print out any matches. + - This parameter requires C(xpath) to be set. type: bool default: 'no' pretty_print: @@ -86,6 +94,7 @@ options: content: description: - Search for a given C(xpath) and get content. + - This parameter requires C(xpath) to be set. choices: [ attribute, text ] input_type: description: @@ -106,6 +115,7 @@ notes: - 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 C(namespaces) parameter. - Namespaces prefix should be used for all children of an element where namespace is defined, unless another namespace is defined for them. +- More information about this module is available from the community wiki at U(https://github.com/ansible/community/wiki/Module:-xml) author: - Tim Bielawa (@tbielawa) - Magnus Hedemark (@magnus919) @@ -161,6 +171,26 @@ EXAMPLES = r''' path: /foo/bar.xml xpath: /business/website/validxhtml/@validatedon +- name: Add or modify an attribute, add element if needed + xml: + path: /foo/bar.xml + xpath: /business/website/validxhtml + attribute: validatedon + value: 1976-08-05 + +# How to read an attrribute value and access it in Ansible +- name: Read attribute value + xml: + path: /foo/bar.xml + xpath: /business/website/validxhtml + content: attribute + attribute: validatedon + register: xmlresp + +- name: Show attribute value + debug: + var: xmlresp.matches[0].validxhtml.validatedon + - name: Remove all children from the website element (option 1) xml: path: /foo/bar.xml @@ -174,7 +204,7 @@ EXAMPLES = r''' children: [] # In case of namespaces, like in below XML, they have to be explicitely stated -# Note: there's the prefix "x" in front of the "bar", too +# NOTE: there's the prefix "x" in front of the "bar", too # # #