diff --git a/lib/ansible/plugins/filter/difference.yml b/lib/ansible/plugins/filter/difference.yml new file mode 100644 index 00000000000..b3237fb12f8 --- /dev/null +++ b/lib/ansible/plugins/filter/difference.yml @@ -0,0 +1,35 @@ +DOCUMENTATION: + name: difference + author: Brian Coca (@bcoca) + version_added: "1.4" + short_description: the difference of one list from another + description: + - Provide a unique list of all the elements of the first list that do not appear in the second one. + options: + _input: + description: A list + type: list + required: true + _second_list: + description: A list + type: list + required: true + seealso: + - plugin_type: filter + plugin: ansible.builtin.intersect + - plugin_type: filter + plugin: ansible.builtin.symmetric_difference + - plugin_type: filter + plugin: ansible.builtin.union + - plugin_type: filter + plugin: ansible.builtin.unique +EXAMPLES: | + # return the elements of list1 not in list2 + # list1: [1, 2, 5, 1, 3, 4, 10] + # list2: [1, 2, 3, 4, 5, 11, 99] + {{ list1 | difference(list2) }} + # => [10] +RETURN: + _value: + description: A unique list of the elements from the first list that do not appear on the 2nd + type: list diff --git a/lib/ansible/plugins/filter/intersect.yml b/lib/ansible/plugins/filter/intersect.yml new file mode 100644 index 00000000000..4be56d29526 --- /dev/null +++ b/lib/ansible/plugins/filter/intersect.yml @@ -0,0 +1,35 @@ +DOCUMENTATION: + name: intersect + author: Brian Coca (@bcoca) + version_added: "1.4" + short_description: intersection of lists + description: + - Provide a list with the common elements from other lists. + options: + _input: + description: A list + type: list + required: true + _second_list: + description: A list + type: list + required: true + seealso: + - plugin_type: filter + plugin: ansible.builtin.difference + - plugin_type: filter + plugin: ansible.builtin.symmetric_difference + - plugin_type: filter + plugin: ansible.builtin.unique + - plugin_type: filter + plugin: ansible.builtin.union +EXAMPLES: | + # return only the common elements of list1 and list2 + # list1: [1, 2, 5, 3, 4, 10] + # list2: [1, 2, 3, 4, 5, 11, 99] + {{ list1 | intersect(list2) }} + # => [1, 2, 5, 3, 4] +RETURN: + _value: + description: A list with unique elements common to both lists, also known as a set + type: list diff --git a/lib/ansible/plugins/filter/symmetric_difference.yml b/lib/ansible/plugins/filter/symmetric_difference.yml new file mode 100644 index 00000000000..27541f6b5a8 --- /dev/null +++ b/lib/ansible/plugins/filter/symmetric_difference.yml @@ -0,0 +1,35 @@ +DOCUMENTATION: + name: symmetric_difference + author: Brian Coca (@bcoca) + version_added: "1.4" + short_description: different items from 2 lists + description: + - Provide a unique list of all the elements unique to each list. + options: + _input: + description: A list + type: list + required: true + _second_list: + description: A list + type: list + required: true + seealso: + - plugin_type: filter + plugin: ansible.builtin.difference + - plugin_type: filter + plugin: ansible.builtin.intersect + - plugin_type: filter + plugin: ansible.builtin.union + - plugin_type: filter + plugin: ansible.builtin.unique +EXAMPLES: | + # return the elements of list1 not in list2 and the elements in list2 not in list1 + # list1: [1, 2, 5, 1, 3, 4, 10] + # list2: [1, 2, 3, 4, 5, 11, 99] + {{ list1 | symmetric_difference(list2) }} + # => [10, 11, 99] +RETURN: + _value: + description: A unique list of the elements from 2 lists that are unique to each one + type: list diff --git a/lib/ansible/plugins/filter/union.yml b/lib/ansible/plugins/filter/union.yml new file mode 100644 index 00000000000..504a7e5733e --- /dev/null +++ b/lib/ansible/plugins/filter/union.yml @@ -0,0 +1,35 @@ +DOCUMENTATION: + name: union + author: Brian Coca (@bcoca) + version_added: "1.4" + short_description: union of lists + description: + - Provide a unique list of all the elements of 2 lists. + options: + _input: + description: A list + type: list + required: true + _second_list: + description: A list + type: list + required: true + seealso: + - plugin_type: filter + plugin: ansible.builtin.difference + - plugin_type: filter + plugin: ansible.builtin.intersect + - plugin_type: filter + plugin: ansible.builtin.symmetric_difference + - plugin_type: filter + plugin: ansible.builtin.unique +EXAMPLES: | + # return the unique elements of list1 added to list2 + # list1: [1, 2, 5, 1, 3, 4, 10] + # list2: [1, 2, 3, 4, 5, 11, 99] + {{ list1 | union(list2) }} + # => [1, 2, 5, 1, 3, 4, 10, 11, 99] +RETURN: + _value: + description: A unique list of all the elements from both lists + type: list diff --git a/lib/ansible/plugins/filter/unique.yml b/lib/ansible/plugins/filter/unique.yml new file mode 100644 index 00000000000..15ec51f6fa3 --- /dev/null +++ b/lib/ansible/plugins/filter/unique.yml @@ -0,0 +1,30 @@ +DOCUMENTATION: + name: unique + author: Brian Coca (@bcoca) + version_added: "1.4" + short_description: set of unique items of a list + description: + - Creates a list of unique elements (a set) from the provided input list. + options: + _input: + description: A list + type: list + required: true + seealso: + - plugin_type: filter + plugin: ansible.builtin.difference + - plugin_type: filter + plugin: ansible.builtin.intersect + - plugin_type: filter + plugin: ansible.builtin.symmetric_difference + - plugin_type: filter + plugin: ansible.builtin.union +EXAMPLES: | + # return only the unique elements of list1 + # list1: [1, 2, 5, 1, 3, 4, 10] + {{ list1 | unique }} + # => [1, 2, 5, 3, 4, 10] +RETURN: + _value: + description: A list with unique elements, also known as a set + type: list