Add docs for the filter reveal_ansible_type and the test ansible_type.

.github/BOTMETA.yml

@@ -1460,6 +1460,10 @@ files:
     maintainers: vbotka
   docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst:
     maintainers: vbotka
+  docs/docsite/rst/filter_guide-abstract_informations-types.rst:
+    maintainers: vbotka
+  docs/docsite/rst/filter_guide-abstract_informations-types-reveal_ansible_type.rst:
+    maintainers: vbotka
   docs/docsite/rst/filter_guide_conversions.rst:
     maintainers: Ajpantuso kellyjonbrazil
   docs/docsite/rst/filter_guide_creating_identifiers.rst:
@@ -1487,7 +1491,7 @@ files:
   docs/docsite/rst/guide_vardict.rst:
     maintainers: russoz
   docs/docsite/rst/test_guide.rst:
-    maintainers: felixfontein
+    maintainers: felixfontein vbotka
 #########################
   tests/:
     labels: tests

docs/docsite/rst/filter_guide-abstract_informations-types-reveal_ansible_type.rst

@@ -0,0 +1,144 @@
+..
+  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
+
+Filter reveal_ansible_type
+""""""""""""""""""""""""""
+
+Use the filter :ansplugin:`community.general.reveal_ansible_type#filter` if you want to get the type of Ansible data.
+
+.. 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>`.
+
+.. versionadded:: 9.2.0
+
+**Substitution converts str to AnsibleUnicode**
+
+* String. AnsibleUnicode.
+
+.. code-block:: yaml+jinja
+
+   data: "abc"
+   result: '{{ data | community.general.reveal_ansible_type }}'
+   # result => AnsibleUnicode
+
+* String. AnsibleUnicode alias str.
+
+.. code-block:: yaml+jinja
+
+   alias: {"AnsibleUnicode": "str"}
+   data: "abc"
+   result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+   # result => str
+
+* List. All items are AnsibleUnicode.
+
+.. code-block:: yaml+jinja
+
+   data: ["a", "b", "c"]
+   result: '{{ data | community.general.reveal_ansible_type }}'
+   # result => list[AnsibleUnicode]
+
+* Dictionary. All keys are AnsibleUnicode. All values are AnsibleUnicode.
+
+.. code-block:: yaml+jinja
+
+   data: {"a": "foo", "b": "bar", "c": "baz"}
+   result: '{{ data | community.general.reveal_ansible_type }}'
+   # result => dict[AnsibleUnicode, AnsibleUnicode]
+
+**No substitution and no alias. Type of strings is str**
+
+* String
+
+.. code-block:: yaml+jinja
+
+   result: '{{ "abc" | community.general.reveal_ansible_type }}'
+   # result => str
+
+* Integer
+
+.. code-block:: yaml+jinja
+
+   result: '{{ 123 | community.general.reveal_ansible_type }}'
+   # result => int
+
+* Float
+
+.. code-block:: yaml+jinja
+
+   result: '{{ 123.45 | community.general.reveal_ansible_type }}'
+   # result => float
+
+* Boolean
+
+.. code-block:: yaml+jinja
+
+   result: '{{ true | community.general.reveal_ansible_type }}'
+   # result => bool
+
+* List. All items are strings.
+
+.. code-block:: yaml+jinja
+
+   result: '{{ ["a", "b", "c"] | community.general.reveal_ansible_type }}'
+   # result => list[str]
+
+* List of dictionaries.
+
+.. code-block:: yaml+jinja
+
+   result: '{{ [{"a": 1}, {"b": 2}] | community.general.reveal_ansible_type }}'
+   # result => list[dict]
+
+* Dictionary. All keys are strings. All values are integers.
+
+.. code-block:: yaml+jinja
+
+   result: '{{ {"a": 1} | community.general.reveal_ansible_type }}'
+   # result => dict[str, int]
+
+* Dictionary. All keys are strings. All values are integers.
+
+.. code-block:: yaml+jinja
+
+   result: '{{ {"a": 1, "b": 2} | community.general.reveal_ansible_type }}'
+   # result => dict[str, int]
+
+**Type of strings is AnsibleUnicode or str**
+
+* Dictionary. The keys are integers or strings. All values are strings.
+
+.. code-block:: yaml+jinja
+
+   alias: {"AnsibleUnicode": "str"}
+   data: {1: 'a', 'b': 'b'}
+   result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+   # result => dict[int|str, str]
+
+* Dictionary. All keys are integers. All values are keys.
+
+.. code-block:: yaml+jinja
+
+   alias: {"AnsibleUnicode": "str"}
+   data: {1: 'a', 2: 'b'}
+   result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+   # result => dict[int, str]
+
+* Dictionary. All keys are strings. Multiple types values.
+
+.. code-block:: yaml+jinja
+
+   alias: {"AnsibleUnicode": "str"}
+   data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': True, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}}
+   result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+   # result => dict[str, bool|dict|float|int|list|str]
+
+* List. Multiple types items.
+
+.. code-block:: yaml+jinja
+
+   alias: {"AnsibleUnicode": "str"}
+   data: [1, 2, 1.1, 'abc', True, ['x', 'y', 'z'], {'x': 1, 'y': 2}]
+   result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+   # result => list[bool|dict|float|int|list|str]

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

@@ -0,0 +1,14 @@
+..
+  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
+
+Types
+^^^^^
+
+Filters to manage Ansible types
+
+.. toctree::
+   :maxdepth: 1
+
+   filter_guide-abstract_informations-types-reveal_ansible_type

docs/docsite/rst/filter_guide_abstract_informations.rst

@@ -15,3 +15,4 @@ Abstract transformations
    filter_guide_abstract_informations_merging_lists_of_dictionaries
    filter_guide_abstract_informations_lists_helper
    filter_guide_abstract_informations_counting_elements_in_sequence
+   filter_guide-abstract_informations-types

docs/docsite/rst/test_guide.rst

@@ -31,3 +31,210 @@ The :ansplugin:`community.general.a_module test <community.general.a_module#test
           - "'community.general.does_not_exist' is not community.general.a_module"
 
 .. versionadded:: 4.0.0
+
+Test ansible_type
+-----------------
+
+Use the test :ansplugin:`community.general.ansible_type#test` if you want to test the type of Ansible data.
+
+.. 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>`.
+
+.. versionadded:: 9.2.0
+
+**Substitution converts str to AnsibleUnicode**
+
+* String. AnsibleUnicode.
+
+.. code-block:: yaml+jinja
+
+   dtype AnsibleUnicode
+   data: "abc"
+   result: '{{ data is community.general.ansible_type(dtype) }}'
+   # result => true
+
+* String. AnsibleUnicode alias str.
+
+.. code-block:: yaml+jinja
+
+   alias: {"AnsibleUnicode": "str"}
+   dtype str
+   data: "abc"
+   result: '{{ data is community.general.ansible_type(dtype, alias) }}'
+   # result => true
+
+* List. All items are AnsibleUnicode.
+
+.. code-block:: yaml+jinja
+
+   dtype list[AnsibleUnicode]
+   data: ["a", "b", "c"]
+   result: '{{ data is community.general.ansible_type(dtype) }}'
+   # result => true
+
+* Dictionary. All keys are AnsibleUnicode. All values are AnsibleUnicode.
+
+.. code-block:: yaml+jinja
+
+   dtype dict[AnsibleUnicode, AnsibleUnicode]
+   data: {"a": "foo", "b": "bar", "c": "baz"}
+   result: '{{ data is community.general.ansible_type(dtype) }}'
+   # result => true
+
+**No substitution and no alias. Type of strings is str**
+
+* String
+
+.. code-block:: yaml+jinja
+
+   dtype: str
+   result: '{{ "abc" is community.general.ansible_type }}'
+   result => true
+
+* Integer
+
+.. code-block:: yaml+jinja
+
+   dtype: int
+   result: '{{ 123 is community.general.ansible_type }}'
+   result => true
+
+* Float
+
+.. code-block:: yaml+jinja
+
+   dtype: float
+   result: '{{ 123.45 is community.general.ansible_type }}'
+   result => true
+
+* Boolean
+
+.. code-block:: yaml+jinja
+
+   dtype: bool
+   result: '{{ true is community.general.ansible_type }}'
+   result => true
+
+* List. All items are strings.
+
+.. code-block:: yaml+jinja
+
+   dtype: list[str]
+   result: '{{ ["a", "b", "c"] is community.general.ansible_type }}'
+   result => true
+
+* List of dictionaries.
+
+.. code-block:: yaml+jinja
+
+   dtype: list[dict]
+   result: '{{ [{"a": 1}, {"b": 2}] is community.general.ansible_type }}'
+   result => true
+
+* Dictionary. All keys are strings. All values are integers.
+
+.. code-block:: yaml+jinja
+
+   dtype: dict[str, int]
+   result: '{{ {"a": 1} is community.general.ansible_type }}'
+   result => true
+
+* Dictionary. All keys are strings. All values are integers.
+
+.. code-block:: yaml+jinja
+
+   dtype: dict[str, int]
+   result: '{{ {"a": 1, "b": 2} is community.general.ansible_type }}'
+   result => true
+
+**Type of strings is AnsibleUnicode or str**
+
+* Dictionary. The keys are integers or strings. All values are strings.
+
+.. code-block:: yaml+jinja
+
+   alias: {"AnsibleUnicode": "str"}
+   dtype: dict[int|str, str]
+   data: {1: 'a', 'b': 'b'}
+   result: '{{ data is community.general.ansible_type(dtype, alias) }}'
+   # result => true
+
+* Dictionary. All keys are integers. All values are keys.
+
+.. code-block:: yaml+jinja
+
+   alias: {"AnsibleUnicode": "str"}
+   dtype: dict[int, str]
+   data: {1: 'a', 2: 'b'}
+   result: '{{ data is community.general.ansible_type(dtype, alias) }}'
+   # result => true
+
+* Dictionary. All keys are strings. Multiple types values.
+
+.. code-block:: yaml+jinja
+
+   alias: {"AnsibleUnicode": "str"}
+   dtype: dict[str, bool|dict|float|int|list|str]
+   data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': True, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}}
+   result: '{{ data is community.general.ansible_type(dtype, alias) }}'
+   # result => true
+
+* List. Multiple types items.
+
+.. code-block:: yaml+jinja
+
+   alias: {"AnsibleUnicode": "str"}
+   dtype: list[bool|dict|float|int|list|str]
+   data: [1, 2, 1.1, 'abc', True, ['x', 'y', 'z'], {'x': 1, 'y': 2}]
+   result: '{{ data is community.general.ansible_type(dtype, alias) }}'
+   # result => true
+
+**Option dtype is list**
+
+* AnsibleUnicode or str
+
+.. code-block:: yaml+jinja
+
+   dtype: ['AnsibleUnicode', 'str']
+   data: abc
+   result: '{{ data is community.general.ansible_type(dtype) }}'
+   # result => true
+
+* float or int
+
+.. code-block:: yaml+jinja
+
+   dtype: ['float', 'int']
+   data: 123
+   result: '{{ data is community.general.ansible_type(dtype) }}'
+   # result => true
+
+* float or int
+
+.. code-block:: yaml+jinja
+
+   dtype: ['float', 'int']
+   data: 123.45
+   result: '{{ data is community.general.ansible_type(dtype) }}'
+   # result => true
+
+**Multiple alias**
+
+* int alias number
+
+.. code-block:: yaml+jinja
+
+   alias: {"int": "number", "float": "number"}
+   dtype: number
+   data: 123
+   result: '{{ data is community.general.ansible_type(dtype, alias) }}'
+   # result => true
+
+* float alias number
+
+.. code-block:: yaml+jinja
+
+   alias: {"int": "number", "float": "number"}
+   dtype: number
+   data: 123.45
+   result: '{{ data is community.general.ansible_type(dtype, alias) }}'
+   # result => true