Add docs for the filter reveal_ansible_type and the test ansible_type.

docs/docsite/helper/ansible_type/README.md

@@ -0,0 +1,51 @@
+<!--
+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,
+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 command
+
+```sh
+shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
+```
+
+## Playbook explained
+
+The playbook includes the variable *tests* and creates the RST file
+from the template. The playbook will terminate if the RST file was
+changed manually. Review the changes and update the template and
+variable *tests* if needed. Update the checksum to pass the integrity
+test. The playbook message provides you with the command. Make sure
+that the updated template nd vars create identical RST file. Only then
+apply your changes.
+
+## Optionally create integration test tasks and plugin examples
+
+```sh
+shell> ansible-playbook playbook.yml -e enable_tasks=true
+shell> ansible-playbook playbook.yml -e enable_examples=true
+```

docs/docsite/helper/ansible_type/ansible_type.rst.sha1

@@ -0,0 +1 @@
+6ca4b820eb61d71c2796046550b06ab9b8e444c5  ../../rst/test_guide-ansible_type.rst

docs/docsite/helper/ansible_type/ansible_type.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/ansible_type/playbook.yml

@@ -0,0 +1,74 @@
+---
+# 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. Optionally create integration tasks and
+# plugin examples.
+#
+# 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/ansible_type/playbook.yml
+
+- name: Create RST file for docs/docsite/rst
+  hosts: localhost
+  gather_facts: false
+
+  vars:
+
+    plugin: ansible_type
+    docs_path:
+      - test_guide
+
+    file_base: "{{ (docs_path + [plugin]) | join('-') }}"
+    file_rst: ../../rst/{{ file_base }}.rst
+    file_sha1: "{{ plugin }}.rst.sha1"
+
+    start: "{{ '{{' }}"
+    stop: "{{ '}}' }}"
+
+  tasks:
+
+    - 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: vars/main/tests.yml
+
+    - name: Create RST file
+      ansible.builtin.template:
+        src: "{{ file_base }}.rst.j2"
+        dest: "{{ file_base }}.rst"
+      when: enable_rst | d(true) | bool
+
+    - name: Create plugin examples
+      ansible.builtin.template:
+        src: examples.yml.j2
+        dest: examples.yml
+      when: enable_examples | d(false) | bool
+
+    - name: Create integration tasks
+      ansible.builtin.template:
+        src: tasks.yml.j2
+        dest: tasks.yml
+      when: enable_tasks | d(false) | bool

docs/docsite/helper/ansible_type/templates/examples.yml.j2

@@ -0,0 +1,67 @@
+# 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
+
+# Substitution converts str to AnsibleUnicode
+# -------------------------------------------
+{% for i in (0, 1, 2, 3) %}
+
+# {{ tests[i].d }}
+{% if tests[i].alias is defined %}
+alias: {{ tests[i].alias | to_json }}
+dtype: {{ tests[i].r }}
+data: {{ tests[i].i | to_json }}
+result: '{{ start }} data is community.general.ansible_type(dtype, alias) {{ stop }}'
+# result => true
+{% else %}
+dtype: {{ tests[i].r }}
+data: {{ tests[i].i | to_json }}
+result: '{{ start }} data is community.general.ansible_type(dtype) {{ stop }}'
+# result => true
+{% endif %}
+{% endfor %}
+
+# No substitution and no alias. Type of strings is str
+# ----------------------------------------------------
+{% for test in tests.4.group %}
+
+# {{ test.d }}
+dtype: {{ test.r }}
+result: '{{ start }} {{ test.i | to_json }} is community.general.ansible_type(dtype) {{ stop }}'
+# result => true
+{% endfor %}
+
+# Type of strings is AnsibleUnicode or str
+# ----------------------------------------
+{% for test in tests.5.group %}
+
+# {{ test.d }}
+alias: {{ tests.5.alias | to_json }}
+dtype: {{ test.r }}
+data: {{ test.i }}
+result: '{{ start }} data is community.general.ansible_type(dtype, alias) {{ stop }}'
+# result => true
+{% endfor %}
+
+# Option dtype is list
+# --------------------
+{% for test in tests.6.group %}
+
+# {{ test.d }}
+dtype: {{ test.r }}
+data: {{ test.i }}
+result: '{{ start }} data is community.general.ansible_type(dtype) {{ stop }}'
+# result => true
+{% endfor %}
+
+# Multiple alias
+# --------------
+{% for test in tests.7.group %}
+
+# {{ test.d }}
+alias: {{ tests.7.alias | to_json }}
+dtype: {{ test.r }}
+data: {{ test.i }}
+result: '{{ start }} data is community.general.ansible_type(dtype, alias) {{ stop }}'
+# result => true
+{% endfor %}

docs/docsite/helper/ansible_type/templates/tasks.yml.j2

@@ -0,0 +1,96 @@
+# 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
+
+# Substitution converts str to AnsibleUnicode
+# -------------------------------------------
+{% for i in (0, 1, 2, 3) %}
+
+- name: {{ tests[i].d }}
+  assert:
+{% if tests[i].alias is defined %}
+    that: data is community.general.ansible_type(dtype, alias)
+    success_msg: '{{ tests[i].i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg: '{{ tests[i].i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    alias: {{ tests[i].alias | to_json }}
+    data: {{ tests[i].i | to_json }}
+    result: '{{ start }} data | community.general.reveal_ansible_type(alias) {{ stop }}'
+    dtype: '{{ tests[i].r }}'
+{% else %}
+    that: data is community.general.ansible_type(dtype)
+    success_msg: '{{ tests[i].i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg: '{{ tests[i].i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    data: {{ tests[i].i | to_json }}
+    result: '{{ start }} data | community.general.reveal_ansible_type {{ stop }}'
+    dtype: '{{ tests[i].r }}'
+{% endif %}
+{% endfor %}
+
+# No substitution and no alias. Type of strings is str
+# ----------------------------------------------------
+{% for test in tests.4.group %}
+
+- name: {{ test.d }}
+  assert:
+    that: '{{ test.i | to_json }} is community.general.ansible_type(dtype)'
+    success_msg: '{{ test.i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg:  '{{ test.i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    result: '{{ start }} {{ test.i | to_json }} | community.general.reveal_ansible_type {{ stop }}'
+    dtype: {{ test.r }}
+{% endfor %}
+
+# Type of strings is AnsibleUnicode or str
+# ----------------------------------------
+{% for test in tests.5.group %}
+
+- name: {{ test.d }}
+  assert:
+    that: data is community.general.ansible_type(dtype, alias)
+    success_msg: '{{ test.i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg: '{{ test.i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    alias: {{ tests.5.alias | to_json }}
+    data: {{ test.i }}
+    result: '{{ start }} data | community.general.reveal_ansible_type(alias) {{ stop }}'
+    dtype: {{ test.r }}
+{% endfor %}
+
+# Option dtype is list
+# --------------------
+{% for test in tests.6.group %}
+
+- name: {{ test.d }}
+  assert:
+    that: data is community.general.ansible_type(dtype)
+    success_msg: '{{ test.i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg: '{{ test.i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    data: {{ test.i }}
+    result: '{{ start }} data | community.general.reveal_ansible_type {{ stop }}'
+    dtype: {{ test.r }}
+{% endfor %}
+
+# Multiple alias
+# --------------
+{% for test in tests.7.group %}
+
+- name: {{ test.d }}
+  assert:
+    that: data is community.general.ansible_type(dtype, alias)
+    success_msg: '{{ test.i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg: '{{ test.i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    alias: {{ tests.7.alias | to_json }}
+    data: {{ test.i }}
+    result: '{{ start }} data | community.general.reveal_ansible_type(alias) {{ stop }}'
+    dtype: {{ test.r }}
+{% endfor %}

docs/docsite/helper/ansible_type/templates/test_guide-ansible_type.rst.j2

@@ -0,0 +1,86 @@
+..
+  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
+
+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**
+{% for i in (0, 1, 2, 3) %}
+
+* {{ tests[i].d }}
+
+.. code-block:: yaml+jinja
+
+{% if tests[i].alias is defined %}
+   alias: {{ tests[i].alias | to_json }}
+   dtype: {{ tests[i].r }}
+   data: {{ tests[i].i | to_json }}
+   result: '{{ start }} data is community.general.ansible_type(dtype, alias) {{ stop }}'
+{% else %}
+   dtype: {{ tests[i].r }}
+   data: {{ tests[i].i | to_json }}
+   result: '{{ start }} data is community.general.ansible_type(dtype) {{ stop }}'
+{% endif %}
+   # result => true
+{% endfor %}
+
+**No substitution and no alias. Type of strings is str**
+{% for test in tests.4.group %}
+
+* {{ test.d }}
+
+.. code-block:: yaml+jinja
+
+   dtype: {{ test.r }}
+   result: '{{ start }} {{ test.i | to_json }} is community.general.ansible_type {{ stop }}'
+   result => true
+{% endfor %}
+
+**Type of strings is AnsibleUnicode or str**
+{% for test in tests.5.group %}
+
+* {{ test.d }}
+
+.. code-block:: yaml+jinja
+
+   alias: {{ tests.5.alias | to_json }}
+   dtype: {{ test.r }}
+   data: {{ test.i }}
+   result: '{{ start }} data is community.general.ansible_type(dtype, alias) {{ stop }}'
+   # result => true
+{% endfor %}
+
+**Option dtype is list**
+{% for test in tests.6.group %}
+
+* {{ test.d }}
+
+.. code-block:: yaml+jinja
+
+   dtype: {{ test.r }}
+   data: {{ test.i }}
+   result: '{{ start }} data is community.general.ansible_type(dtype) {{ stop }}'
+   # result => true
+{% endfor %}
+
+**Multiple alias**
+{% for test in tests.7.group %}
+
+* {{ test.d }}
+
+.. code-block:: yaml+jinja
+
+   alias: {{ tests.7.alias | to_json }}
+   dtype: {{ test.r }}
+   data: {{ test.i }}
+   result: '{{ start }} data is community.general.ansible_type(dtype, alias) {{ stop }}'
+   # result => true
+{% endfor %}

docs/docsite/helper/ansible_type/vars/main/tests.yml

@@ -0,0 +1,105 @@
+---
+# 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
+
+# Note: Expansion in a loop will convert all AnsibleUnicode types to str.
+
+tests:
+  - name: 0.Test AnsibleUnicode.
+    i: abc
+    r: AnsibleUnicode
+    d: String. AnsibleUnicode.
+  - name: 1.Test AnsibleUnicode alias str.
+    alias:
+      AnsibleUnicode: str
+    i: abc
+    r: str
+    d: String. AnsibleUnicode alias str.
+  - name: 2.Test list[AnsibleUnicode].
+    i: [a, b, c]
+    r: list[AnsibleUnicode]
+    d: List. All items are AnsibleUnicode.
+  - name: 3.Test dict[AnsibleUnicode, AnsibleUnicode].
+    i: {a: foo, b: bar, c: baz}
+    r: dict[AnsibleUnicode, AnsibleUnicode]
+    d: Dictionary. All keys are AnsibleUnicode. All values are AnsibleUnicode.
+  - name: 4.Test no substitution and no alias. Type of strings is str.
+    alias: {}
+    group:
+      - i: abc
+        r: str
+        d: String
+      - i: 123
+        r: int
+        d: Integer
+      - i: 123.45
+        r: float
+        d: Float
+      - i: True
+        r: bool
+        d: Boolean
+      - i: [a, b, c]
+        r: list[str]
+        d: List. All items are strings.
+      - i: [{a: 1}, {b: 2}]
+        r: list[dict]
+        d: List of dictionaries.
+      - i: {a: 1}
+        r: dict[str, int]
+        d: Dictionary. All keys are strings. All values are integers.
+      - i: {a: 1, b: 2}
+        r: dict[str, int]
+        d: Dictionary. All keys are strings. All values are integers.
+  - name: 5.Test no substitution and no alias. Type of strings is str.
+    alias:
+      AnsibleUnicode: str
+    group:
+      - i: {1: a, b: b}
+        r: dict[int|str, str]
+        d: Dictionary. The keys are integers or strings. All values are strings.
+      - i: {1: a, 2: b}
+        r: dict[int, str]
+        d: Dictionary. All keys are integers. All values are keys.
+      - i:
+          a: 1
+          b: 1.1
+          c: abc
+          d: true
+          e: [x, y, z]
+          f: {x: 1, y: 2}
+        r: dict[str, bool|dict|float|int|list|str]
+        d: Dictionary. All keys are strings. Multiple types values.
+      - i:
+          - 1
+          - 2
+          - 1.1
+          - abc
+          - true
+          - [x, y, z]
+          - {x: 1, y: 2}
+        r: list[bool|dict|float|int|list|str]
+        d: List. Multiple types items.
+  - name: 6.Test dtype list.
+    alias: {}
+    group:
+      - i: abc
+        r: [AnsibleUnicode, str]
+        d: AnsibleUnicode or str
+      - i: 123
+        r: [float, int]
+        d: float or int
+      - i: 123.45
+        r: [float, int]
+        d: float or int
+  - name: 7.Multiple alias.
+    alias:
+      int: number
+      float: number
+    group:
+      - i: 123
+        r: number
+        d: int alias number
+      - i: 123.45
+        r: number
+        d: float alias number

docs/docsite/helper/reveal_ansible_type/README.md

@@ -0,0 +1,51 @@
+<!--
+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,
+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 command
+
+```sh
+shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
+```
+
+## Playbook explained
+
+The playbook includes the variable *tests* and creates the RST file
+from the template. The playbook will terminate if the RST file was
+changed manually. Review the changes and update the template and
+variable *tests* if needed. Update the checksum to pass the integrity
+test. The playbook message provides you with the command. Make sure
+that the updated template nd vars create identical RST file. Only then
+apply your changes.
+
+## Optionally create integration test tasks and plugin examples
+
+```sh
+shell> ansible-playbook playbook.yml -e enable_tasks=true
+shell> ansible-playbook playbook.yml -e enable_examples=true
+```

docs/docsite/helper/reveal_ansible_type/playbook.yml

@@ -0,0 +1,76 @@
+---
+# 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. Optionally create integration tasks and
+# plugin examples.
+#
+# 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/reveal_ansible_type/playbook.yml
+
+- name: Create RST file for docs/docsite/rst
+  hosts: localhost
+  gather_facts: false
+
+  vars:
+
+    plugin: reveal_ansible_type
+    docs_path:
+      - filter_guide
+      - abstract_informations
+      - types
+
+    file_base: "{{ (docs_path + [plugin]) | join('-') }}"
+    file_rst: ../../rst/{{ file_base }}.rst
+    file_sha1: "{{ plugin }}.rst.sha1"
+
+    start: "{{ '{{' }}"
+    stop: "{{ '}}' }}"
+
+  tasks:
+
+    - 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: vars/main/tests.yml
+
+    - name: Create RST file
+      ansible.builtin.template:
+        src: "{{ file_base }}.rst.j2"
+        dest: "{{ file_base }}.rst"
+      when: enable_rst | d(true) | bool
+
+    - name: Create plugin examples
+      ansible.builtin.template:
+        src: examples.yml.j2
+        dest: examples.yml
+      when: enable_examples | d(false) | bool
+
+    - name: Create integration tasks
+      ansible.builtin.template:
+        src: tasks.yml.j2
+        dest: tasks.yml
+      when: enable_tasks | d(false) | bool

docs/docsite/helper/reveal_ansible_type/reveal_ansible_type.rst.sha1

@@ -0,0 +1 @@
+845a993148d2f66035cd5d89adf616020f66b3f8  ../../rst/filter_guide-abstract_informations-types-reveal_ansible_type.rst

docs/docsite/helper/reveal_ansible_type/reveal_ansible_type.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/reveal_ansible_type/templates/examples.yml.j2

@@ -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
+
+# Substitution converts str to AnsibleUnicode
+# -------------------------------------------
+{% for i in (0, 1, 2, 3) %}
+
+# {{ tests[i].d }}
+{% if tests[i].alias is defined %}
+alias: {{ tests[i].alias | to_json }}
+data: {{ tests[i].i | to_json }}
+result: '{{ start }} data | community.general.reveal_ansible_type(alias) {{ stop }}'
+# result => {{ tests[i].r }}
+{% else %}
+data: {{ tests[i].i | to_json }}
+result: '{{ start }} data | community.general.reveal_ansible_type {{ stop }}'
+# result => {{ tests[i].r }}
+{% endif %}
+{% endfor %}
+
+# No substitution and no alias. Type of strings is str
+# ----------------------------------------------------
+{% for test in tests.4.group %}
+
+# {{ test.d }}
+result: '{{ start }} {{ test.i | to_json }} | community.general.reveal_ansible_type {{ stop }}'
+# result => {{ test.r }}
+{% endfor %}
+
+# Type of strings is AnsibleUnicode or str
+# ----------------------------------------
+{% for test in tests.5.group %}
+
+# {{ test.d }}
+alias: {{ tests.5.alias | to_json }}
+data: {{ test.i }}
+result: '{{ start }} data | community.general.reveal_ansible_type(alias) {{ stop }}'
+# result => {{ test.r }}
+{% endfor %}

docs/docsite/helper/reveal_ansible_type/templates/filter_guide-abstract_informations-types-reveal_ansible_type.rst.j2

@@ -0,0 +1,55 @@
+..
+  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**
+{% for i in (0, 1, 2, 3) %}
+
+* {{ tests[i].d }}
+
+.. code-block:: yaml+jinja
+
+{% if tests[i].alias is defined %}
+   alias: {{ tests[i].alias | to_json }}
+   data: {{ tests[i].i | to_json }}
+   result: '{{ start }} data | community.general.reveal_ansible_type(alias) {{ stop }}'
+{% else %}
+   data: {{ tests[i].i | to_json }}
+   result: '{{ start }} data | community.general.reveal_ansible_type {{ stop }}'
+{% endif %}
+   # result => {{ tests[i].r }}
+{% endfor %}
+
+**No substitution and no alias. Type of strings is str**
+{% for test in tests.4.group %}
+
+* {{ test.d }}
+
+.. code-block:: yaml+jinja
+
+   result: '{{ start }} {{ test.i | to_json }} | community.general.reveal_ansible_type {{ stop }}'
+   # result => {{ test.r }}
+{% endfor %}
+
+**Type of strings is AnsibleUnicode or str**
+{% for test in tests.5.group %}
+
+* {{ test.d }}
+
+.. code-block:: yaml+jinja
+
+   alias: {{ tests.5.alias | to_json }}
+   data: {{ test.i }}
+   result: '{{ start }} data | community.general.reveal_ansible_type(alias) {{ stop }}'
+   # result => {{ test.r }}
+{% endfor %}

docs/docsite/helper/reveal_ansible_type/templates/tasks.yml.j2

@@ -0,0 +1,63 @@
+# 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
+
+# Substitution converts str to AnsibleUnicode
+# -------------------------------------------
+{% for i in (0, 1, 2, 3) %}
+
+- name: {{ tests[i].d }}
+  assert:
+{% if tests[i].alias is defined %}
+    that: result == dtype
+    success_msg: '{{ tests[i].i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg: '{{ tests[i].i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    alias: {{ tests[i].alias | to_json }}
+    data: {{ tests[i].i | to_json }}
+    result: '{{ start }} data | community.general.reveal_ansible_type(alias) {{ stop }}'
+    dtype: '{{ tests[i].r }}'
+{% else %}
+    that: result == dtype
+    success_msg: '{{ tests[i].i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg: '{{ tests[i].i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    data: {{ tests[i].i | to_json }}
+    result: '{{ start }} data | community.general.reveal_ansible_type {{ stop }}'
+    dtype: '{{ tests[i].r }}'
+{% endif %}
+{% endfor %}
+
+# No substitution and no alias. Type of strings is str
+# ----------------------------------------------------
+{% for test in tests.4.group %}
+
+- name: {{ test.d }}
+  assert:
+    that: result == dtype
+    success_msg: '{{ test.i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg:  '{{ test.i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    result: '{{ start }} {{ test.i | to_json }} | community.general.reveal_ansible_type {{ stop }}'
+    dtype: {{ test.r }}
+{% endfor %}
+
+# Type of strings is AnsibleUnicode or str
+# ----------------------------------------
+{% for test in tests.5.group %}
+
+- name: {{ test.d }}
+  assert:
+    that: result == dtype
+    success_msg: 'data is {{ start }} dtype {{ stop }}'
+    fail_msg: 'data is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    alias: {{ tests.5.alias | to_json }}
+    data: {{ test.i }}
+    result: '{{ start }} data | community.general.reveal_ansible_type(alias) {{ stop }}'
+    dtype: {{ test.r }}
+{% endfor %}

docs/docsite/helper/reveal_ansible_type/vars/main/tests.yml

@@ -0,0 +1,82 @@
+---
+# 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
+
+# Note: Expansion in a loop will convert all AnsibleUnicode types to str.
+
+tests:
+  - name: 0.Test AnsibleUnicode.
+    i: abc
+    r: AnsibleUnicode
+    d: String. AnsibleUnicode.
+  - name: 1.Test AnsibleUnicode alias str.
+    alias:
+      AnsibleUnicode: str
+    i: abc
+    r: str
+    d: String. AnsibleUnicode alias str.
+  - name: 2.Test list[AnsibleUnicode].
+    i: [a, b, c]
+    r: list[AnsibleUnicode]
+    d: List. All items are AnsibleUnicode.
+  - name: 3.Test dict[AnsibleUnicode, AnsibleUnicode].
+    i: {a: foo, b: bar, c: baz}
+    r: dict[AnsibleUnicode, AnsibleUnicode]
+    d: Dictionary. All keys are AnsibleUnicode. All values are AnsibleUnicode.
+  - name: 4.Test no substitution and no alias. Type of strings is str.
+    alias: {}
+    group:
+      - i: abc
+        r: str
+        d: String
+      - i: 123
+        r: int
+        d: Integer
+      - i: 123.45
+        r: float
+        d: Float
+      - i: True
+        r: bool
+        d: Boolean
+      - i: [a, b, c]
+        r: list[str]
+        d: List. All items are strings.
+      - i: [{a: 1}, {b: 2}]
+        r: list[dict]
+        d: List of dictionaries.
+      - i: {a: 1}
+        r: dict[str, int]
+        d: Dictionary. All keys are strings. All values are integers.
+      - i: {a: 1, b: 2}
+        r: dict[str, int]
+        d: Dictionary. All keys are strings. All values are integers.
+  - name: 5.Test no substitution and no alias. Type of strings is str.
+    alias:
+      AnsibleUnicode: str
+    group:
+      - i: {1: a, b: b}
+        r: dict[int|str, str]
+        d: Dictionary. The keys are integers or strings. All values are strings.
+      - i: {1: a, 2: b}
+        r: dict[int, str]
+        d: Dictionary. All keys are integers. All values are keys.
+      - i:
+          a: 1
+          b: 1.1
+          c: abc
+          d: true
+          e: [x, y, z]
+          f: {x: 1, y: 2}
+        r: dict[str, bool|dict|float|int|list|str]
+        d: Dictionary. All keys are strings. Multiple types values.
+      - i:
+          - 1
+          - 2
+          - 1.1
+          - abc
+          - true
+          - [x, y, z]
+          - {x: 1, y: 2}
+        r: list[bool|dict|float|int|list|str]
+        d: List. Multiple types items.

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-ansible_type.rst

@@ -0,0 +1,211 @@
+..
+  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
+
+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

docs/docsite/rst/test_guide-feature_tests.rst

@@ -0,0 +1,24 @@
+..
+  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
+
+Feature Tests
+-------------
+
+The :ansplugin:`community.general.a_module test <community.general.a_module#test>` allows to check whether a given string refers to an existing module or action plugin. This can be useful in roles, which can use this to ensure that required modules are present ahead of time.
+
+.. code-block:: yaml+jinja
+
+    - name: Make sure that community.aws.route53 is available
+      assert:
+        that:
+          - >
+            'community.aws.route53' is community.general.a_module
+
+    - name: Make sure that community.general.does_not_exist is not a module or action plugin
+      assert:
+        that:
+          - "'community.general.does_not_exist' is not community.general.a_module"
+
+.. versionadded:: 4.0.0

docs/docsite/rst/test_guide.rst

@@ -8,26 +8,9 @@
 community.general Test (Plugin) Guide
 =====================================
 
-The :ref:`community.general collection <plugins_in_community.general>` offers currently one test plugin.
+The :ref:`community.general collection <plugins_in_community.general>` offers test plugins:
 
-.. contents:: Topics
+.. toctree::
 
-Feature Tests
+    test_guide-feature_tests.rst
--------------
+    test_guide-ansible_type.rst
-
-The :ansplugin:`community.general.a_module test <community.general.a_module#test>` allows to check whether a given string refers to an existing module or action plugin. This can be useful in roles, which can use this to ensure that required modules are present ahead of time.
-
-.. code-block:: yaml+jinja
-
-    - name: Make sure that community.aws.route53 is available
-      assert:
-        that:
-          - >
-            'community.aws.route53' is community.general.a_module
-
-    - name: Make sure that community.general.does_not_exist is not a module or action plugin
-      assert:
-        that:
-          - "'community.general.does_not_exist' is not community.general.a_module"
-
-.. versionadded:: 4.0.0