Refactor of win_xml (2nd attempt) to add support for processing multiple nodes and counting nodes matched by xpath (#53362)

* add multi-node manipulation, delete on xpath match only and count capability to win_xml

* fix pep8 and yamllint errors identified by ci tests

* fixed bugs when handling multiple elements, multiple attribute nodes and handling for attribute nodes when using xpaths that only select attributes like //@lang.  Added more tests and tweaked documentation.

* fixed line-too-long error

* fixed trailing space errors

* trailing whitespace expunged

* bump version_added to 2.9 for new changes

* fix PSAvoidUsingPositionalParameters sanity check failure

* refix sanity check as it broke the msg return value

lib/ansible/modules/windows/win_xml.py

@@ -15,28 +15,23 @@ DOCUMENTATION = r'''
 ---
 module: win_xml
 version_added: "2.7"
-short_description: Add XML fragment to an XML parent
+short_description: Manages XML file content on Windows hosts
 description:
-    - Adds XML fragments formatted as strings to existing XML on remote servers.
+    - Manages XML nodes, attributes and text, using xpath to select which xml nodes need to be managed.
+    - XML fragments, formatted as strings, are used to specify the desired state of a part or parts of XML files on remote Windows servers.
     - For non-Windows targets, use the M(xml) module instead.
 options:
-    path:
+    attribute:
         description:
-        - The path of remote servers XML.
-        type: path
-        required: true
-        aliases: [ dest, file ]
-    fragment:
-        description:
-        - The string representation of the XML fragment to be added.
+        - The attribute name if the type is 'attribute'.
+        - Required if C(type=attribute).
         type: str
-        required: true
-        aliases: [ xmlstring ]
-    xpath:
+    count:
         description:
-        - The node of the remote server XML where the fragment will go.
-        type: str
-        required: true
+        - When set to C(yes), return the number of nodes matched by I(xpath).
+        type: bool
+        default: false
+        version_added: 2.9
     backup:
         description:
         - Determine whether a backup should be created.
@@ -44,20 +39,49 @@ options:
           so you can get the original file back if you somehow clobbered it incorrectly.
         type: bool
         default: no
+    fragment:
+        description:
+        - The string representation of the XML fragment expected at xpath.  Since ansible 2.9 not required when I(state=absent), or when I(count=yes).
+        type: str
+        required: false
+        aliases: [ xmlstring ]
+    path:
+        description:
+        - Path to the file to operate on.
+        type: path
+        required: true
+        aliases: [ dest, file ]
+    state:
+        description:
+        - Set or remove the nodes (or attributes) matched by I(xpath).
+        type: str
+        default: present
+        choices: [ present, absent ]
+        version_added: 2.9
     type:
         description:
-        - The type of XML you are working with.
+        - The type of XML node you are working with.
         type: str
         required: yes
         default: element
         choices: [ attribute, element, text ]
-    attribute:
+    xpath:
         description:
-        - The attribute name if the type is 'attribute'.
-        - Required if C(type=attribute).
+        - Xpath to select the node or nodes to operate on.
         type: str
+        required: true
 author:
     - Richard Levenberg (@richardcs)
+    - Jon Hawkesworth (@jhawkesworth)
+notes:
+    - Only supports operating on xml elements, attributes and text.
+    - Namespace, processing-instruction, command and document node types cannot be modified with this module.
+seealso:
+    - module: xml
+      description: XML manipulation for Posix hosts.
+    - name: w3shools XPath tutorial
+      description: A useful tutorial on XPath
+      link: https://www.w3schools.com/xml/xpath_intro.asp
 '''
 
 EXAMPLES = r'''
@@ -74,6 +98,32 @@ EXAMPLES = r'''
    attribute: 'sslEnabledProtocols'
    fragment: 'TLSv1,TLSv1.1,TLSv1.2'
    type: attribute
+
+- name: remove debug configuration nodes from nlog.conf
+  win_xml:
+   path: C:\IISApplication\nlog.conf
+   xpath: /nlog/rules/logger[@name="debug"]/descendant::*
+   state: absent
+
+- name: count configured connectors in Tomcat's server.xml
+  win_xml:
+   path: C:\Tomcat\conf\server.xml
+   xpath: //Server/Service/Connector
+   count: yes
+  register: connector_count
+
+- name: show connector count
+  debug:
+    msg="Connector count is {{connector_count.count}}"
+
+- name: ensure all lang=en attributes to lang=nl
+  win_xml:
+   path: C:\Data\Books.xml
+   xpath: //@[lang="en"]
+   attribute: lang
+   fragment: nl
+   type: attribute
+
 '''
 
 RETURN = r'''
@@ -82,6 +132,11 @@ backup_file:
     returned: if backup=yes
     type: str
     sample: C:\Path\To\File.txt.11540.20150212-220915.bak
+count:
+    description: Number of nodes matched by xpath.
+    returned: if count=yes
+    type: int
+    sample: 33
 msg:
     description: What was done.
     returned: always