From cbffb77f5713b80b2054195b55dbabde5d80ecfb Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Thu, 15 Sep 2022 20:00:52 +0200
Subject: [PATCH] Document some more filters (#78548)

---
 lib/ansible/plugins/filter/dict2items.yml | 47 +++++++++++++++++++++++
 lib/ansible/plugins/filter/items2dict.yml | 47 +++++++++++++++++++++++
 lib/ansible/plugins/filter/path_join.yml  | 21 ++++++++++
 lib/ansible/plugins/filter/realpath.yml   | 22 +++++++++++
 lib/ansible/plugins/filter/relpath.yml    | 29 ++++++++++++++
 lib/ansible/plugins/filter/splitext.yml   | 30 +++++++++++++++
 6 files changed, 196 insertions(+)
 create mode 100644 lib/ansible/plugins/filter/dict2items.yml
 create mode 100644 lib/ansible/plugins/filter/items2dict.yml
 create mode 100644 lib/ansible/plugins/filter/path_join.yml
 create mode 100644 lib/ansible/plugins/filter/realpath.yml
 create mode 100644 lib/ansible/plugins/filter/relpath.yml
 create mode 100644 lib/ansible/plugins/filter/splitext.yml

diff --git a/lib/ansible/plugins/filter/dict2items.yml b/lib/ansible/plugins/filter/dict2items.yml
new file mode 100644
index 00000000000..018d5f7d2af
--- /dev/null
+++ b/lib/ansible/plugins/filter/dict2items.yml
@@ -0,0 +1,47 @@
+DOCUMENTATION:
+  name: dict2items
+  author: Ansible core team
+  version_added: "2.6"
+  short_description: takes a dictionary and transforms it into a list of dictionaries
+  description:
+    - Takes a dictionary and transforms it into a list of dictionaries, with each having a
+      C(key) and C(value) keys that correspond to the keys and values of the original.
+  options:
+    _input:
+      description:
+        - The dictionary to transform
+      type: dict
+      required: true
+    key_name:
+      description: Configure the key to use instead of C(key).
+      type: str
+      default: key
+      version_added: "2.8"
+    value_name:
+      description: Configure the key to use instead of C(value).
+      type: str
+      default: value
+      version_added: "2.8"
+  seealso:
+    - plugin_type: filter
+      plugin: ansible.builtin.items2dict
+EXAMPLES: |
+  - name: Convert a dictionary into a list of dictionaries
+    debug:
+      msg: "{{ files | dict2items(key_name='file', value_name='path') }}"
+    vars:
+      files:
+        users: /etc/passwd
+        groups: /etc/group
+
+  # The output is a list of dictionaries:
+  #   - file: users
+  #     path: /etc/passwd
+  #   - file: groups
+  #     path: /etc/group
+
+RETURN:
+  _value:
+    description: A list of dictionaries.
+    type: list
+    elements: dict
diff --git a/lib/ansible/plugins/filter/items2dict.yml b/lib/ansible/plugins/filter/items2dict.yml
new file mode 100644
index 00000000000..522c522f065
--- /dev/null
+++ b/lib/ansible/plugins/filter/items2dict.yml
@@ -0,0 +1,47 @@
+DOCUMENTATION:
+  name: items2dict
+  author: Ansible core team
+  version_added: "2.7"
+  short_description: convert a list of one-element dictionaries into a dictionary
+  description:
+    - Takes a list of dicts with each having a C(key) and C(value) keys, and transforms the list into a dictionary,
+      effectively as the reverse of R(dict2items,ansible_collections.ansible.builtin.dict2items_filter).
+  options:
+    _input:
+      description:
+        - A list of dictionaries.
+        - Every dictionary must have keys C(key) and C(value).
+      type: list
+      elements: dict
+      required: true
+    key_name:
+      description: Configure the key to use instead of C(key).
+      type: str
+      default: key
+    value_name:
+      description: Configure the key to use instead of C(value).
+      type: str
+      default: value
+  seealso:
+    - plugin_type: filter
+      plugin: ansible.builtin.dict2items
+EXAMPLES: |
+  - name: Convert list of key-value pairs to dictionary
+    debug:
+      msg: "{{ tags | items2dict }}"
+    vars:
+      tags:
+        - key: Application
+          value: payment
+        - key: Environment
+          value: dev
+
+  # The output is a dictionary with two key/value pairs:
+  #
+  #     Application: payment
+  #     Environment: dev
+
+RETURN:
+  _value:
+    description: The resulting dictionary.
+    type: dict
diff --git a/lib/ansible/plugins/filter/path_join.yml b/lib/ansible/plugins/filter/path_join.yml
new file mode 100644
index 00000000000..ad56168af4c
--- /dev/null
+++ b/lib/ansible/plugins/filter/path_join.yml
@@ -0,0 +1,21 @@
+DOCUMENTATION:
+  name: path_join
+  author: Anthony Bourguignon (@Toniob)
+  version_added: "2.10"
+  short_description: join one or more path components
+  description:
+    - Returns a path obtained by joining one or more path components.
+  options:
+    _input:
+      description: A path, or a list of paths.
+      type: any
+      required: true
+EXAMPLES: |
+
+  # If path == 'foo/bar' and file == 'baz.txt', the result is '/etc/foo/bar/subdir/baz.txt'
+  {{ ('/etc', path, 'subdir', file) | path_join }}
+
+RETURN:
+  _value:
+    description: The concatenated path.
+    type: path
diff --git a/lib/ansible/plugins/filter/realpath.yml b/lib/ansible/plugins/filter/realpath.yml
new file mode 100644
index 00000000000..1e982226371
--- /dev/null
+++ b/lib/ansible/plugins/filter/realpath.yml
@@ -0,0 +1,22 @@
+DOCUMENTATION:
+  name: realpath
+  author: darkone23 (@darkone23)
+  version_added: "1.8"
+  short_description: get canonical path for the given file
+  description:
+    - Returns the canonical path for the given file. This is done by eliminating symbolic
+      links encountered in the path.
+  options:
+    _input:
+      description: A path to a file.
+      type: path
+      required: true
+EXAMPLES: |
+
+  # To get the real path of a link
+  {{ mypath | realpath }}
+
+RETURN:
+  _value:
+    description: The canonical path.
+    type: path
diff --git a/lib/ansible/plugins/filter/relpath.yml b/lib/ansible/plugins/filter/relpath.yml
new file mode 100644
index 00000000000..b169b6b9dba
--- /dev/null
+++ b/lib/ansible/plugins/filter/relpath.yml
@@ -0,0 +1,29 @@
+DOCUMENTATION:
+  name: relpath
+  author: Jakub Jirutka (@jirutka)
+  version_added: "1.7"
+  short_description: get relative path of the given file
+  description:
+    - Returns the relative path of the given file to the current directory if I(start) is not specified,
+      or relative to the directory given in I(start).
+  positional: start
+  options:
+    _input:
+      description: A path.
+      type: path
+      required: true
+    start:
+      description: The directory the path should be relative to.
+      type: path
+EXAMPLES: |
+
+  # Get the relative path to 'mypath' from 'mydir'
+  {{ mypath | relpath(mydir) }}
+
+  # Returns '../foo/bar.txt'
+  {{ '/tmp/foo/bar.txt' | relpath('/tmp/baz/') }}
+
+RETURN:
+  _value:
+    description: The relative path.
+    type: path
diff --git a/lib/ansible/plugins/filter/splitext.yml b/lib/ansible/plugins/filter/splitext.yml
new file mode 100644
index 00000000000..eac048bd669
--- /dev/null
+++ b/lib/ansible/plugins/filter/splitext.yml
@@ -0,0 +1,30 @@
+DOCUMENTATION:
+  name: splitext
+  author: Matt Martz (@sivel)
+  version_added: "2.0"
+  short_description: split a filename into root and file extension
+  description:
+    - Returns a tuple consisting of C(root) and C(extension), where C(root ~ extension) equals the filename.
+  options:
+    _input:
+      description:
+        - A filename.
+        - Path components contained in the filename will be returned as part of the root.
+      type: str
+      required: true
+EXAMPLES: |
+
+  # with path == 'nginx.conf' the return would be ('nginx', '.conf')
+  {{ path | splitext }}
+
+  # with path == 'nginx.conf' the return would be 'nginx'
+  {{ path | splitext | first }}
+
+  # with path == 'nginx.conf' the return would be '.conf'
+  {{ path | splitext | last }}
+
+RETURN:
+  _value:
+    description: A tuple consisting of root and the extension.
+    type: tuple
+    elements: str