Feature filter replace_keys (#8446)

* Add filter replace_keys.

* Update examples and integration tests.

* Fix examples and copyright.

* Update documentation, examples and integration tests.

* Implement #8445. Add filter replace_keys

* Fix documentation formatting.

* Fix documentation.

* Fix type(target). Formatting improved.

* Instead of a dictionary, _keys_filter_target_dict returns a list

* No target testing in _keys_filter_params
* Interface changed _keys_filter_params(data, matching_parameter)
* If there are items with equal C(before) the B(first) one will be used.

* Update remove_keys. Interface changed _keys_filter_params(data, matching_parameter)

* The target can't be empty also in _keys_filter_target_dict

* Update plugins/filter/replace_keys.py

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

* Update plugins/filter/replace_keys.py

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

* Update plugins/filter/replace_keys.py

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

* Test attributes before and after are strings in the iteration of target.

* Update plugins/filter/replace_keys.py

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

---------

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

tests/integration/targets/filter_replace_keys/aliases

@@ -0,0 +1,5 @@
+# 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
+
+azp/posix/2

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

@@ -0,0 +1,21 @@
+---
+# 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

@@ -0,0 +1,7 @@
+---
+# 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
+  import_tasks: replace_keys.yml

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

@@ -0,0 +1,56 @@
+---
+# 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/vars/main.yml

@@ -0,0 +1,58 @@
+---
+# 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}