Feature. Add chapter 'Lists of dictionaries' to docsite (#8482)

* Feature. Add chapter 'Lists of dictionaries'

* Fix copyright and licensing.

* Add maintainers for docsite chapter 'Lists of dictionaries'.

* Generate docs keep_keys and remove_keys

* Update integration tests of keep_keys and remove_keys
* Update docs helpers of keep_keys and remove_keys

* Fix copyright and licensing.

* Fix remove license from templates. Cleanup.

* Add docs helper replace_keys

* Update integration test filter_replace_keys
* Generate and update:
  filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst

* Formatting improved.

* Fix results Jinja quotation marks.

* Update docs/docsite/helper/keep_keys/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst.j2

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/helper/keep_keys/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst.j2

Co-authored-by: Felix Fontein <felix@fontein.de>

* Fix references.

* Updated helpers.

* Fix licenses. Simplified templates.

* Fix licenses.

* Fix README.

---------

Co-authored-by: Felix Fontein <felix@fontein.de>

.github/BOTMETA.yml

@@ -1444,6 +1444,14 @@ files:
     maintainers: felixfontein
   docs/docsite/rst/filter_guide_abstract_informations_lists_helper.rst:
     maintainers: cfiehe
+  docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst:
+    maintainers: vbotka
+  docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst:
+    maintainers: vbotka
+  docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst:
+    maintainers: vbotka
+  docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries.rst:
+    maintainers: vbotka
   docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst:
     maintainers: vbotka
   docs/docsite/rst/filter_guide_conversions.rst:

docs/docsite/helper/keep_keys/README.md

@@ -0,0 +1,61 @@
+<!--
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
+# Docs helper. Create RST file.
+
+The playbook `playbook.yml` writes a RST file that can be used in
+docs/docsite/rst. The usage of this helper is recommended but not
+mandatory. You can stop reading here and update the RST file manually
+if you don't want to use this helper.
+
+## Run the playbook
+
+If you want to generate the RST file by this helper fit the variables
+in the playbook and the template to your needs. Then, run the play
+
+```sh
+shell> ansible-playbook playbook.yml
+```
+
+## Copy RST to docs/docsite/rst
+
+Copy the RST file to `docs/docsite/rst` and remove it from this
+directory.
+
+## Update the checksums
+
+Substitute the variables and run the below commands
+
+```sh
+shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
+shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
+```
+
+## Playbook explained
+
+The playbook includes the variable *tests* from the integration tests
+and creates the RST file from the template. The playbook will
+terminate if:
+
+* The file with the variable *tests* was changed
+* The RST file was changed
+
+This means that this helper is probably not up to date.
+
+### The file with the variable *tests* was changed
+
+This means that somebody updated the integration tests. Review the
+changes and update the template if needed. Update the checksum to pass
+the integrity test. The playbook message provides you with the
+command.
+
+### The RST file was changed
+
+This means that somebody updated the RST file manually. Review the
+changes and update the template. Update the checksum to pass the
+integrity test. The playbook message provides you with the
+command. Make sure that the updated template will create identical RST
+file. Only then apply your changes.

docs/docsite/helper/keep_keys/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst.j2

@@ -0,0 +1,80 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+keep_keys
+"""""""""
+
+Use the filter :ansplugin:`community.general.keep_keys#filter` if you have a list of dictionaries and want to keep certain keys only.
+
+.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ansplugin:`the documentation for the community.general.yaml callback plugin <community.general.yaml#callback>`.
+
+
+Let us use the below list in the following examples:
+
+.. code-block:: yaml
+
+   input:
+     {{ tests.0.input | to_yaml(indent=2) | indent(5) }}
+
+{% for i in tests[0:1]|subelements('group') %}
+* {{ i.1.d }}
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1
+
+   target: {{ i.1.tt }}
+   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
+
+{% endfor %}
+
+gives
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     {{ tests.0.result | to_yaml(indent=2) | indent(5) }}
+ 
+.. versionadded:: 9.1.0
+
+* The results of the below examples 1-5 are all the same:
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     {{ tests.1.result | to_yaml(indent=2) | indent(5) }}
+
+{% for i in tests[1:2]|subelements('group') %}
+{{ loop.index }}. {{ i.1.d }}
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: {{ i.1.mp }}
+   target: {{ i.1.tt }}
+   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
+
+{% endfor %}
+
+* The results of the below examples 6-9 are all the same:
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     {{ tests.2.result | to_yaml(indent=2) | indent(5) }}
+
+{% for i in tests[2:3]|subelements('group') %}
+{{ loop.index + 5 }}. {{ i.1.d }}
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: {{ i.1.mp }}
+   target: {{ i.1.tt }}
+   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
+
+{% endfor %}

docs/docsite/helper/keep_keys/keep_keys.rst.sha1

@@ -0,0 +1 @@
+8690afce792abc95693c2f61f743ee27388b1592  ../../rst/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst

docs/docsite/helper/keep_keys/keep_keys.rst.sha1.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later

docs/docsite/helper/keep_keys/playbook.yml

@@ -0,0 +1,79 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Create docs REST files
+# shell> ansible-playbook playbook.yml
+#
+# Proofread and copy created *.rst file into the directory
+# docs/docsite/rst. Do not add *.rst in this directory to the version
+# control.
+#
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# community.general/docs/docsite/helper/keep_keys/playbook.yml
+
+- name: Create RST file for docs/docsite/rst
+  hosts: localhost
+  gather_facts: false
+
+  vars:
+
+    plugin: keep_keys
+    plugin_type: filter
+    docs_path:
+      - filter_guide
+      - abstract_informations
+      - lists_of_dictionaries
+
+    file_base: "{{ (docs_path + [plugin]) | join('-') }}"
+    file_rst: ../../rst/{{ file_base }}.rst
+    file_sha1: "{{ plugin }}.rst.sha1"
+
+    target: "../../../../tests/integration/targets/{{ plugin_type }}_{{ plugin }}"
+    target_vars: "{{ target }}/vars/main/tests.yml"
+    target_sha1: tests.yml.sha1
+
+  tasks:
+
+    - name: Test integrity tests.yml
+      when:
+        - integrity | d(true) | bool
+        - lookup('file', target_sha1) != lookup('pipe', 'sha1sum ' ~  target_vars)
+      block:
+
+        - name: Changed tests.yml
+          ansible.builtin.debug:
+            msg: |
+              Changed {{ target_vars }}
+              Review the changes and update {{ target_sha1 }}
+              shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
+
+        - name: Changed tests.yml end host
+          ansible.builtin.meta: end_play
+
+    - name: Test integrity RST file
+      when:
+        - integrity | d(true) | bool
+        - lookup('file', file_sha1) != lookup('pipe', 'sha1sum ' ~ file_rst)
+      block:
+
+        - name: Changed RST file
+          ansible.builtin.debug:
+            msg: |
+              Changed {{ file_rst }}
+              Review the changes and update {{ file_sha1 }}
+              shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
+
+        - name: Changed RST file end host
+          ansible.builtin.meta: end_play
+
+    - name: Include target vars
+      include_vars:
+        file: "{{ target_vars }}"
+
+    - name: Create RST file
+      ansible.builtin.template:
+        src: "{{ file_base }}.rst.j2"
+        dest: "{{ file_base }}.rst"

docs/docsite/helper/keep_keys/tests.yml.sha1

@@ -0,0 +1 @@
+c6fc4ee2017d9222675bcd13cc4f88ba8d14f38d  ../../../../tests/integration/targets/filter_keep_keys/vars/main/tests.yml

docs/docsite/helper/keep_keys/tests.yml.sha1.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later

docs/docsite/helper/remove_keys/README.md

@@ -0,0 +1,61 @@
+<!--
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
+# Docs helper. Create RST file.
+
+The playbook `playbook.yml` writes a RST file that can be used in
+docs/docsite/rst. The usage of this helper is recommended but not
+mandatory. You can stop reading here and update the RST file manually
+if you don't want to use this helper.
+
+## Run the playbook
+
+If you want to generate the RST file by this helper fit the variables
+in the playbook and the template to your needs. Then, run the play
+
+```sh
+shell> ansible-playbook playbook.yml
+```
+
+## Copy RST to docs/docsite/rst
+
+Copy the RST file to `docs/docsite/rst` and remove it from this
+directory.
+
+## Update the checksums
+
+Substitute the variables and run the below commands
+
+```sh
+shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
+shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
+```
+
+## Playbook explained
+
+The playbook includes the variable *tests* from the integration tests
+and creates the RST file from the template. The playbook will
+terminate if:
+
+* The file with the variable *tests* was changed
+* The RST file was changed
+
+This means that this helper is probably not up to date.
+
+### The file with the variable *tests* was changed
+
+This means that somebody updated the integration tests. Review the
+changes and update the template if needed. Update the checksum to pass
+the integrity test. The playbook message provides you with the
+command.
+
+### The RST file was changed
+
+This means that somebody updated the RST file manually. Review the
+changes and update the template. Update the checksum to pass the
+integrity test. The playbook message provides you with the
+command. Make sure that the updated template will create identical RST
+file. Only then apply your changes.

docs/docsite/helper/remove_keys/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst.j2

@@ -0,0 +1,80 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+remove_keys
+"""""""""""
+
+Use the filter :ansplugin:`community.general.remove_keys#filter` if you have a list of dictionaries and want to remove certain keys.
+
+.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See See :ansplugin:`the documentation for the community.general.yaml callback plugin <community.general.yaml#callback>`.
+
+
+Let us use the below list in the following examples:
+
+.. code-block:: yaml
+
+   input:
+     {{ tests.0.input | to_yaml(indent=2) | indent(5) }}
+
+{% for i in tests[0:1]|subelements('group') %}
+* {{ i.1.d }}
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1
+
+   target: {{ i.1.tt }}
+   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
+
+{% endfor %}
+
+gives
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     {{ tests.0.result | to_yaml(indent=2) | indent(5) }}
+ 
+.. versionadded:: 9.1.0
+
+* The results of the below examples 1-5 are all the same:
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     {{ tests.1.result | to_yaml(indent=2) | indent(5) }}
+
+{% for i in tests[1:2]|subelements('group') %}
+{{ loop.index }}. {{ i.1.d }}
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: {{ i.1.mp }}
+   target: {{ i.1.tt }}
+   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
+
+{% endfor %}
+
+* The results of the below examples 6-9 are all the same:
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     {{ tests.2.result | to_yaml(indent=2) | indent(5) }}
+
+{% for i in tests[2:3]|subelements('group') %}
+{{ loop.index + 5 }}. {{ i.1.d }}
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: {{ i.1.mp }}
+   target: {{ i.1.tt }}
+   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
+
+{% endfor %}

docs/docsite/helper/remove_keys/playbook.yml

@@ -0,0 +1,79 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Create docs REST files
+# shell> ansible-playbook playbook.yml
+#
+# Proofread and copy created *.rst file into the directory
+# docs/docsite/rst. Do not add *.rst in this directory to the version
+# control.
+#
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# community.general/docs/docsite/helper/remove_keys/playbook.yml
+
+- name: Create RST file for docs/docsite/rst
+  hosts: localhost
+  gather_facts: false
+
+  vars:
+
+    plugin: remove_keys
+    plugin_type: filter
+    docs_path:
+      - filter_guide
+      - abstract_informations
+      - lists_of_dictionaries
+
+    file_base: "{{ (docs_path + [plugin]) | join('-') }}"
+    file_rst: ../../rst/{{ file_base }}.rst
+    file_sha1: "{{ plugin }}.rst.sha1"
+
+    target: "../../../../tests/integration/targets/{{ plugin_type }}_{{ plugin }}"
+    target_vars: "{{ target }}/vars/main/tests.yml"
+    target_sha1: tests.yml.sha1
+
+  tasks:
+
+    - name: Test integrity tests.yml
+      when:
+        - integrity | d(true) | bool
+        - lookup('file', target_sha1) != lookup('pipe', 'sha1sum ' ~  target_vars)
+      block:
+
+        - name: Changed tests.yml
+          ansible.builtin.debug:
+            msg: |
+              Changed {{ target_vars }}
+              Review the changes and update {{ target_sha1 }}
+              shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
+
+        - name: Changed tests.yml end host
+          ansible.builtin.meta: end_play
+
+    - name: Test integrity RST file
+      when:
+        - integrity | d(true) | bool
+        - lookup('file', file_sha1) != lookup('pipe', 'sha1sum ' ~ file_rst)
+      block:
+
+        - name: Changed RST file
+          ansible.builtin.debug:
+            msg: |
+              Changed {{ file_rst }}
+              Review the changes and update {{ file_sha1 }}
+              shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
+
+        - name: Changed RST file end host
+          ansible.builtin.meta: end_play
+
+    - name: Include target vars
+      include_vars:
+        file: "{{ target_vars }}"
+
+    - name: Create RST file
+      ansible.builtin.template:
+        src: "{{ file_base }}.rst.j2"
+        dest: "{{ file_base }}.rst"

docs/docsite/helper/remove_keys/remove_keys.rst.sha1

@@ -0,0 +1 @@
+3cc606b42e3d450cf6323f25930f7c5a591fa086  ../../rst/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst

docs/docsite/helper/remove_keys/remove_keys.rst.sha1.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later

docs/docsite/helper/remove_keys/tests.yml.sha1

@@ -0,0 +1 @@
+0554335045f02d8c37b824355b0cf86864cee9a5  ../../../../tests/integration/targets/filter_remove_keys/vars/main/tests.yml

docs/docsite/helper/remove_keys/tests.yml.sha1.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later

docs/docsite/helper/replace_keys/README.md

@@ -0,0 +1,61 @@
+<!--
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
+# Docs helper. Create RST file.
+
+The playbook `playbook.yml` writes a RST file that can be used in
+docs/docsite/rst. The usage of this helper is recommended but not
+mandatory. You can stop reading here and update the RST file manually
+if you don't want to use this helper.
+
+## Run the playbook
+
+If you want to generate the RST file by this helper fit the variables
+in the playbook and the template to your needs. Then, run the play
+
+```sh
+shell> ansible-playbook playbook.yml
+```
+
+## Copy RST to docs/docsite/rst
+
+Copy the RST file to `docs/docsite/rst` and remove it from this
+directory.
+
+## Update the checksums
+
+Substitute the variables and run the below commands
+
+```sh
+shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
+shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
+```
+
+## Playbook explained
+
+The playbook includes the variable *tests* from the integration tests
+and creates the RST file from the template. The playbook will
+terminate if:
+
+* The file with the variable *tests* was changed
+* The RST file was changed
+
+This means that this helper is probably not up to date.
+
+### The file with the variable *tests* was changed
+
+This means that somebody updated the integration tests. Review the
+changes and update the template if needed. Update the checksum to pass
+the integrity test. The playbook message provides you with the
+command.
+
+### The RST file was changed
+
+This means that somebody updated the RST file manually. Review the
+changes and update the template. Update the checksum to pass the
+integrity test. The playbook message provides you with the
+command. Make sure that the updated template will create identical RST
+file. Only then apply your changes.

docs/docsite/helper/replace_keys/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst.j2

@@ -0,0 +1,110 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+replace_keys
+""""""""""""
+
+Use the filter :ansplugin:`community.general.replace_keys#filter` if you have a list of dictionaries and want to replace certain keys.
+
+.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ansplugin:`the documentation for the community.general.yaml callback plugin <community.general.yaml#callback>`.
+
+
+Let us use the below list in the following examples:
+
+.. code-block:: yaml
+
+   input:
+     {{ tests.0.input | to_yaml(indent=2) | indent(5) }}
+
+{% for i in tests[0:1]|subelements('group') %}
+* {{ i.1.d }}
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-3
+
+   target:
+     {{ i.1.tt | to_yaml(indent=2) | indent(5) }}
+   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
+
+{% endfor %}
+
+gives
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     {{ tests.0.result | to_yaml(indent=2) | indent(5) }}
+ 
+.. versionadded:: 9.1.0
+
+* The results of the below examples 1-3 are all the same:
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     {{ tests.1.result | to_yaml(indent=2) | indent(5) }}
+
+{% for i in tests[1:2]|subelements('group') %}
+{{ loop.index }}. {{ i.1.d }}
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-4
+
+   mp: {{ i.1.mp }}
+   target:
+     {{ i.1.tt | to_yaml(indent=2) | indent(5) }}
+   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
+
+{% endfor %}
+
+* The results of the below examples 4-5 are the same:
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     {{ tests.2.result | to_yaml(indent=2) | indent(5) }}
+
+{% for i in tests[2:3]|subelements('group') %}
+{{ loop.index + 3 }}. {{ i.1.d }}
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-3
+
+   mp: {{ i.1.mp }}
+   target:
+     {{ i.1.tt | to_yaml(indent=2) | indent(5) }}
+   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
+
+{% endfor %}
+
+{% for i in tests[3:4]|subelements('group') %}
+{{ loop.index + 5 }}. {{ i.1.d }}
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   input:
+     {{ i.0.input | to_yaml(indent=2) | indent(5) }}
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-4
+
+   mp: {{ i.1.mp }}
+   target:
+     {{ i.1.tt | to_yaml(indent=2) | indent(5) }}
+   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
+
+gives
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     {{ i.0.result | to_yaml(indent=2) | indent(5) }}
+
+{% endfor %}

docs/docsite/helper/replace_keys/playbook.yml

@@ -0,0 +1,79 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Create docs REST files
+# shell> ansible-playbook playbook.yml
+#
+# Proofread and copy created *.rst file into the directory
+# docs/docsite/rst. Do not add *.rst in this directory to the version
+# control.
+#
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# community.general/docs/docsite/helper/replace_keys/playbook.yml
+
+- name: Create RST file for docs/docsite/rst
+  hosts: localhost
+  gather_facts: false
+
+  vars:
+
+    plugin: replace_keys
+    plugin_type: filter
+    docs_path:
+      - filter_guide
+      - abstract_informations
+      - lists_of_dictionaries
+
+    file_base: "{{ (docs_path + [plugin]) | join('-') }}"
+    file_rst: ../../rst/{{ file_base }}.rst
+    file_sha1: "{{ plugin }}.rst.sha1"
+
+    target: "../../../../tests/integration/targets/{{ plugin_type }}_{{ plugin }}"
+    target_vars: "{{ target }}/vars/main/tests.yml"
+    target_sha1: tests.yml.sha1
+
+  tasks:
+
+    - name: Test integrity tests.yml
+      when:
+        - integrity | d(true) | bool
+        - lookup('file', target_sha1) != lookup('pipe', 'sha1sum ' ~  target_vars)
+      block:
+
+        - name: Changed tests.yml
+          ansible.builtin.debug:
+            msg: |
+              Changed {{ target_vars }}
+              Review the changes and update {{ target_sha1 }}
+              shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
+
+        - name: Changed tests.yml end host
+          ansible.builtin.meta: end_play
+
+    - name: Test integrity RST file
+      when:
+        - integrity | d(true) | bool
+        - lookup('file', file_sha1) != lookup('pipe', 'sha1sum ' ~ file_rst)
+      block:
+
+        - name: Changed RST file
+          ansible.builtin.debug:
+            msg: |
+              Changed {{ file_rst }}
+              Review the changes and update {{ file_sha1 }}
+              shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
+
+        - name: Changed RST file end host
+          ansible.builtin.meta: end_play
+
+    - name: Include target vars
+      include_vars:
+        file: "{{ target_vars }}"
+
+    - name: Create RST file
+      ansible.builtin.template:
+        src: "{{ file_base }}.rst.j2"
+        dest: "{{ file_base }}.rst"

docs/docsite/helper/replace_keys/replace_keys.rst.sha1

@@ -0,0 +1 @@
+403f23c02ac02b1c3b611cb14f9b3ba59dc3f587  ../../rst/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst

docs/docsite/helper/replace_keys/replace_keys.rst.sha1.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later

docs/docsite/helper/replace_keys/tests.yml.sha1

@@ -0,0 +1 @@
+2e54f3528c95cca746d5748f1ed7ada56ad0890e  ../../../../tests/integration/targets/filter_replace_keys/vars/main/tests.yml

docs/docsite/helper/replace_keys/tests.yml.sha1.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later

docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst

@@ -0,0 +1,151 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+keep_keys
+"""""""""
+
+Use the filter :ansplugin:`community.general.keep_keys#filter` if you have a list of dictionaries and want to keep certain keys only.
+
+.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ansplugin:`the documentation for the community.general.yaml callback plugin <community.general.yaml#callback>`.
+
+
+Let us use the below list in the following examples:
+
+.. code-block:: yaml
+
+   input:
+     - k0_x0: A0
+       k1_x1: B0
+       k2_x2: [C0]
+       k3_x3: foo
+     - k0_x0: A1
+       k1_x1: B1
+       k2_x2: [C1]
+       k3_x3: bar
+
+
+* By default, match keys that equal any of the items in the target.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1
+
+   target: ['k0_x0', 'k1_x1']
+   result: "{{ input | community.general.keep_keys(target=target) }}"
+
+
+gives
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     - {k0_x0: A0, k1_x1: B0}
+     - {k0_x0: A1, k1_x1: B1}
+
+ 
+.. versionadded:: 9.1.0
+
+* The results of the below examples 1-5 are all the same:
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     - {k0_x0: A0, k1_x1: B0}
+     - {k0_x0: A1, k1_x1: B1}
+
+
+1. Match keys that equal any of the items in the target.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: equal
+   target: ['k0_x0', 'k1_x1']
+   result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
+
+2. Match keys that start with any of the items in the target.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: starts_with
+   target: ['k0', 'k1']
+   result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
+
+3. Match keys that end with any of the items in target.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: ends_with
+   target: ['x0', 'x1']
+   result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
+
+4. Match keys by the regex.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: regex
+   target: ['^.*[01]_x.*$']
+   result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
+
+5. Match keys by the regex.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: regex
+   target: ^.*[01]_x.*$
+   result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
+
+
+* The results of the below examples 6-9 are all the same:
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     - {k0_x0: A0}
+     - {k0_x0: A1}
+
+
+6. Match keys that equal the target.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: equal
+   target: k0_x0
+   result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
+
+7. Match keys that start with the target.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: starts_with
+   target: k0
+   result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
+
+8. Match keys that end with the target.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: ends_with
+   target: x0
+   result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
+
+9. Match keys by the regex.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: regex
+   target: ^.*0_x.*$
+   result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
+

docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst

@@ -0,0 +1,159 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+remove_keys
+"""""""""""
+
+Use the filter :ansplugin:`community.general.remove_keys#filter` if you have a list of dictionaries and want to remove certain keys.
+
+.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See See :ansplugin:`the documentation for the community.general.yaml callback plugin <community.general.yaml#callback>`.
+
+
+Let us use the below list in the following examples:
+
+.. code-block:: yaml
+
+   input:
+     - k0_x0: A0
+       k1_x1: B0
+       k2_x2: [C0]
+       k3_x3: foo
+     - k0_x0: A1
+       k1_x1: B1
+       k2_x2: [C1]
+       k3_x3: bar
+
+
+* By default, match keys that equal any of the items in the target.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1
+
+   target: ['k0_x0', 'k1_x1']
+   result: "{{ input | community.general.remove_keys(target=target) }}"
+
+
+gives
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     - k2_x2: [C0]
+       k3_x3: foo
+     - k2_x2: [C1]
+       k3_x3: bar
+
+ 
+.. versionadded:: 9.1.0
+
+* The results of the below examples 1-5 are all the same:
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     - k2_x2: [C0]
+       k3_x3: foo
+     - k2_x2: [C1]
+       k3_x3: bar
+
+
+1. Match keys that equal any of the items in the target.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: equal
+   target: ['k0_x0', 'k1_x1']
+   result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
+
+2. Match keys that start with any of the items in the target.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: starts_with
+   target: ['k0', 'k1']
+   result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
+
+3. Match keys that end with any of the items in target.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: ends_with
+   target: ['x0', 'x1']
+   result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
+
+4. Match keys by the regex.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: regex
+   target: ['^.*[01]_x.*$']
+   result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
+
+5. Match keys by the regex.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: regex
+   target: ^.*[01]_x.*$
+   result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
+
+
+* The results of the below examples 6-9 are all the same:
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     - k1_x1: B0
+       k2_x2: [C0]
+       k3_x3: foo
+     - k1_x1: B1
+       k2_x2: [C1]
+       k3_x3: bar
+
+
+6. Match keys that equal the target.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: equal
+   target: k0_x0
+   result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
+
+7. Match keys that start with the target.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: starts_with
+   target: k0
+   result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
+
+8. Match keys that end with the target.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: ends_with
+   target: x0
+   result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
+
+9. Match keys by the regex.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1,2
+
+   mp: regex
+   target: ^.*0_x.*$
+   result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
+

docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst

@@ -0,0 +1,175 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+replace_keys
+""""""""""""
+
+Use the filter :ansplugin:`community.general.replace_keys#filter` if you have a list of dictionaries and want to replace certain keys.
+
+.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ansplugin:`the documentation for the community.general.yaml callback plugin <community.general.yaml#callback>`.
+
+
+Let us use the below list in the following examples:
+
+.. code-block:: yaml
+
+   input:
+     - k0_x0: A0
+       k1_x1: B0
+       k2_x2: [C0]
+       k3_x3: foo
+     - k0_x0: A1
+       k1_x1: B1
+       k2_x2: [C1]
+       k3_x3: bar
+
+
+* By default, match keys that equal any of the attributes before.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-3
+
+   target:
+     - {after: a0, before: k0_x0}
+     - {after: a1, before: k1_x1}
+
+   result: "{{ input | community.general.replace_keys(target=target) }}"
+
+
+gives
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     - a0: A0
+       a1: B0
+       k2_x2: [C0]
+       k3_x3: foo
+     - a0: A1
+       a1: B1
+       k2_x2: [C1]
+       k3_x3: bar
+
+ 
+.. versionadded:: 9.1.0
+
+* The results of the below examples 1-3 are all the same:
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     - a0: A0
+       a1: B0
+       k2_x2: [C0]
+       k3_x3: foo
+     - a0: A1
+       a1: B1
+       k2_x2: [C1]
+       k3_x3: bar
+
+
+1. Replace keys that starts with any of the attributes before.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-4
+
+   mp: starts_with
+   target:
+     - {after: a0, before: k0}
+     - {after: a1, before: k1}
+
+   result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}"
+
+2. Replace keys that ends with any of the attributes before.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-4
+
+   mp: ends_with
+   target:
+     - {after: a0, before: x0}
+     - {after: a1, before: x1}
+
+   result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}"
+
+3. Replace keys that match any regex of the attributes before.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-4
+
+   mp: regex
+   target:
+     - {after: a0, before: ^.*0_x.*$}
+     - {after: a1, before: ^.*1_x.*$}
+
+   result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}"
+
+
+* The results of the below examples 4-5 are the same:
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     - {X: foo}
+     - {X: bar}
+
+
+4. If more keys match the same attribute before the last one will be used.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-3
+
+   mp: regex
+   target:
+     - {after: X, before: ^.*_x.*$}
+
+   result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}"
+
+5. If there are items with equal attribute before the first one will be used.
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-3
+
+   mp: regex
+   target:
+     - {after: X, before: ^.*_x.*$}
+     - {after: Y, before: ^.*_x.*$}
+
+   result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}"
+
+
+6. If there are more matches for a key the first one will be used.
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   input:
+     - {aaa1: A, bbb1: B, ccc1: C}
+     - {aaa2: D, bbb2: E, ccc2: F}
+
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-4
+
+   mp: starts_with
+   target:
+     - {after: X, before: a}
+     - {after: Y, before: aa}
+
+   result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}"
+
+gives
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     - {X: A, bbb1: B, ccc1: C}
+     - {X: D, bbb2: E, ccc2: F}
+
+

docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries.rst

@@ -0,0 +1,18 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _ansible_collections.community.general.docsite.filter_guide.filter_guide_abstract_informations.lists_of_dicts:
+  
+Lists of dictionaries
+^^^^^^^^^^^^^^^^^^^^^
+
+Filters to manage keys in a list of dictionaries:
+
+.. toctree::
+   :maxdepth: 1
+
+   filter_guide-abstract_informations-lists_of_dictionaries-keep_keys
+   filter_guide-abstract_informations-lists_of_dictionaries-remove_keys
+   filter_guide-abstract_informations-lists_of_dictionaries-replace_keys

docs/docsite/rst/filter_guide_abstract_informations.rst

@@ -11,6 +11,7 @@ Abstract transformations
 
    filter_guide_abstract_informations_dictionaries
    filter_guide_abstract_informations_grouping
+   filter_guide-abstract_informations-lists_of_dictionaries
    filter_guide_abstract_informations_merging_lists_of_dictionaries
    filter_guide_abstract_informations_lists_helper
    filter_guide_abstract_informations_counting_elements_in_sequence

tests/integration/targets/filter_keep_keys/tasks/keep_keys.yml

@@ -1,79 +0,0 @@
----
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-- name: Debug ansible_version
-  ansible.builtin.debug:
-    var: ansible_version
-  when: not quite_test | d(true) | bool
-  tags: ansible_version
-
-- name: Test keep keys equal (default)
-  ansible.builtin.assert:
-    that:
-      - (rr | difference(result1) | length) == 0
-    success_msg: |
-      [OK]  result:
-      {{ rr | to_yaml }}
-    fail_msg: |
-      [ERR] result:
-      {{ rr | to_yaml }}
-    quiet: "{{ quiet_test | d(true) | bool }}"
-  vars:
-    rr: "{{ list1 | community.general.keep_keys(target=tt) }}"
-    tt: [k0_x0, k1_x1]
-  tags: equal_default
-
-- name: Test keep keys regex string
-  ansible.builtin.assert:
-    that:
-      - (rr | difference(result1) | length) == 0
-    success_msg: |
-      [OK]  result:
-      {{ rr | to_yaml }}
-    fail_msg: |
-      [ERR] result:
-      {{ rr | to_yaml }}
-    quiet: "{{ quiet_test | d(true) | bool }}"
-  vars:
-    rr: "{{ list1 | community.general.keep_keys(target=tt, matching_parameter=mp) }}"
-    mp: regex
-    tt: '^.*[01]_x.*$'
-  tags: regex_string
-
-- name: Test keep keys targets1
-  ansible.builtin.assert:
-    that:
-      - (rr | difference(result1) | length) == 0
-    success_msg: |
-      [OK]  result:
-      {{ rr | to_yaml }}
-    fail_msg: |
-      [ERR] result:
-      {{ rr | to_yaml }}
-    quiet: "{{ quiet_test | d(true) | bool }}"
-  loop: "{{ targets1 }}"
-  loop_control:
-    label: "{{ item.mp }}: {{ item.tt }}"
-  vars:
-    rr: "{{ list1 | community.general.keep_keys(target=item.tt, matching_parameter=item.mp) }}"
-  tags: targets1
-
-- name: Test keep keys targets2
-  ansible.builtin.assert:
-    that:
-      - (rr | difference(result2) | length) == 0
-    success_msg: |
-      [OK]  result:
-      {{ rr | to_yaml }}
-    fail_msg: |
-      [ERR] result:
-      {{ rr | to_yaml }}
-    quiet: "{{ quiet_test | d(true) | bool }}"
-  loop: "{{ targets2 }}"
-  loop_control:
-    label: "{{ item.mp }}: {{ item.tt }}"
-  vars:
-    rr: "{{ list2 | community.general.keep_keys(target=item.tt, matching_parameter=item.mp) }}"
-  tags: targets2

tests/integration/targets/filter_keep_keys/tasks/main.yml

@@ -3,5 +3,5 @@
 # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-- name: Test keep_keys
+- name: Tests
-  import_tasks: keep_keys.yml
+  import_tasks: tests.yml

tests/integration/targets/filter_keep_keys/tasks/tests.yml

@@ -0,0 +1,31 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Debug ansible_version
+  ansible.builtin.debug:
+    var: ansible_version
+  when: not quite_test | d(true) | bool
+  tags: ansible_version
+
+- name: Tests
+  ansible.builtin.assert:
+    that:
+      - (result | difference(i.0.result) | length) == 0
+    success_msg: |
+      [OK]  result:
+      {{ result | to_yaml }}
+    fail_msg: |
+      [ERR] result:
+      {{ result | to_yaml }}
+    quiet: "{{ quiet_test | d(true) | bool }}"
+  loop: "{{ tests | subelements('group') }}"
+  loop_control:
+    loop_var: i
+    label: "{{ i.1.mp | d('default') }}: {{ i.1.tt }}"
+  vars:
+    input: "{{ i.0.input }}"
+    target: "{{ i.1.tt }}"
+    mp: "{{ i.1.mp | d('default') }}"
+    result: "{{ lookup('template', i.0.template) }}"

tests/integration/targets/filter_keep_keys/templates/default.j2

@@ -0,0 +1 @@
+{{ input | community.general.keep_keys(target=target) }}

tests/integration/targets/filter_keep_keys/templates/default.j2.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later

tests/integration/targets/filter_keep_keys/templates/mp.j2

@@ -0,0 +1 @@
+{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}

tests/integration/targets/filter_keep_keys/templates/mp.j2.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later

tests/integration/targets/filter_keep_keys/vars/main.yml

@@ -1,33 +0,0 @@
----
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-targets1:
-  - {mp: equal, tt: [k0_x0, k1_x1]}
-  - {mp: starts_with, tt: [k0, k1]}
-  - {mp: ends_with, tt: [x0, x1]}
-  - {mp: regex, tt: ['^.*[01]_x.*$']}
-  - {mp: regex, tt: '^.*[01]_x.*$'}
-
-list1:
-  - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
-  - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
-
-result1:
-   - {k0_x0: A0, k1_x1: B0}
-   - {k0_x0: A1, k1_x1: B1}
-
-targets2:
-  - {mp: equal, tt: k0_x0}
-  - {mp: starts_with, tt: k0}
-  - {mp: ends_with, tt: x0}
-  - {mp: regex, tt: '^.*0_x.*$'}
-
-list2:
-  - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
-  - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
-
-result2:
-   - {k0_x0: A0}
-   - {k0_x0: A1}

tests/integration/targets/filter_keep_keys/vars/main/tests.yml

@@ -0,0 +1,40 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+tests:
+  - template: default.j2
+    group:
+      - {tt: [k0_x0, k1_x1], d: 'By default, match keys that equal any of the items in the target.'}
+    input:
+      - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
+      - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
+    result:
+       - {k0_x0: A0, k1_x1: B0}
+       - {k0_x0: A1, k1_x1: B1}
+  - template: mp.j2
+    group:
+      - {mp: equal, tt: [k0_x0, k1_x1], d: Match keys that equal any of the items in the target.}
+      - {mp: starts_with, tt: [k0, k1], d: Match keys that start with any of the items in the target.}
+      - {mp: ends_with, tt: [x0, x1], d: Match keys that end with any of the items in target.}
+      - {mp: regex, tt: ['^.*[01]_x.*$'], d: Match keys by the regex.}
+      - {mp: regex, tt: '^.*[01]_x.*$', d: Match keys by the regex.}
+    input:
+      - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
+      - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
+    result:
+       - {k0_x0: A0, k1_x1: B0}
+       - {k0_x0: A1, k1_x1: B1}
+  - template: mp.j2
+    group:
+      - {mp: equal, tt: k0_x0, d: Match keys that equal the target.}
+      - {mp: starts_with, tt: k0, d: Match keys that start with the target.}
+      - {mp: ends_with, tt: x0, d: Match keys that end with the target.}
+      - {mp: regex, tt: '^.*0_x.*$', d: Match keys by the regex.}
+    input:
+      - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
+      - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
+    result:
+       - {k0_x0: A0}
+       - {k0_x0: A1}

tests/integration/targets/filter_remove_keys/tasks/main.yml

@@ -3,5 +3,5 @@
 # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-- name: Test remove_keys
+- name: Tests
-  import_tasks: remove_keys.yml
+  import_tasks: tests.yml

tests/integration/targets/filter_remove_keys/tasks/remove_keys.yml

@@ -1,79 +0,0 @@
----
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-- name: Debug ansible_version
-  ansible.builtin.debug:
-    var: ansible_version
-  when: not quite_test | d(true) | bool
-  tags: ansible_version
-
-- name: Test remove keys equal (default)
-  ansible.builtin.assert:
-    that:
-      - (rr | difference(result1) | length) == 0
-    success_msg: |
-      [OK]  result:
-      {{ rr | to_yaml }}
-    fail_msg: |
-      [ERR] result:
-      {{ rr | to_yaml }}
-    quiet: "{{ quiet_test | d(true) | bool }}"
-  vars:
-    rr: "{{ list1 | community.general.remove_keys(target=tt) }}"
-    tt: [k0_x0, k1_x1]
-  tags: equal_default
-
-- name: Test remove keys regex string
-  ansible.builtin.assert:
-    that:
-      - (rr | difference(result1) | length) == 0
-    success_msg: |
-      [OK]  result:
-      {{ rr | to_yaml }}
-    fail_msg: |
-      [ERR] result:
-      {{ rr | to_yaml }}
-    quiet: "{{ quiet_test | d(true) | bool }}"
-  vars:
-    rr: "{{ list1 | community.general.remove_keys(target=tt, matching_parameter=mp) }}"
-    mp: regex
-    tt: '^.*[01]_x.*$'
-  tags: regex_string
-
-- name: Test remove keys targets1
-  ansible.builtin.assert:
-    that:
-      - (rr | difference(result1) | length) == 0
-    success_msg: |
-      [OK]  result:
-      {{ rr | to_yaml }}
-    fail_msg: |
-      [ERR] result:
-      {{ rr | to_yaml }}
-    quiet: "{{ quiet_test | d(true) | bool }}"
-  loop: "{{ targets1 }}"
-  loop_control:
-    label: "{{ item.mp }}: {{ item.tt }}"
-  vars:
-    rr: "{{ list1 | community.general.remove_keys(target=item.tt, matching_parameter=item.mp) }}"
-  tags: targets1
-
-- name: Test remove keys targets2
-  ansible.builtin.assert:
-    that:
-      - (rr | difference(result2) | length) == 0
-    success_msg: |
-      [OK]  result:
-      {{ rr | to_yaml }}
-    fail_msg: |
-      [ERR] result:
-      {{ rr | to_yaml }}
-    quiet: "{{ quiet_test | d(true) | bool }}"
-  loop: "{{ targets2 }}"
-  loop_control:
-    label: "{{ item.mp }}: {{ item.tt }}"
-  vars:
-    rr: "{{ list2 | community.general.remove_keys(target=item.tt, matching_parameter=item.mp) }}"
-  tags: targets1

tests/integration/targets/filter_remove_keys/tasks/tests.yml

@@ -0,0 +1,31 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Debug ansible_version
+  ansible.builtin.debug:
+    var: ansible_version
+  when: not quite_test | d(true) | bool
+  tags: ansible_version
+
+- name: Tests
+  ansible.builtin.assert:
+    that:
+      - (result | difference(i.0.result) | length) == 0
+    success_msg: |
+      [OK]  result:
+      {{ result | to_yaml }}
+    fail_msg: |
+      [ERR] result:
+      {{ result | to_yaml }}
+    quiet: "{{ quiet_test | d(true) | bool }}"
+  loop: "{{ tests | subelements('group') }}"
+  loop_control:
+    loop_var: i
+    label: "{{ i.1.mp | d('default') }}: {{ i.1.tt }}"
+  vars:
+    input: "{{ i.0.input }}"
+    target: "{{ i.1.tt }}"
+    mp: "{{ i.1.mp | d('default') }}"
+    result: "{{ lookup('template', i.0.template) }}"

tests/integration/targets/filter_remove_keys/templates/default.j2

@@ -0,0 +1 @@
+{{ input | community.general.remove_keys(target=target) }}

tests/integration/targets/filter_remove_keys/templates/default.j2.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later

tests/integration/targets/filter_remove_keys/templates/mp.j2

@@ -0,0 +1 @@
+{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}

tests/integration/targets/filter_remove_keys/templates/mp.j2.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later

tests/integration/targets/filter_remove_keys/vars/main.yml

@@ -1,33 +0,0 @@
----
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-targets1:
-  - {mp: equal, tt: [k0_x0, k1_x1]}
-  - {mp: starts_with, tt: [k0, k1]}
-  - {mp: ends_with, tt: [x0, x1]}
-  - {mp: regex, tt: ['^.*[01]_x.*$']}
-  - {mp: regex, tt: '^.*[01]_x.*$'}
-
-list1:
-  - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
-  - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
-
-result1:
-  - {k2_x2: [C0], k3_x3: foo}
-  - {k2_x2: [C1], k3_x3: bar}
-
-targets2:
-  - {mp: equal, tt: k0_x0}
-  - {mp: starts_with, tt: k0}
-  - {mp: ends_with, tt: x0}
-  - {mp: regex, tt: '^.*0_x.*$'}
-
-list2:
-  - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
-  - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
-
-result2:
-  - {k1_x1: B0, k2_x2: [C0], k3_x3: foo}
-  - {k1_x1: B1, k2_x2: [C1], k3_x3: bar}

tests/integration/targets/filter_remove_keys/vars/main/tests.yml

@@ -0,0 +1,40 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+tests:
+  - template: default.j2
+    group:
+      - {tt: [k0_x0, k1_x1], d: 'By default, match keys that equal any of the items in the target.'}
+    input:
+      - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
+      - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
+    result:
+      - {k2_x2: [C0], k3_x3: foo}
+      - {k2_x2: [C1], k3_x3: bar}
+  - template: mp.j2
+    group:
+      - {mp: equal, tt: [k0_x0, k1_x1], d: Match keys that equal any of the items in the target.}
+      - {mp: starts_with, tt: [k0, k1], d: Match keys that start with any of the items in the target.}
+      - {mp: ends_with, tt: [x0, x1], d: Match keys that end with any of the items in target.}
+      - {mp: regex, tt: ['^.*[01]_x.*$'], d: Match keys by the regex.}
+      - {mp: regex, tt: '^.*[01]_x.*$', d: Match keys by the regex.}
+    input:
+      - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
+      - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
+    result:
+      - {k2_x2: [C0], k3_x3: foo}
+      - {k2_x2: [C1], k3_x3: bar}
+  - template: mp.j2
+    group:
+      - {mp: equal, tt: k0_x0, d: Match keys that equal the target.}
+      - {mp: starts_with, tt: k0, d: Match keys that start with the target.}
+      - {mp: ends_with, tt: x0, d: Match keys that end with the target.}
+      - {mp: regex, tt: '^.*0_x.*$', d: Match keys by the regex.}
+    input:
+      - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
+      - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
+    result:
+      - {k1_x1: B0, k2_x2: [C0], k3_x3: foo}
+      - {k1_x1: B1, k2_x2: [C1], k3_x3: bar} 

tests/integration/targets/filter_replace_keys/tasks/fn-test-replace_keys.yml

@@ -1,21 +0,0 @@
----
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-- name: Test replace keys
-  ansible.builtin.assert:
-    that:
-      - (rr | difference(item.result) | length) == 0
-    success_msg: |
-      [OK]  {{ item.label }}
-      result:
-        {{ rr | to_nice_yaml(indent=2) | indent(2) }}
-    fail_msg: |
-      [ERR] {{ item.label }}
-      result:
-        {{ rr | to_nice_yaml(indent=2) | indent(2) }}
-    quiet: "{{ quiet_test | d(true) | bool }}"
-  vars:
-    rr: "{{ item.data |
-            community.general.replace_keys(target=item.target, matching_parameter=item.match) }}"

tests/integration/targets/filter_replace_keys/tasks/main.yml

@@ -3,5 +3,5 @@
 # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-- name: Test replace_keys
+- name: Tests
-  import_tasks: replace_keys.yml
+  import_tasks: tests.yml

tests/integration/targets/filter_replace_keys/tasks/replace_keys.yml

@@ -1,56 +0,0 @@
----
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-- name: Debug ansible_version
-  ansible.builtin.debug:
-    var: ansible_version
-  when: not quiet_test | d(true) | bool
-  tags: ansible_version
-
-- name: Test replace keys equal (default)
-  ansible.builtin.assert:
-    that:
-      - (rr | difference(result1) | length) == 0
-    success_msg: |
-      [OK]  result:
-      {{ rr | to_yaml }}
-    fail_msg: |
-      [ERR] result:
-      {{ rr | to_yaml }}
-    quiet: "{{ quiet_test | d(true) | bool }}"
-  vars:
-    rr: "{{ list1 | community.general.replace_keys(target=tt) }}"
-    tt:
-      - {before: k0_x0, after: a0}
-      - {before: k1_x1, after: a1}
-  tags: equal_default
-
-- name: Test replace keys targets1
-  ansible.builtin.assert:
-    that:
-      - (rr | difference(result1) | length) == 0
-    success_msg: |
-      [OK]  result:
-      {{ rr | to_yaml }}
-    fail_msg: |
-      [ERR] result:
-      {{ rr | to_yaml }}
-    quiet: "{{ quiet_test | d(true) | bool }}"
-  loop: "{{ targets1 | dict2items }}"
-  loop_control:
-    label: "{{ item.key }}"
-  vars:
-    rr: "{{ list1 | community.general.replace_keys(target=item.value, matching_parameter=item.key) }}"
-  tags: targets1
-
-- name: Test replace keys targets2
-  include_tasks:
-    file: fn-test-replace_keys.yml
-    apply:
-      tags: targets2
-  loop: "{{ targets2 }}"
-  loop_control:
-    label: "{{ item.label }}"
-  tags: targets2

tests/integration/targets/filter_replace_keys/tasks/tests.yml

@@ -0,0 +1,31 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Debug ansible_version
+  ansible.builtin.debug:
+    var: ansible_version
+  when: not quite_test | d(true) | bool
+  tags: ansible_version
+
+- name: Tests
+  ansible.builtin.assert:
+    that:
+      - (result | difference(i.0.result) | length) == 0
+    success_msg: |
+      [OK]  result:
+      {{ result | to_yaml }}
+    fail_msg: |
+      [ERR] result:
+      {{ result | to_yaml }}
+    quiet: "{{ quiet_test | d(true) | bool }}"
+  loop: "{{ tests | subelements('group') }}"
+  loop_control:
+    loop_var: i
+    label: "{{ i.1.mp | d('default') }}: {{ i.1.tt }}"
+  vars:
+    input: "{{ i.0.input }}"
+    target: "{{ i.1.tt }}"
+    mp: "{{ i.1.mp | d('default') }}"
+    result: "{{ lookup('template', i.0.template) }}"

tests/integration/targets/filter_replace_keys/templates/default.j2

@@ -0,0 +1 @@
+{{ input | community.general.replace_keys(target=target) }}

tests/integration/targets/filter_replace_keys/templates/default.j2.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later

tests/integration/targets/filter_replace_keys/templates/mp.j2

@@ -0,0 +1 @@
+{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}

tests/integration/targets/filter_replace_keys/templates/mp.j2.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later

tests/integration/targets/filter_replace_keys/vars/main.yml

@@ -1,58 +0,0 @@
----
-# Copyright (c) Ansible Project
-# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
-# SPDX-License-Identifier: GPL-3.0-or-later
-
-list1:
-  - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
-  - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
-
-result1:
-  - {a0: A0, a1: B0, k2_x2: [C0], k3_x3: foo}
-  - {a0: A1, a1: B1, k2_x2: [C1], k3_x3: bar}
-
-targets1:
-  equal:
-    - {before: k0_x0, after: a0}
-    - {before: k1_x1, after: a1}
-  starts_with:
-    - {before: k0, after: a0}
-    - {before: k1, after: a1}
-  ends_with:
-    - {before: x0, after: a0}
-    - {before: x1, after: a1}
-  regex:
-    - {before: "^.*0_x.*$", after: a0}
-    - {before: "^.*1_x.*$", after: a1}
-
-list2:
-  - {aaa1: A, bbb1: B, ccc1: C}
-  - {aaa2: D, bbb2: E, ccc2: F}
-
-targets2:
-  - label: If more keys match the same attribute before the last one will be used.
-    match: regex
-    target:
-      - {before: "^.*_x.*$", after: X}
-    data: "{{ list1 }}"
-    result:
-      - X: foo
-      - X: bar
-  - label: If there are items with equal attribute before the first one will be used.
-    match: regex
-    target:
-      - {before: "^.*_x.*$", after: X}
-      - {before: "^.*_x.*$", after: Y}
-    data: "{{ list1 }}"
-    result:
-      - X: foo
-      - X: bar
-  - label: If there are more matches for a key the first one will be used.
-    match: starts_with
-    target:
-      - {before: a, after: X}
-      - {before: aa, after: Y}
-    data: "{{ list2 }}"
-    result:
-      - {X: A, bbb1: B, ccc1: C}
-      - {X: D, bbb2: E, ccc2: F}

tests/integration/targets/filter_replace_keys/vars/main/tests.yml

@@ -0,0 +1,71 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+tests:
+  - template: default.j2
+    group:
+      - d: By default, match keys that equal any of the attributes before.
+        tt:
+          - {before: k0_x0, after: a0}
+          - {before: k1_x1, after: a1}
+    input:
+      - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
+      - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
+    result:
+       - {a0: A0, a1: B0, k2_x2: [C0], k3_x3: foo}
+       - {a0: A1, a1: B1, k2_x2: [C1], k3_x3: bar}
+  - template: mp.j2
+    group:
+      - d: Replace keys that starts with any of the attributes before.
+        mp: starts_with
+        tt:
+          - {before: k0, after: a0}
+          - {before: k1, after: a1}
+      - d: Replace keys that ends with any of the attributes before.
+        mp: ends_with
+        tt:
+          - {before: x0, after: a0}
+          - {before: x1, after: a1}
+      - d: Replace keys that match any regex of the attributes before.
+        mp: regex
+        tt:
+          - {before: "^.*0_x.*$", after: a0}
+          - {before: "^.*1_x.*$", after: a1}
+    input:
+      - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
+      - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
+    result:
+       - {a0: A0, a1: B0, k2_x2: [C0], k3_x3: foo}
+       - {a0: A1, a1: B1, k2_x2: [C1], k3_x3: bar}
+  - template: mp.j2
+    group:
+      - d: If more keys match the same attribute before the last one will be used.
+        mp: regex
+        tt:
+          - {before: "^.*_x.*$", after: X}
+      - d: If there are items with equal attribute before the first one will be used.
+        mp: regex
+        tt:
+          - {before: "^.*_x.*$", after: X}
+          - {before: "^.*_x.*$", after: Y}
+    input:
+      - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
+      - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
+    result:
+       - X: foo
+       - X: bar
+  - template: mp.j2
+    group:
+      - d: If there are more matches for a key the first one will be used.
+        mp: starts_with
+        tt:
+          - {before: a, after: X}
+          - {before: aa, after: Y}
+    input:
+      - {aaa1: A, bbb1: B, ccc1: C}
+      - {aaa2: D, bbb2: E, ccc2: F}
+    result:
+      - {X: A, bbb1: B, ccc1: C}
+      - {X: D, bbb2: E, ccc2: F}