new module: win_path (#20073)

lib/ansible/modules/windows/win_path.py

@@ -0,0 +1,87 @@
+#!/usr/bin/python
+#
+# Copyright 2016 Red Hat | Ansible
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# This is a windows documentation stub.  Actual code lives in the .ps1
+# file of the same name
+
+ANSIBLE_METADATA = {'status': ['preview'],
+                    'supported_by': 'core',
+                    'version': '1.0'}
+
+DOCUMENTATION = '''
+---
+module: win_path
+version_added: "2.3"
+short_description: Manage Windows path environment variables
+description:
+    - Allows element-based ordering, addition, and removal of Windows path environment variables.
+options:
+  name:
+    description:
+      - Target path environment variable name
+    default: PATH
+  elements:
+    description:
+      - A single path element, or a list of path elements (ie, directories) to add or remove.
+      - When multiple elements are included in the list (and C(state) is C(present)), the elements are guaranteed to appear in the same relative order in the resultant path value.
+      - Variable expansions (eg, C(%VARNAME%)) are allowed, and are stored unexpanded in the target path element.
+      - Any existing path elements not mentioned in C(elements) are always preserved in their current order.
+      - New path elements are appended to the path, and existing path elements may be moved closer to the end to satisfy the requested ordering.
+      - Paths are compared in a case-insensitive fashion, and trailing backslashes are ignored for comparison purposes. However, note that trailing backslashes in YAML require quotes.
+    required: true
+  state:
+    description:
+      - Whether the path elements specified in C(elements) should be present or absent.
+    choices:
+      - present
+      - absent
+  scope:
+    description:
+      - The level at which the environment variable specified by C(name) should be managed (either for the current user or global machine scope).
+    choices:
+      - machine
+      - user
+    default: machine
+author: "Matt Davis (@nitzmahone)"
+notes:
+   - This module is for modifying indidvidual elements of path-like
+     environment variables. For general-purpose management of other
+     environment vars, use the M(win_environment) module.
+   - This module does not broadcast change events.
+     This means that the minority of windows applications which can have
+     their environment changed without restarting will not be notified and
+     therefore will need restarting to pick up new environment settings.
+     User level environment variables will require an interactive user to
+     log out and in again before they become available.
+'''
+
+EXAMPLES = r'''
+- name: Ensure that system32 and Powershell are present on the global system path, and in the specified order
+  win_path:
+    elements:
+    - %SystemRoot%\system32
+    - %SystemRoot%\system32\WindowsPowerShell\v1.0
+
+- name: Ensure that C:\Program Files\MyJavaThing is not on the current user's CLASSPATH
+  win_path
+    name: CLASSPATH
+    elements: C:\Program Files\MyJavaThing
+    scope: user
+    state: absent
+'''