diff --git a/docs/docsite/helper/ansible_type/README.md b/docs/docsite/helper/ansible_type/README.md new file mode 100644 index 0000000000..4e6a9e04f1 --- /dev/null +++ b/docs/docsite/helper/ansible_type/README.md @@ -0,0 +1,51 @@ + + +# 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 +``` diff --git a/docs/docsite/helper/ansible_type/ansible_type.rst.sha1 b/docs/docsite/helper/ansible_type/ansible_type.rst.sha1 new file mode 100644 index 0000000000..1195c7ff11 --- /dev/null +++ b/docs/docsite/helper/ansible_type/ansible_type.rst.sha1 @@ -0,0 +1 @@ +6ca4b820eb61d71c2796046550b06ab9b8e444c5 ../../rst/test_guide-ansible_type.rst diff --git a/docs/docsite/helper/ansible_type/ansible_type.rst.sha1.license b/docs/docsite/helper/ansible_type/ansible_type.rst.sha1.license new file mode 100644 index 0000000000..a1390a69ed --- /dev/null +++ b/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 diff --git a/docs/docsite/helper/ansible_type/playbook.yml b/docs/docsite/helper/ansible_type/playbook.yml new file mode 100644 index 0000000000..7cd69992b7 --- /dev/null +++ b/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 diff --git a/docs/docsite/helper/ansible_type/templates/examples.yml.j2 b/docs/docsite/helper/ansible_type/templates/examples.yml.j2 new file mode 100644 index 0000000000..f470d8f9d1 --- /dev/null +++ b/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 %} diff --git a/docs/docsite/helper/ansible_type/templates/tasks.yml.j2 b/docs/docsite/helper/ansible_type/templates/tasks.yml.j2 new file mode 100644 index 0000000000..0a1d477467 --- /dev/null +++ b/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 %} diff --git a/docs/docsite/helper/ansible_type/templates/test_guide-ansible_type.rst.j2 b/docs/docsite/helper/ansible_type/templates/test_guide-ansible_type.rst.j2 new file mode 100644 index 0000000000..b9230d4e54 --- /dev/null +++ b/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 `. + +.. 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 %} diff --git a/docs/docsite/helper/ansible_type/vars/main/tests.yml b/docs/docsite/helper/ansible_type/vars/main/tests.yml new file mode 100644 index 0000000000..4e54b9ee5b --- /dev/null +++ b/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 diff --git a/docs/docsite/helper/reveal_ansible_type/README.md b/docs/docsite/helper/reveal_ansible_type/README.md new file mode 100644 index 0000000000..4e6a9e04f1 --- /dev/null +++ b/docs/docsite/helper/reveal_ansible_type/README.md @@ -0,0 +1,51 @@ + + +# 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 +``` diff --git a/docs/docsite/helper/reveal_ansible_type/playbook.yml b/docs/docsite/helper/reveal_ansible_type/playbook.yml new file mode 100644 index 0000000000..e511cdecfc --- /dev/null +++ b/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 diff --git a/docs/docsite/helper/reveal_ansible_type/reveal_ansible_type.rst.sha1 b/docs/docsite/helper/reveal_ansible_type/reveal_ansible_type.rst.sha1 new file mode 100644 index 0000000000..f98335450d --- /dev/null +++ b/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 diff --git a/docs/docsite/helper/reveal_ansible_type/reveal_ansible_type.rst.sha1.license b/docs/docsite/helper/reveal_ansible_type/reveal_ansible_type.rst.sha1.license new file mode 100644 index 0000000000..a1390a69ed --- /dev/null +++ b/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 diff --git a/docs/docsite/helper/reveal_ansible_type/templates/examples.yml.j2 b/docs/docsite/helper/reveal_ansible_type/templates/examples.yml.j2 new file mode 100644 index 0000000000..2567fac99c --- /dev/null +++ b/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 %} diff --git a/docs/docsite/helper/reveal_ansible_type/templates/filter_guide-abstract_informations-types-reveal_ansible_type.rst.j2 b/docs/docsite/helper/reveal_ansible_type/templates/filter_guide-abstract_informations-types-reveal_ansible_type.rst.j2 new file mode 100644 index 0000000000..0fd67beb0c --- /dev/null +++ b/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 `. + +.. 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 %} diff --git a/docs/docsite/helper/reveal_ansible_type/templates/tasks.yml.j2 b/docs/docsite/helper/reveal_ansible_type/templates/tasks.yml.j2 new file mode 100644 index 0000000000..acf5d72849 --- /dev/null +++ b/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 %} diff --git a/docs/docsite/helper/reveal_ansible_type/vars/main/tests.yml b/docs/docsite/helper/reveal_ansible_type/vars/main/tests.yml new file mode 100644 index 0000000000..e4c4a28d18 --- /dev/null +++ b/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. diff --git a/docs/docsite/rst/filter_guide-abstract_informations-types-reveal_ansible_type.rst b/docs/docsite/rst/filter_guide-abstract_informations-types-reveal_ansible_type.rst new file mode 100644 index 0000000000..968376e5d0 --- /dev/null +++ b/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 `. + +.. 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] diff --git a/docs/docsite/rst/filter_guide-abstract_informations-types.rst b/docs/docsite/rst/filter_guide-abstract_informations-types.rst new file mode 100644 index 0000000000..d5e6151ee8 --- /dev/null +++ b/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 diff --git a/docs/docsite/rst/filter_guide_abstract_informations.rst b/docs/docsite/rst/filter_guide_abstract_informations.rst index 818c09f02c..d7370b85b4 100644 --- a/docs/docsite/rst/filter_guide_abstract_informations.rst +++ b/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 diff --git a/docs/docsite/rst/test_guide-ansible_type.rst b/docs/docsite/rst/test_guide-ansible_type.rst new file mode 100644 index 0000000000..aad276b436 --- /dev/null +++ b/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 `. + +.. 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 diff --git a/docs/docsite/rst/test_guide-feature_tests.rst b/docs/docsite/rst/test_guide-feature_tests.rst new file mode 100644 index 0000000000..336e8b4942 --- /dev/null +++ b/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 ` 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 diff --git a/docs/docsite/rst/test_guide.rst b/docs/docsite/rst/test_guide.rst index 7a261c7552..bc9317c7b9 100644 --- a/docs/docsite/rst/test_guide.rst +++ b/docs/docsite/rst/test_guide.rst @@ -8,26 +8,9 @@ community.general Test (Plugin) Guide ===================================== -The :ref:`community.general collection ` offers currently one test plugin. +The :ref:`community.general collection ` offers test plugins: -.. contents:: Topics +.. toctree:: -Feature Tests -------------- - -The :ansplugin:`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 + test_guide-feature_tests.rst + test_guide-ansible_type.rst