diff --git a/docs/docsite/helper/lists_mergeby/default-common.yml b/docs/docsite/helper/lists_mergeby/default-common.yml new file mode 100644 index 0000000000..ff6a31df6e --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/default-common.yml @@ -0,0 +1,12 @@ +list1: + - name: foo + extra: true + - name: bar + extra: false + - name: meh + extra: true +list2: + - name: foo + path: /foo + - name: baz + path: /baz diff --git a/docs/docsite/helper/lists_mergeby/default-recursive-true.yml b/docs/docsite/helper/lists_mergeby/default-recursive-true.yml new file mode 100644 index 0000000000..7d8a7cf640 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/default-recursive-true.yml @@ -0,0 +1,19 @@ +list1: + - name: myname01 + param01: + x: default_value + y: default_value + list: + - default_value + - name: myname02 + param01: [1, 1, 2, 3] + +list2: + - name: myname01 + param01: + y: patch_value + z: patch_value + list: + - patch_value + - name: myname02 + param01: [3, 4, 4, {key: value}] diff --git a/docs/docsite/helper/lists_mergeby/example-001.yml b/docs/docsite/helper/lists_mergeby/example-001.yml new file mode 100644 index 0000000000..d1cbb4b3b4 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-001.yml @@ -0,0 +1,10 @@ +--- +- name: 1. Merge two lists by common attribute 'name' + include_vars: + dir: example-001_vars +- debug: + var: list3 + when: debug|d(false)|bool +- template: + src: list3.out.j2 + dest: example-001.out diff --git a/docs/docsite/helper/lists_mergeby/example-001_vars/default-common.yml b/docs/docsite/helper/lists_mergeby/example-001_vars/default-common.yml new file mode 120000 index 0000000000..7ea8984a8d --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-001_vars/default-common.yml @@ -0,0 +1 @@ +../default-common.yml \ No newline at end of file diff --git a/docs/docsite/helper/lists_mergeby/example-001_vars/list3.yml b/docs/docsite/helper/lists_mergeby/example-001_vars/list3.yml new file mode 100644 index 0000000000..4ecfb0a6c6 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-001_vars/list3.yml @@ -0,0 +1,2 @@ +list3: "{{ list1| + community.general.lists_mergeby(list2, 'name') }}" diff --git a/docs/docsite/helper/lists_mergeby/example-002.yml b/docs/docsite/helper/lists_mergeby/example-002.yml new file mode 100644 index 0000000000..d21441a8df --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-002.yml @@ -0,0 +1,10 @@ +--- +- name: 2. Merge two lists by common attribute 'name' + include_vars: + dir: example-002_vars +- debug: + var: list3 + when: debug|d(false)|bool +- template: + src: list3.out.j2 + dest: example-002.out diff --git a/docs/docsite/helper/lists_mergeby/example-002_vars/default-common.yml b/docs/docsite/helper/lists_mergeby/example-002_vars/default-common.yml new file mode 120000 index 0000000000..7ea8984a8d --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-002_vars/default-common.yml @@ -0,0 +1 @@ +../default-common.yml \ No newline at end of file diff --git a/docs/docsite/helper/lists_mergeby/example-002_vars/list3.yml b/docs/docsite/helper/lists_mergeby/example-002_vars/list3.yml new file mode 100644 index 0000000000..9eb6775f44 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-002_vars/list3.yml @@ -0,0 +1,2 @@ +list3: "{{ [list1, list2]| + community.general.lists_mergeby('name') }}" diff --git a/docs/docsite/helper/lists_mergeby/example-003.yml b/docs/docsite/helper/lists_mergeby/example-003.yml new file mode 100644 index 0000000000..7692278609 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-003.yml @@ -0,0 +1,10 @@ +--- +- name: 3. Merge recursive by 'name', replace lists (default) + include_vars: + dir: example-003_vars +- debug: + var: list3 + when: debug|d(false)|bool +- template: + src: list3.out.j2 + dest: example-003.out diff --git a/docs/docsite/helper/lists_mergeby/example-003_vars/default-recursive-true.yml b/docs/docsite/helper/lists_mergeby/example-003_vars/default-recursive-true.yml new file mode 120000 index 0000000000..299736f8ad --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-003_vars/default-recursive-true.yml @@ -0,0 +1 @@ +../default-recursive-true.yml \ No newline at end of file diff --git a/docs/docsite/helper/lists_mergeby/example-003_vars/list3.yml b/docs/docsite/helper/lists_mergeby/example-003_vars/list3.yml new file mode 100644 index 0000000000..6d6bf8a478 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-003_vars/list3.yml @@ -0,0 +1,3 @@ +list3: "{{ [list1, list2]| + community.general.lists_mergeby('name', + recursive=true) }}" diff --git a/docs/docsite/helper/lists_mergeby/example-004.yml b/docs/docsite/helper/lists_mergeby/example-004.yml new file mode 100644 index 0000000000..8a473a7328 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-004.yml @@ -0,0 +1,10 @@ +--- +- name: 4. Merge recursive by 'name', keep lists + include_vars: + dir: example-004_vars +- debug: + var: list3 + when: debug|d(false)|bool +- template: + src: list3.out.j2 + dest: example-004.out diff --git a/docs/docsite/helper/lists_mergeby/example-004_vars/default-recursive-true.yml b/docs/docsite/helper/lists_mergeby/example-004_vars/default-recursive-true.yml new file mode 120000 index 0000000000..299736f8ad --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-004_vars/default-recursive-true.yml @@ -0,0 +1 @@ +../default-recursive-true.yml \ No newline at end of file diff --git a/docs/docsite/helper/lists_mergeby/example-004_vars/list3.yml b/docs/docsite/helper/lists_mergeby/example-004_vars/list3.yml new file mode 100644 index 0000000000..a525ae4f69 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-004_vars/list3.yml @@ -0,0 +1,4 @@ +list3: "{{ [list1, list2]| + community.general.lists_mergeby('name', + recursive=true, + list_merge='keep') }}" diff --git a/docs/docsite/helper/lists_mergeby/example-005.yml b/docs/docsite/helper/lists_mergeby/example-005.yml new file mode 100644 index 0000000000..8bdf92c359 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-005.yml @@ -0,0 +1,10 @@ +--- +- name: 5. Merge recursive by 'name', append lists + include_vars: + dir: example-005_vars +- debug: + var: list3 + when: debug|d(false)|bool +- template: + src: list3.out.j2 + dest: example-005.out diff --git a/docs/docsite/helper/lists_mergeby/example-005_vars/default-recursive-true.yml b/docs/docsite/helper/lists_mergeby/example-005_vars/default-recursive-true.yml new file mode 120000 index 0000000000..299736f8ad --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-005_vars/default-recursive-true.yml @@ -0,0 +1 @@ +../default-recursive-true.yml \ No newline at end of file diff --git a/docs/docsite/helper/lists_mergeby/example-005_vars/list3.yml b/docs/docsite/helper/lists_mergeby/example-005_vars/list3.yml new file mode 100644 index 0000000000..650686104b --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-005_vars/list3.yml @@ -0,0 +1,4 @@ +list3: "{{ [list1, list2]| + community.general.lists_mergeby('name', + recursive=true, + list_merge='append') }}" diff --git a/docs/docsite/helper/lists_mergeby/example-006.yml b/docs/docsite/helper/lists_mergeby/example-006.yml new file mode 100644 index 0000000000..9dcb9b684d --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-006.yml @@ -0,0 +1,10 @@ +--- +- name: 6. Merge recursive by 'name', prepend lists + include_vars: + dir: example-006_vars +- debug: + var: list3 + when: debug|d(false)|bool +- template: + src: list3.out.j2 + dest: example-006.out diff --git a/docs/docsite/helper/lists_mergeby/example-006_vars/default-recursive-true.yml b/docs/docsite/helper/lists_mergeby/example-006_vars/default-recursive-true.yml new file mode 120000 index 0000000000..299736f8ad --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-006_vars/default-recursive-true.yml @@ -0,0 +1 @@ +../default-recursive-true.yml \ No newline at end of file diff --git a/docs/docsite/helper/lists_mergeby/example-006_vars/list3.yml b/docs/docsite/helper/lists_mergeby/example-006_vars/list3.yml new file mode 100644 index 0000000000..d880dfa9f0 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-006_vars/list3.yml @@ -0,0 +1,4 @@ +list3: "{{ [list1, list2]| + community.general.lists_mergeby('name', + recursive=true, + list_merge='prepend') }}" diff --git a/docs/docsite/helper/lists_mergeby/example-007.yml b/docs/docsite/helper/lists_mergeby/example-007.yml new file mode 100644 index 0000000000..e1a6f2c7e3 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-007.yml @@ -0,0 +1,10 @@ +--- +- name: 7. Merge recursive by 'name', append lists 'remove present' + include_vars: + dir: example-007_vars +- debug: + var: list3 + when: debug|d(false)|bool +- template: + src: list3.out.j2 + dest: example-007.out diff --git a/docs/docsite/helper/lists_mergeby/example-007_vars/default-recursive-true.yml b/docs/docsite/helper/lists_mergeby/example-007_vars/default-recursive-true.yml new file mode 120000 index 0000000000..299736f8ad --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-007_vars/default-recursive-true.yml @@ -0,0 +1 @@ +../default-recursive-true.yml \ No newline at end of file diff --git a/docs/docsite/helper/lists_mergeby/example-007_vars/list3.yml b/docs/docsite/helper/lists_mergeby/example-007_vars/list3.yml new file mode 100644 index 0000000000..af71d6dfd5 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-007_vars/list3.yml @@ -0,0 +1,4 @@ +list3: "{{ [list1, list2]| + community.general.lists_mergeby('name', + recursive=true, + list_merge='append_rp') }}" diff --git a/docs/docsite/helper/lists_mergeby/example-008.yml b/docs/docsite/helper/lists_mergeby/example-008.yml new file mode 100644 index 0000000000..18a598864a --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-008.yml @@ -0,0 +1,10 @@ +--- +- name: 8. Merge recursive by 'name', prepend lists 'remove present' + include_vars: + dir: example-008_vars +- debug: + var: list3 + when: debug|d(false)|bool +- template: + src: list3.out.j2 + dest: example-008.out diff --git a/docs/docsite/helper/lists_mergeby/example-008_vars/default-recursive-true.yml b/docs/docsite/helper/lists_mergeby/example-008_vars/default-recursive-true.yml new file mode 120000 index 0000000000..299736f8ad --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-008_vars/default-recursive-true.yml @@ -0,0 +1 @@ +../default-recursive-true.yml \ No newline at end of file diff --git a/docs/docsite/helper/lists_mergeby/example-008_vars/list3.yml b/docs/docsite/helper/lists_mergeby/example-008_vars/list3.yml new file mode 100644 index 0000000000..8a20578507 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/example-008_vars/list3.yml @@ -0,0 +1,4 @@ +list3: "{{ [list1, list2]| + community.general.lists_mergeby('name', + recursive=true, + list_merge='prepend_rp') }}" diff --git a/docs/docsite/helper/lists_mergeby/examples.yml b/docs/docsite/helper/lists_mergeby/examples.yml index 3a8110a098..1e798cb8dc 100644 --- a/docs/docsite/helper/lists_mergeby/examples.yml +++ b/docs/docsite/helper/lists_mergeby/examples.yml @@ -1,37 +1,49 @@ --- examples: + - label: 'In the example below the lists are merged by the attribute ``name``:' + file: example-001_vars/list3.yml + lang: 'yaml+jinja' + - label: 'This produces:' + file: example-001.out + lang: 'yaml' + - label: 'It is possible to use a list of lists as an input of the filter:' + file: example-002_vars/list3.yml + lang: 'yaml+jinja' + - label: 'This produces the same result as in the previous example:' + file: example-002.out + lang: 'yaml' - label: 'Example ``list_merge=replace`` (default):' - file: example-003.yml + file: example-003_vars/list3.yml lang: 'yaml+jinja' - label: 'This produces:' file: example-003.out lang: 'yaml' - label: 'Example ``list_merge=keep``:' - file: example-004.yml + file: example-004_vars/list3.yml lang: 'yaml+jinja' - label: 'This produces:' file: example-004.out lang: 'yaml' - label: 'Example ``list_merge=append``:' - file: example-005.yml + file: example-005_vars/list3.yml lang: 'yaml+jinja' - label: 'This produces:' file: example-005.out lang: 'yaml' - label: 'Example ``list_merge=prepend``:' - file: example-006.yml + file: example-006_vars/list3.yml lang: 'yaml+jinja' - label: 'This produces:' file: example-006.out lang: 'yaml' - label: 'Example ``list_merge=append_rp``:' - file: example-007.yml + file: example-007_vars/list3.yml lang: 'yaml+jinja' - label: 'This produces:' file: example-007.out lang: 'yaml' - label: 'Example ``list_merge=prepend_rp``:' - file: example-008.yml + file: example-008_vars/list3.yml lang: 'yaml+jinja' - label: 'This produces:' file: example-008.out diff --git a/docs/docsite/helper/lists_mergeby/examples.rst.j2 b/docs/docsite/helper/lists_mergeby/examples_all.rst.j2 similarity index 60% rename from docs/docsite/helper/lists_mergeby/examples.rst.j2 rename to docs/docsite/helper/lists_mergeby/examples_all.rst.j2 index d6abeb1108..014ff2d112 100644 --- a/docs/docsite/helper/lists_mergeby/examples.rst.j2 +++ b/docs/docsite/helper/lists_mergeby/examples_all.rst.j2 @@ -3,6 +3,6 @@ .. code-block:: {{ i.lang }} - {{ lookup('file', source_path ~ i.file)|indent(2) }} + {{ lookup('file', i.file)|indent(2) }} {% endfor %} diff --git a/docs/docsite/helper/lists_mergeby/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst.j2 b/docs/docsite/helper/lists_mergeby/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst.j2 new file mode 100644 index 0000000000..fc13b998f1 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst.j2 @@ -0,0 +1,57 @@ +Merging lists of dictionaries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you have two or more lists of dictionaries and want to combine them into a list of merged dictionaries, where the dictionaries are merged by an attribute, you can use the ``lists_mergeby`` filter. + +.. 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 :ref:`the documentation for the community.general.yaml callback plugin `. + +Let us use the lists below in the following examples + +.. code-block:: yaml + + {{ lookup('file', 'default-common.yml')|indent(2) }} + +{% for i in examples[0:2] %} +{{ i.label }} + +.. code-block:: {{ i.lang }} + + {{ lookup('file', i.file)|indent(2) }} + +{% endfor %} + +.. versionadded:: 2.0.0 + +{% for i in examples[2:4] %} +{{ i.label }} + +.. code-block:: {{ i.lang }} + + {{ lookup('file', i.file)|indent(2) }} + +{% endfor %} + +The filter also accepts two optional parameters: ``recursive`` and ``list_merge``. These parameters are only supported when used with ansible-base 2.10 or ansible-core, but not with Ansible 2.9. This is available since community.general 4.4.0. + +**recursive** + Is a boolean, default to ``False``. Should the ``community.general.lists_mergeby`` recursively merge nested hashes. Note: It does not depend on the value of the ``hash_behaviour`` setting in ``ansible.cfg``. + +**list_merge** + Is a string, its possible values are ``replace`` (default), ``keep``, ``append``, ``prepend``, ``append_rp`` or ``prepend_rp``. It modifies the behaviour of ``community.general.lists_mergeby`` when the hashes to merge contain arrays/lists. + +The examples below set ``recursive=true`` and display the differences among all six options of ``list_merge``. Functionality of the parameters is exactly the same as in the filter ``combine``. See :ref:`Combining hashes/dictionaries ` to learn details about these options. + +Let us use the lists below in the following examples + +.. code-block:: yaml + + {{ lookup('file', 'default-recursive-true.yml')|indent(2) }} + +{% for i in examples[4:16] %} +{{ i.label }} + +.. code-block:: {{ i.lang }} + + {{ lookup('file', i.file)|indent(2) }} + +{% endfor %} diff --git a/docs/docsite/helper/lists_mergeby/list3.out.j2 b/docs/docsite/helper/lists_mergeby/list3.out.j2 new file mode 100644 index 0000000000..f2f1e6c8e7 --- /dev/null +++ b/docs/docsite/helper/lists_mergeby/list3.out.j2 @@ -0,0 +1,2 @@ +list3: + {{ list3|to_nice_yaml|indent(2) }} diff --git a/docs/docsite/helper/lists_mergeby/playbook.yml b/docs/docsite/helper/lists_mergeby/playbook.yml index c31e1853ff..6fc2a71cc0 100644 --- a/docs/docsite/helper/lists_mergeby/playbook.yml +++ b/docs/docsite/helper/lists_mergeby/playbook.yml @@ -1,41 +1,49 @@ --- -# The following runs all examples: +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# 1) Run all examples and create example-XXX.out +# shell> ansible-playbook playbook.yml -e examples=true # -# ANSIBLE_STDOUT_CALLBACK=community.general.yaml ansible-playbook playbook.yml -e examples=true +# 2) Optionally, create examples_all.rst +# shell> ansible-playbook playbook.yml -e examples_all=true # -# You need to copy the YAML output of example-XXX.yml into example-XXX.out. -# -# The following generates examples.rst out of the .out files: -# -# ansible-playbook playbook.yml -e template=true +# 3) Create other REST files. See the blocks below. +# shell> ansible-playbook playbook.yml -e merging_lists_of_dictionaries=true +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# docs/docsite/helper/lists_mergeby/playbook.yml + - hosts: localhost gather_facts: false - vars: - source_path: ../../rst/examples/lists_mergeby/ tasks: - block: - - import_tasks: '{{ source_path }}example-001.yml' + - import_tasks: example-001.yml tags: t001 - - import_tasks: '{{ source_path }}example-002.yml' + - import_tasks: example-002.yml tags: t002 - - import_tasks: '{{ source_path }}example-003.yml' + - import_tasks: example-003.yml tags: t003 - - import_tasks: '{{ source_path }}example-004.yml' + - import_tasks: example-004.yml tags: t004 - - import_tasks: '{{ source_path }}example-005.yml' + - import_tasks: example-005.yml tags: t005 - - import_tasks: '{{ source_path }}example-006.yml' + - import_tasks: example-006.yml tags: t006 - - import_tasks: '{{ source_path }}example-007.yml' + - import_tasks: example-007.yml tags: t007 - - import_tasks: '{{ source_path }}example-008.yml' + - import_tasks: example-008.yml tags: t008 when: examples|d(false)|bool - block: - include_vars: examples.yml - template: - src: examples.rst.j2 - dest: examples.rst - when: template|d(false)|bool + src: examples_all.rst.j2 + dest: examples_all.rst + when: examples_all|d(false)|bool + + - block: + - include_vars: examples.yml + - template: + src: filter_guide_abstract_informations_merging_lists_of_dictionaries.rst.j2 + dest: filter_guide_abstract_informations_merging_lists_of_dictionaries.rst + when: merging_lists_of_dictionaries|d(false)|bool diff --git a/docs/docsite/rst/examples/lists_mergeby/example-001.out b/docs/docsite/rst/examples/lists_mergeby/example-001.out deleted file mode 100644 index 879c2cadb7..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-001.out +++ /dev/null @@ -1,10 +0,0 @@ - list3: - - extra: false - name: bar - - name: baz - path: /baz - - extra: true - name: foo - path: /foo - - extra: true - name: meh diff --git a/docs/docsite/rst/examples/lists_mergeby/example-001.yml b/docs/docsite/rst/examples/lists_mergeby/example-001.yml deleted file mode 100644 index 3284dbddfd..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-001.yml +++ /dev/null @@ -1,20 +0,0 @@ ---- -- name: Merge two lists by common attribute 'name' - set_fact: - list3: "{{ list1| - community.general.lists_mergeby(list2, 'name') }}" - vars: - list1: - - name: foo - extra: true - - name: bar - extra: false - - name: meh - extra: true - list2: - - name: foo - path: /foo - - name: baz - path: /baz -- debug: - var: list3 diff --git a/docs/docsite/rst/examples/lists_mergeby/example-002.out b/docs/docsite/rst/examples/lists_mergeby/example-002.out deleted file mode 100644 index 879c2cadb7..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-002.out +++ /dev/null @@ -1,10 +0,0 @@ - list3: - - extra: false - name: bar - - name: baz - path: /baz - - extra: true - name: foo - path: /foo - - extra: true - name: meh diff --git a/docs/docsite/rst/examples/lists_mergeby/example-002.yml b/docs/docsite/rst/examples/lists_mergeby/example-002.yml deleted file mode 100644 index d8a3ddf529..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-002.yml +++ /dev/null @@ -1,20 +0,0 @@ ---- -- name: Merge two lists by common attribute 'name' - set_fact: - list3: "{{ [list1, list2]| - community.general.lists_mergeby('name') }}" - vars: - list1: - - name: foo - extra: true - - name: bar - extra: false - - name: meh - extra: true - list2: - - name: foo - path: /foo - - name: baz - path: /baz -- debug: - var: list3 diff --git a/docs/docsite/rst/examples/lists_mergeby/example-003.out b/docs/docsite/rst/examples/lists_mergeby/example-003.out deleted file mode 100644 index 62ba8def2c..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-003.out +++ /dev/null @@ -1,14 +0,0 @@ - list3: - - name: myname01 - param01: - list: - - patch_value - x: default_value - y: patch_value - z: patch_value - - name: myname02 - param01: - - 3 - - 4 - - 4 - - key: value diff --git a/docs/docsite/rst/examples/lists_mergeby/example-003.yml b/docs/docsite/rst/examples/lists_mergeby/example-003.yml deleted file mode 100644 index 7dbbcae63e..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-003.yml +++ /dev/null @@ -1,28 +0,0 @@ ---- -- name: Merge recursive by 'name', replace lists (default) - set_fact: - list3: "{{ [list1, list2]| - community.general.lists_mergeby('name', - recursive=true) }}" - vars: - list1: - - name: myname01 - param01: - x: default_value - y: default_value - list: - - default_value - - name: myname02 - param01: [1, 1, 2, 3] - - list2: - - name: myname01 - param01: - y: patch_value - z: patch_value - list: - - patch_value - - name: myname02 - param01: [3, 4, 4, {key: value}] -- debug: - var: list3 diff --git a/docs/docsite/rst/examples/lists_mergeby/example-004.out b/docs/docsite/rst/examples/lists_mergeby/example-004.out deleted file mode 100644 index 18d1d12a02..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-004.out +++ /dev/null @@ -1,14 +0,0 @@ - list3: - - name: myname01 - param01: - list: - - default_value - x: default_value - y: patch_value - z: patch_value - - name: myname02 - param01: - - 1 - - 1 - - 2 - - 3 diff --git a/docs/docsite/rst/examples/lists_mergeby/example-004.yml b/docs/docsite/rst/examples/lists_mergeby/example-004.yml deleted file mode 100644 index 26c1089137..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-004.yml +++ /dev/null @@ -1,29 +0,0 @@ ---- -- name: Merge recursive by 'name', keep lists - set_fact: - list3: "{{ [list1, list2]| - community.general.lists_mergeby('name', - recursive=true, - list_merge='keep') }}" - vars: - list1: - - name: myname01 - param01: - x: default_value - y: default_value - list: - - default_value - - name: myname02 - param01: [1, 1, 2, 3] - - list2: - - name: myname01 - param01: - y: patch_value - z: patch_value - list: - - patch_value - - name: myname02 - param01: [3, 4, 4, {key: value}] -- debug: - var: list3 diff --git a/docs/docsite/rst/examples/lists_mergeby/example-005.out b/docs/docsite/rst/examples/lists_mergeby/example-005.out deleted file mode 100644 index 5fff8638db..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-005.out +++ /dev/null @@ -1,19 +0,0 @@ - list3: - - name: myname01 - param01: - list: - - default_value - - patch_value - x: default_value - y: patch_value - z: patch_value - - name: myname02 - param01: - - 1 - - 1 - - 2 - - 3 - - 3 - - 4 - - 4 - - key: value diff --git a/docs/docsite/rst/examples/lists_mergeby/example-005.yml b/docs/docsite/rst/examples/lists_mergeby/example-005.yml deleted file mode 100644 index f2d76059e8..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-005.yml +++ /dev/null @@ -1,29 +0,0 @@ ---- -- name: Merge recursive by 'name', append lists - set_fact: - list3: "{{ [list1, list2]| - community.general.lists_mergeby('name', - recursive=true, - list_merge='append') }}" - vars: - list1: - - name: myname01 - param01: - x: default_value - y: default_value - list: - - default_value - - name: myname02 - param01: [1, 1, 2, 3] - - list2: - - name: myname01 - param01: - y: patch_value - z: patch_value - list: - - patch_value - - name: myname02 - param01: [3, 4, 4, {key: value}] -- debug: - var: list3 diff --git a/docs/docsite/rst/examples/lists_mergeby/example-006.out b/docs/docsite/rst/examples/lists_mergeby/example-006.out deleted file mode 100644 index 2c0e0652f1..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-006.out +++ /dev/null @@ -1,19 +0,0 @@ - list3: - - name: myname01 - param01: - list: - - patch_value - - default_value - x: default_value - y: patch_value - z: patch_value - - name: myname02 - param01: - - 3 - - 4 - - 4 - - key: value - - 1 - - 1 - - 2 - - 3 diff --git a/docs/docsite/rst/examples/lists_mergeby/example-006.yml b/docs/docsite/rst/examples/lists_mergeby/example-006.yml deleted file mode 100644 index 91e18a00a1..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-006.yml +++ /dev/null @@ -1,29 +0,0 @@ ---- -- name: Merge recursive by 'name', prepend lists - set_fact: - list3: "{{ [list1, list2]| - community.general.lists_mergeby('name', - recursive=true, - list_merge='prepend') }}" - vars: - list1: - - name: myname01 - param01: - x: default_value - y: default_value - list: - - default_value - - name: myname02 - param01: [1, 1, 2, 3] - - list2: - - name: myname01 - param01: - y: patch_value - z: patch_value - list: - - patch_value - - name: myname02 - param01: [3, 4, 4, {key: value}] -- debug: - var: list3 diff --git a/docs/docsite/rst/examples/lists_mergeby/example-007.out b/docs/docsite/rst/examples/lists_mergeby/example-007.out deleted file mode 100644 index 516ea026f8..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-007.out +++ /dev/null @@ -1,18 +0,0 @@ - list3: - - name: myname01 - param01: - list: - - default_value - - patch_value - x: default_value - y: patch_value - z: patch_value - - name: myname02 - param01: - - 1 - - 1 - - 2 - - 3 - - 4 - - 4 - - key: value diff --git a/docs/docsite/rst/examples/lists_mergeby/example-007.yml b/docs/docsite/rst/examples/lists_mergeby/example-007.yml deleted file mode 100644 index 46139e58f8..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-007.yml +++ /dev/null @@ -1,29 +0,0 @@ ---- -- name: Merge recursive by 'name', append lists 'remove present' - set_fact: - list3: "{{ [list1, list2]| - community.general.lists_mergeby('name', - recursive=true, - list_merge='append_rp') }}" - vars: - list1: - - name: myname01 - param01: - x: default_value - y: default_value - list: - - default_value - - name: myname02 - param01: [1, 1, 2, 3] - - list2: - - name: myname01 - param01: - y: patch_value - z: patch_value - list: - - patch_value - - name: myname02 - param01: [3, 4, 4, {key: value}] -- debug: - var: list3 diff --git a/docs/docsite/rst/examples/lists_mergeby/example-008.out b/docs/docsite/rst/examples/lists_mergeby/example-008.out deleted file mode 100644 index 838cee02a3..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-008.out +++ /dev/null @@ -1,18 +0,0 @@ - list3: - - name: myname01 - param01: - list: - - patch_value - - default_value - x: default_value - y: patch_value - z: patch_value - - name: myname02 - param01: - - 3 - - 4 - - 4 - - key: value - - 1 - - 1 - - 2 diff --git a/docs/docsite/rst/examples/lists_mergeby/example-008.yml b/docs/docsite/rst/examples/lists_mergeby/example-008.yml deleted file mode 100644 index adcdcc78a3..0000000000 --- a/docs/docsite/rst/examples/lists_mergeby/example-008.yml +++ /dev/null @@ -1,29 +0,0 @@ ---- -- name: Merge recursive by 'name', prepend lists 'remove present' - set_fact: - list3: "{{ [list1, list2]| - community.general.lists_mergeby('name', - recursive=true, - list_merge='prepend_rp') }}" - vars: - list1: - - name: myname01 - param01: - x: default_value - y: default_value - list: - - default_value - - name: myname02 - param01: [1, 1, 2, 3] - - list2: - - name: myname01 - param01: - y: patch_value - z: patch_value - list: - - patch_value - - name: myname02 - param01: [3, 4, 4, {key: value}] -- debug: - var: list3 diff --git a/docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst b/docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst index 5e09103bb0..026454155d 100644 --- a/docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst +++ b/docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst @@ -5,45 +5,45 @@ If you have two or more lists of dictionaries and want to combine them into a li .. 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 :ref:`the documentation for the community.general.yaml callback plugin `. +Let us use the lists below in the following examples + +.. code-block:: yaml + + list1: + - name: foo + extra: true + - name: bar + extra: false + - name: meh + extra: true + list2: + - name: foo + path: /foo + - name: baz + path: /baz + In the example below the lists are merged by the attribute ``name``: .. code-block:: yaml+jinja - --- - - name: Merge two lists by common attribute 'name' - set_fact: - list3: "{{ list1| - community.general.lists_mergeby(list2, 'name') }}" - vars: - list1: - - name: foo - extra: true - - name: bar - extra: false - - name: meh - extra: true - list2: - - name: foo - path: /foo - - name: baz - path: /baz - - debug: - var: list3 + list3: "{{ list1| + community.general.lists_mergeby(list2, 'name') }}" This produces: .. code-block:: yaml list3: - - extra: false - name: bar - - name: baz - path: /baz - - extra: true - name: foo - path: /foo - - extra: true - name: meh + - extra: false + name: bar + - name: baz + path: /baz + - extra: true + name: foo + path: /foo + - extra: true + name: meh + .. versionadded:: 2.0.0 @@ -51,41 +51,24 @@ It is possible to use a list of lists as an input of the filter: .. code-block:: yaml+jinja - --- - - name: Merge two lists by common attribute 'name' - set_fact: - list3: "{{ [list1, list2]| - community.general.lists_mergeby('name') }}" - vars: - list1: - - name: foo - extra: true - - name: bar - extra: false - - name: meh - extra: true - list2: - - name: foo - path: /foo - - name: baz - path: /baz - - debug: - var: list3 + list3: "{{ [list1, list2]| + community.general.lists_mergeby('name') }}" This produces the same result as in the previous example: .. code-block:: yaml list3: - - extra: false - name: bar - - name: baz - path: /baz - - extra: true - name: foo - path: /foo - - extra: true - name: meh + - extra: false + name: bar + - name: baz + path: /baz + - extra: true + name: foo + path: /foo + - extra: true + name: meh + The filter also accepts two optional parameters: ``recursive`` and ``list_merge``. These parameters are only supported when used with ansible-base 2.10 or ansible-core, but not with Ansible 2.9. This is available since community.general 4.4.0. @@ -97,337 +80,212 @@ The filter also accepts two optional parameters: ``recursive`` and ``list_merge` The examples below set ``recursive=true`` and display the differences among all six options of ``list_merge``. Functionality of the parameters is exactly the same as in the filter ``combine``. See :ref:`Combining hashes/dictionaries ` to learn details about these options. +Let us use the lists below in the following examples + +.. code-block:: yaml + + list1: + - name: myname01 + param01: + x: default_value + y: default_value + list: + - default_value + - name: myname02 + param01: [1, 1, 2, 3] + + list2: + - name: myname01 + param01: + y: patch_value + z: patch_value + list: + - patch_value + - name: myname02 + param01: [3, 4, 4, {key: value}] + Example ``list_merge=replace`` (default): .. code-block:: yaml+jinja - --- - - name: Merge recursive by 'name', replace lists (default) - set_fact: - list3: "{{ [list1, list2]| - community.general.lists_mergeby('name', - recursive=true) }}" - vars: - list1: - - name: myname01 - param01: - x: default_value - y: default_value - list: - - default_value - - name: myname02 - param01: [1, 1, 2, 3] - - list2: - - name: myname01 - param01: - y: patch_value - z: patch_value - list: - - patch_value - - name: myname02 - param01: [3, 4, 4, {key: value}] - - debug: - var: list3 + list3: "{{ [list1, list2]| + community.general.lists_mergeby('name', + recursive=true) }}" This produces: .. code-block:: yaml - list3: - - name: myname01 - param01: - list: - - patch_value - x: default_value - y: patch_value - z: patch_value - - name: myname02 - param01: - - 3 - - 4 - - 4 - - key: value + list3: + - name: myname01 + param01: + list: + - patch_value + x: default_value + y: patch_value + z: patch_value + - name: myname02 + param01: + - 3 + - 4 + - 4 + - key: value Example ``list_merge=keep``: .. code-block:: yaml+jinja - --- - - name: Merge recursive by 'name', keep lists - set_fact: - list3: "{{ [list1, list2]| - community.general.lists_mergeby('name', - recursive=true, - list_merge='keep') }}" - vars: - list1: - - name: myname01 - param01: - x: default_value - y: default_value - list: - - default_value - - name: myname02 - param01: [1, 1, 2, 3] - - list2: - - name: myname01 - param01: - y: patch_value - z: patch_value - list: - - patch_value - - name: myname02 - param01: [3, 4, 4, {key: value}] - - debug: - var: list3 + list3: "{{ [list1, list2]| + community.general.lists_mergeby('name', + recursive=true, + list_merge='keep') }}" This produces: .. code-block:: yaml - list3: - - name: myname01 - param01: - list: - - default_value - x: default_value - y: patch_value - z: patch_value - - name: myname02 - param01: - - 1 - - 1 - - 2 - - 3 + list3: + - name: myname01 + param01: + list: + - default_value + x: default_value + y: patch_value + z: patch_value + - name: myname02 + param01: + - 1 + - 1 + - 2 + - 3 Example ``list_merge=append``: .. code-block:: yaml+jinja - --- - - name: Merge recursive by 'name', append lists - set_fact: - list3: "{{ [list1, list2]| - community.general.lists_mergeby('name', - recursive=true, - list_merge='append') }}" - vars: - list1: - - name: myname01 - param01: - x: default_value - y: default_value - list: - - default_value - - name: myname02 - param01: [1, 1, 2, 3] - - list2: - - name: myname01 - param01: - y: patch_value - z: patch_value - list: - - patch_value - - name: myname02 - param01: [3, 4, 4, {key: value}] - - debug: - var: list3 + list3: "{{ [list1, list2]| + community.general.lists_mergeby('name', + recursive=true, + list_merge='append') }}" This produces: .. code-block:: yaml - list3: - - name: myname01 - param01: - list: - - default_value - - patch_value - x: default_value - y: patch_value - z: patch_value - - name: myname02 - param01: - - 1 - - 1 - - 2 - - 3 - - 3 - - 4 - - 4 - - key: value + list3: + - name: myname01 + param01: + list: + - default_value + - patch_value + x: default_value + y: patch_value + z: patch_value + - name: myname02 + param01: + - 1 + - 1 + - 2 + - 3 + - 3 + - 4 + - 4 + - key: value Example ``list_merge=prepend``: .. code-block:: yaml+jinja - --- - - name: Merge recursive by 'name', prepend lists - set_fact: - list3: "{{ [list1, list2]| - community.general.lists_mergeby('name', - recursive=true, - list_merge='prepend') }}" - vars: - list1: - - name: myname01 - param01: - x: default_value - y: default_value - list: - - default_value - - name: myname02 - param01: [1, 1, 2, 3] - - list2: - - name: myname01 - param01: - y: patch_value - z: patch_value - list: - - patch_value - - name: myname02 - param01: [3, 4, 4, {key: value}] - - debug: - var: list3 + list3: "{{ [list1, list2]| + community.general.lists_mergeby('name', + recursive=true, + list_merge='prepend') }}" This produces: .. code-block:: yaml - list3: - - name: myname01 - param01: - list: - - patch_value - - default_value - x: default_value - y: patch_value - z: patch_value - - name: myname02 - param01: - - 3 - - 4 - - 4 - - key: value - - 1 - - 1 - - 2 - - 3 + list3: + - name: myname01 + param01: + list: + - patch_value + - default_value + x: default_value + y: patch_value + z: patch_value + - name: myname02 + param01: + - 3 + - 4 + - 4 + - key: value + - 1 + - 1 + - 2 + - 3 Example ``list_merge=append_rp``: .. code-block:: yaml+jinja - --- - - name: Merge recursive by 'name', append lists 'remove present' - set_fact: - list3: "{{ [list1, list2]| - community.general.lists_mergeby('name', - recursive=true, - list_merge='append_rp') }}" - vars: - list1: - - name: myname01 - param01: - x: default_value - y: default_value - list: - - default_value - - name: myname02 - param01: [1, 1, 2, 3] - - list2: - - name: myname01 - param01: - y: patch_value - z: patch_value - list: - - patch_value - - name: myname02 - param01: [3, 4, 4, {key: value}] - - debug: - var: list3 + list3: "{{ [list1, list2]| + community.general.lists_mergeby('name', + recursive=true, + list_merge='append_rp') }}" This produces: .. code-block:: yaml - list3: - - name: myname01 - param01: - list: - - default_value - - patch_value - x: default_value - y: patch_value - z: patch_value - - name: myname02 - param01: - - 1 - - 1 - - 2 - - 3 - - 4 - - 4 - - key: value + list3: + - name: myname01 + param01: + list: + - default_value + - patch_value + x: default_value + y: patch_value + z: patch_value + - name: myname02 + param01: + - 1 + - 1 + - 2 + - 3 + - 4 + - 4 + - key: value Example ``list_merge=prepend_rp``: .. code-block:: yaml+jinja - --- - - name: Merge recursive by 'name', prepend lists 'remove present' - set_fact: - list3: "{{ [list1, list2]| - community.general.lists_mergeby('name', - recursive=true, - list_merge='prepend_rp') }}" - vars: - list1: - - name: myname01 - param01: - x: default_value - y: default_value - list: - - default_value - - name: myname02 - param01: [1, 1, 2, 3] - - list2: - - name: myname01 - param01: - y: patch_value - z: patch_value - list: - - patch_value - - name: myname02 - param01: [3, 4, 4, {key: value}] - - debug: - var: list3 + list3: "{{ [list1, list2]| + community.general.lists_mergeby('name', + recursive=true, + list_merge='prepend_rp') }}" This produces: .. code-block:: yaml - list3: - - name: myname01 - param01: - list: - - patch_value - - default_value - x: default_value - y: patch_value - z: patch_value - - name: myname02 - param01: - - 3 - - 4 - - 4 - - key: value - - 1 - - 1 - - 2 + list3: + - name: myname01 + param01: + list: + - patch_value + - default_value + x: default_value + y: patch_value + z: patch_value + - name: myname02 + param01: + - 3 + - 4 + - 4 + - key: value + - 1 + - 1 + - 2 +