|
- One or more zero-based indicies of the matching list items
- See wantlist if a list is always required
+ One or more zero-based indices of the matching list items.
+ See wantlist if a list is always required.
|
diff --git a/docs/ansible.utils.index_of_filter.rst b/docs/ansible.utils.index_of_filter.rst
index d9900d7..ea97ebf 100644
--- a/docs/ansible.utils.index_of_filter.rst
+++ b/docs/ansible.utils.index_of_filter.rst
@@ -5,10 +5,10 @@
ansible.utils.index_of
**********************
-**Find the indicies of items in a list matching some criteria**
+**Find the indices of items in a list matching some criteria**
-Version added: 1.0
+Version added: 1.0.0
.. contents::
:local:
@@ -17,9 +17,9 @@ Version added: 1.0
Synopsis
--------
-- This plugin returns the indicies of items matching some criteria in a list
-- When working with a list of dictionaries, the key to evaluate can be specified
-- ``index_of`` is also available as a ``lookup plugin`` for convenience
+- This plugin returns the indices of items matching some criteria in a list.
+- When working with a list of dictionaries, the key to evaluate can be specified.
+- ``index_of`` is also available as a ``lookup plugin`` for convenience.
- Using the parameters below- ``data|ansible.utils.index_of(test, value, key, fail_on_missing, wantlist``)
@@ -52,8 +52,8 @@ Parameters
|
- A list of items to enumerate and test against
- This option represents the value that is passed to filter plugin in pipe format.
+ A list of items to enumerate and test against.
+ This option represents the value that is passed to the filter plugin in pipe format.
For example config_data|ansible.utils.index_of('x'), in this case config_data represents this option.
|
@@ -75,7 +75,7 @@ Parameters
|
- When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries
+ When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries.
|
@@ -92,9 +92,9 @@ Parameters
|
|
- When the data provided is a list of dictionaries, run the test againt this dictionary key
- When using a key, the data must only contain dictionaries
- See fail_on_missing below to determine the behaviour when the key is missing from a dictionary in the data
+ When the data provided is a list of dictionaries, run the test against this dictionary key.
+ When using a key, the data must only contain dictionaries.
+ See fail_on_missing below to determine the behavior when the key is missing from a dictionary in the data.
|
@@ -131,7 +131,7 @@ Parameters
|
|
- The value used to test each list item against
+ The value used to test each list item against.
{'Not required for simple tests (eg': 'true, false, even, odd)'}
May be a string, boolean, number, regular expesion dict etc, depending on the test used
|
@@ -154,8 +154,8 @@ Parameters
|
- When only a single entry in the data is matched, that entries index is returned as an integer
- If set to True, the return value will always be a list, even if only a single entry is matched
+ When only a single entry in the data is matched, the index of that entry is returned as an integer.
+ If set to True, the return value will always be a list, even if only a single entry is matched.
|
diff --git a/docs/ansible.utils.index_of_lookup.rst b/docs/ansible.utils.index_of_lookup.rst
index b9c9e55..b741203 100644
--- a/docs/ansible.utils.index_of_lookup.rst
+++ b/docs/ansible.utils.index_of_lookup.rst
@@ -5,10 +5,10 @@
ansible.utils.index_of
**********************
-**Find the indicies of items in a list matching some criteria**
+**Find the indices of items in a list matching some criteria**
-Version added: 1.0
+Version added: 1.0.0
.. contents::
:local:
@@ -17,10 +17,10 @@ Version added: 1.0
Synopsis
--------
-- This plugin returns the indicies of items matching some criteria in a list
-- When working with a list of dictionaries, the key to evaluate can be specified
-- ``index_of`` is also available as a ``filter plugin`` for convenience
-- Using the parameters below- ``lookup('ansible.utils.index_of', data, test, value, key, fail_on_missing, wantlist``)
+- This plugin returns the indices of items matching some criteria in a list.
+- When working with a list of dictionaries, the key to evaluate can be specified.
+- ``index_of`` is also available as a ``filter plugin`` for convenience.
+- Using the parameters below- ``lookup('ansible.utils.index_of', data, test, value, key, fail_on_missing, wantlist``).
@@ -52,7 +52,7 @@ Parameters
|
- A list of items to enumerate and test against
+ A list of items to enumerate and test against.
|
@@ -73,7 +73,7 @@ Parameters
|
|
- When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries
+ When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries.
|
@@ -90,7 +90,7 @@ Parameters
|
|
- When the data provided is a list of dictionaries, run the test againt this dictionary key When using a key, the data must only contain dictionaries See fail_on_missing below to determine the behaviour when the key is missing from a dictionary in the data
+ When the data provided is a list of dictionaries, run the test against this dictionary key. When using a key, the data must only contain dictionaries. See fail_on_missing below to determine the behaviour when the key is missing from a dictionary in the data.
|
@@ -108,7 +108,7 @@ Parameters
|
|
-
+
|
@@ -125,7 +125,7 @@ Parameters
|
|
- The value used to test each list item against Not required for simple tests (eg: true, false, even, odd) May be a string, boolean, number, regular expesion dict etc, depending on the test used
+ The value used to test each list item against. Not required for simple tests (eg: true, false, even, odd) May be a string, boolean, number, regular expesion dict etc, depending on the test used.
|
@@ -146,7 +146,7 @@ Parameters
|
|
- When only a single entry in the data is matched, that entries index is returned as an integer If set to True, the return value will always be a list, even if only a single entry is matched This can also be accomplised using query or q instead of lookup https://docs.ansible.com/ansible/latest/plugins/lookup.htmlWhen only a single entry in the data is matched, the index of that entry is returned as an integer. If set to True, the return value will always be a list, even if only a single entry is matched. This can also be accomplised using query or q instead of lookup. https://docs.ansible.com/ansible/latest/plugins/lookup.html |
@@ -429,8 +429,8 @@ Common return values are documented `here
|
- One or more zero-based indicies of the matching list items
- See wantlist if a list is always required
+ One or more zero-based indicies of the matching list items.
+ See wantlist if a list is always required.
|
diff --git a/docs/ansible.utils.jsonschema_validate.rst b/docs/ansible.utils.jsonschema_validate.rst
index d55620f..c3ab581 100644
--- a/docs/ansible.utils.jsonschema_validate.rst
+++ b/docs/ansible.utils.jsonschema_validate.rst
@@ -5,7 +5,7 @@
ansible.utils.jsonschema
************************
-**Define configurable options for jsonschema validate sub-plugin (engine).**
+**Define configurable options for jsonschema validate plugin**
Version added: 1.0.0
@@ -17,7 +17,7 @@ Version added: 1.0.0
Synopsis
--------
-- This plugin documentation provides the configurable options when *ansible.utils.jsonschema* is used as a value for ``engine`` option within ``validate`` plugins. Refer individual ``validate`` plugin docs ``engine`` option for more details.
+- This plugin documentation provides the configurable options that can be passed to the validate plugins when *ansible.utils.json* is used as a value for engine option.
@@ -67,7 +67,6 @@ Notes
-----
.. note::
- - This sub-plugin is not a standalone pluign and works only when used with ``validate`` plugins. This plugin will be used when ``engine`` option of ``validate`` plugin is set to *ansible.utils.jsonschema*.
- The value of ``data`` option should be either of type *dict* or *strings* which should be a valid *dict* when read in python.
- The value of ``criteria`` should be *list* of *dict* or *list* of *strings* and each *string* within the *list* entry should be a valid *dict* when read in python.
diff --git a/docs/ansible.utils.to_paths_filter.rst b/docs/ansible.utils.to_paths_filter.rst
index e071222..d573443 100644
--- a/docs/ansible.utils.to_paths_filter.rst
+++ b/docs/ansible.utils.to_paths_filter.rst
@@ -8,7 +8,7 @@ ansible.utils.to_paths
**Flatten a complex object into a dictionary of paths and values**
-Version added: 1.0
+Version added: 1.0.0
.. contents::
:local:
@@ -18,9 +18,9 @@ Version added: 1.0
Synopsis
--------
- Flatten a complex object into a dictionary of paths and values.
-- Paths are dot delimited whenever possible
-- Brakets are used for list indicies and keys that contain special characters
-- ``to_paths`` is also available as a ``lookup plugin`` for convenience
+- Paths are dot delimited whenever possible.
+- Brakets are used for list indices and keys that contain special characters.
+- ``to_paths`` is also available as a ``lookup plugin`` for convenience.
- Using the parameters below- ``var|ansible.utils.to_paths(prepend, wantlist``)
@@ -71,7 +71,7 @@ Parameters
The value of var will be will be used.
- This option represents the value that is passed to filter plugin in pipe format.
+ This option represents the value that is passed to the filter plugin in pipe format.
For example config_data|ansible.utils.to_paths(), in this case config_data represents this option.
|
@@ -129,8 +129,8 @@ Examples
# paths:
# b.c.d[0]: 0
# b.c.d[1]: 1
- # b.c.e[0]: true
- # b.c.e[1]: false
+ # b.c.e[0]: True
+ # b.c.e[1]: False
- name: Use prepend to add the initial variable name
ansible.builtin.set_fact:
@@ -142,8 +142,8 @@ Examples
# paths:
# a.b.c.d[0]: 0
# a.b.c.d[1]: 1
- # a.b.c.e[0]: true
- # a.b.c.e[1]: false
+ # a.b.c.e[0]: True
+ # a.b.c.e[1]: False
#### Using a complex object
diff --git a/docs/ansible.utils.to_paths_lookup.rst b/docs/ansible.utils.to_paths_lookup.rst
index 941ee63..a8ae00f 100644
--- a/docs/ansible.utils.to_paths_lookup.rst
+++ b/docs/ansible.utils.to_paths_lookup.rst
@@ -8,7 +8,7 @@ ansible.utils.to_paths
**Flatten a complex object into a dictionary of paths and values**
-Version added: 1.0
+Version added: 1.0.0
.. contents::
:local:
@@ -18,9 +18,9 @@ Version added: 1.0
Synopsis
--------
- Flatten a complex object into a dictionary of paths and values.
-- Paths are dot delimited whenever possible
-- Brakets are used for list indicies and keys that contain special characters
-- ``to_paths`` is also available as a filter plugin
+- Paths are dot delimited whenever possible.
+- Brackets are used for list indices and keys that contain special characters.
+- ``to_paths`` is also available as a filter plugin.
- Using the parameters below- ``lookup('ansible.utils.to_paths', var, prepend, wantlist``)
@@ -127,8 +127,8 @@ Examples
# paths:
# b.c.d[0]: 0
# b.c.d[1]: 1
- # b.c.e[0]: true
- # b.c.e[1]: false
+ # b.c.e[0]: True
+ # b.c.e[1]: False
- name: Use prepend to add the initial variable name
ansible.builtin.set_fact:
@@ -140,8 +140,8 @@ Examples
# paths:
# a.b.c.d[0]: 0
# a.b.c.d[1]: 1
- # a.b.c.e[0]: true
- # a.b.c.e[1]: false
+ # a.b.c.e[0]: True
+ # a.b.c.e[1]: False
#### Using a complex object
@@ -201,9 +201,9 @@ Common return values are documented `here
|
- A dictionary of key value pairs
- The key is the path
- The value is the value
+ A dictionary of key value pairs.
+ The key is the path.
+ The value is the value.
|
diff --git a/docs/ansible.utils.update_fact_module.rst b/docs/ansible.utils.update_fact_module.rst
index 895e898..5d2cd78 100644
--- a/docs/ansible.utils.update_fact_module.rst
+++ b/docs/ansible.utils.update_fact_module.rst
@@ -19,7 +19,7 @@ Synopsis
--------
- This module allows updating existing variables.
- Variables are updated on a host-by-host basis.
-- Variable are not modified in place, instead they are returned by the module
+- Variables are not modified in place, instead they are returned by the module.
@@ -49,7 +49,7 @@ Parameters
|
- A list of dictionaries, each a desired update to make
+ A list of dictionaries, each a desired update to make.
|
@@ -66,9 +66,9 @@ Parameters
|
|
- The path in a currently set variable to update
- The path can be in dot or bracket notation
- It should be a valid jinja reference
+ The path in a currently set variable to update.
+ The path can be in dot or bracket notation.
+ It should be a valid jinja reference.
|
@@ -85,8 +85,8 @@ Parameters
|
|
- The value to be set at the path
- Can be a simple or complex data structure
+ The value to be set at the path.
+ Can be a simple or complex data structure.
|
@@ -296,7 +296,7 @@ Examples
state: gathered
register: current
- - name: Update the source of sequenmce 10 in the IPv4 ACL named test1
+ - name: Update the source of sequence 10 in the IPv4 ACL named test1
ansible.utils.update_fact:
updates:
- path: current.gathered[{{ afi }}].acls[{{ acl }}].aces[{{ ace }}].source
diff --git a/docs/ansible.utils.validate_filter.rst b/docs/ansible.utils.validate_filter.rst
index bafc772..566d916 100644
--- a/docs/ansible.utils.validate_filter.rst
+++ b/docs/ansible.utils.validate_filter.rst
@@ -50,8 +50,8 @@ Parameters
The criteria used for validation of value that represents data options.
- This option represents the first argument passed in the filter plugin For example config_data|ansible.utils.validate(config_criteria), in this case the value of config_criteria represents this option.
- For the type of criteria that represents this value refer documentation of individual validator plugins.
+ This option represents the first argument passed in the filter plugin. For example config_data|ansible.utils.validate(config_criteria), in this case the value of config_criteria represents this option.
+ For the type of criteria that represents this value refer to the documentation of individual validator plugins.
|
@@ -69,9 +69,9 @@ Parameters
|
|
- A data that will be validated against criteria.
- This option represents the value that is passed to filter plugin in pipe format. For example config_data|ansible.utils.validate(), in this case config_data represents this option.
- For the type of data that represents this value refer documentation of individual validator plugins.
+ Data that will be validated against criteria.
+ This option represents the value that is passed to the filter plugin in pipe format. For example config_data|ansible.utils.validate(), in this case config_data represents this option.
+ For the type of data that represents this value refer to the documentation of individual validator plugins.
|
@@ -90,7 +90,7 @@ Parameters
|
The name of the validator plugin to use.
- This option can be passed in lookup plugin as a key, value pair For example config_data|ansible.utils.validate(config_criteria, engine='ansible.utils.jsonschema'), in this case the value ansible.utils.jsonschema represents the engine to be use for data valdiation. If the value is not provided the default value that is ansible.uitls.jsonschema will be used.
+ This option can be passed in lookup plugin as a key, value pair. For example config_data|ansible.utils.validate(config_criteria, engine='ansible.utils.jsonschema'), in this case the value ansible.utils.jsonschema represents the engine to be use for data valdiation. If the value is not provided the default value that is ansible.uitls.jsonschema will be used.
The value should be in fully qualified collection name format that is <org-name>.<collection-name>.<validator-plugin-name>.
|
@@ -102,8 +102,8 @@ Notes
-----
.. note::
- - For the type of options ``data`` and ``criteria`` refer the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option.
- - For additional plugin configuration options refer the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option.
+ - For the type of options ``data`` and ``criteria`` refer to the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option.
+ - For additional plugin configuration options refer to the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option.
- The plugin configuration option can be either passed as *key=value* pairs within filter plugin or environment variables.
- The precedence of the ``validate`` plugin configurable option is the variable passed within filter plugin as *key=value* pairs followed by the environment variables.
@@ -119,7 +119,7 @@ Examples
data: "{{ lookup('file', './validate/data/show_interfaces_iosxr.json')}}"
criteria: "{{ lookup('file', './validate/criteria/jsonschema/show_interfaces_iosxr.json')}}"
- - name: validate data in json format using jsonschema with by passing plugin configuration variable as key/value pairs
+ - name: validate data in json format using jsonschema by passing plugin configuration variable as key/value pairs
ansible.builtin.set_fact:
data_validilty: "{{ data|ansible.utils.validate(criteria, engine='ansible.utils.jsonschema', draft='draft7') }}"
diff --git a/docs/ansible.utils.validate_lookup.rst b/docs/ansible.utils.validate_lookup.rst
index 4e468a7..ff4293d 100644
--- a/docs/ansible.utils.validate_lookup.rst
+++ b/docs/ansible.utils.validate_lookup.rst
@@ -51,7 +51,7 @@ Parameters
The criteria used for validation of value that represents data options.
This option represents the second argument passed in the lookup plugin For example lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'), in this case the value of config_criteria represents this option.
- For the type of criteria that represents this value refer documentation of individual validate plugins.
+ For the type of criteria that represents this value refer to the documentation of individual validate plugins.
|
@@ -69,9 +69,9 @@ Parameters
|
|
- A data that will be validated against criteria.
- This option represents the value that is passed to lookup plugin as first argument. For example lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'), in this case config_data represents this option.
- For the type of data that represents this value refer documentation of individual validate plugins.
+ Data that will be validated against criteria.
+ This option represents the value that is passed to the lookup plugin as the first argument. For example lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'), in this case config_data represents this option.
+ For the type of data that represents this value refer to the documentation of individual validate plugins.
|
@@ -90,7 +90,7 @@ Parameters
|
The name of the validate plugin to use.
- This option can be passed in lookup plugin as a key, value pair For example lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'), in this case the value ansible.utils.jsonschema represents the engine to be use for data valdiation. If the value is not provided the default value that is ansible.uitls.jsonschema will be used.
+ This option can be passed in lookup plugin as a key, value pair. For example lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'), in this case the value ansible.utils.jsonschema represents the engine to be use for data valdiation. If the value is not provided the default value that is ansible.uitls.jsonschema will be used.
The value should be in fully qualified collection name format that is <org-name>.<collection-name>.<validate-plugin-name>.
|
@@ -102,8 +102,8 @@ Notes
-----
.. note::
- - For the type of options ``data`` and ``criteria`` refer the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option.
- - For additional plugin configuration options refer the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option.
+ - For the type of options ``data`` and ``criteria`` refer to the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option.
+ - For additional plugin configuration options refer to the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option.
- The plugin configuration option can be either passed as *key=value* pairs within lookup plugin or task or environment variables.
- The precedence the ``validate`` plugin configurable option is the variable passed within lookup plugin as *key=value* pairs followed by task variables followed by environment variables.
@@ -154,8 +154,8 @@ Common return values are documented `here
|
- If data is valid returns empty list
- If data is invalid returns list of errors in data
+ If data is valid returns empty list.
+ If data is invalid returns list of errors in data.
|
diff --git a/docs/ansible.utils.validate_module.rst b/docs/ansible.utils.validate_module.rst
index cf9546b..64cdb4b 100644
--- a/docs/ansible.utils.validate_module.rst
+++ b/docs/ansible.utils.validate_module.rst
@@ -46,7 +46,7 @@ Parameters
|
- The criteria used for validation of data. For the type of criteria refer documentation of individual validate plugins.
+ The criteria used for validation of data. For the type of criteria refer to the documentation of individual validate plugins.
|
@@ -62,7 +62,7 @@ Parameters
|
|
- A data that will be validated against criteria. For the type of data refer documentation of individual validate plugins
+ Data that will be validated against criteria. For the type of data refer to the documentation of individual validate plugins.
|
@@ -78,7 +78,7 @@ Parameters
Default:
"ansible.utils.jsonschema"
- The name of the validate plugin to use. The engine value should follow the fully qualified collection name format that is <org-name>.<collection-name>.<validate-plugin-name>.
+ The name of the validate plugin to use. The engine value should follow the fully qualified collection name format, that is <org-name>.<collection-name>.<validate-plugin-name>.
|
@@ -89,10 +89,10 @@ Notes
-----
.. note::
- - For the type of options ``data`` and ``criteria`` refer the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option.
- - For additional plugin configuration options refer the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option.
+ - For the type of options ``data`` and ``criteria`` refer to the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option.
+ - For additional plugin configuration options refer to the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option.
- The plugin configuration option can be either passed as task or environment variables.
- - The precedence the ``validate`` plugin configurable option is task variables followed by the environment variables.
+ - The precedence of the ``validate`` plugin configurable option is task variables followed by the environment variables.
@@ -155,7 +155,7 @@ Common return values are documented `here always
The msg indicates if the data is valid as per the criteria.
- In case data is valid return success message all checks passed
+ In case data is valid return success message all checks passed.
In case data is invalid return error message Validation errors were found along with more information on error is available.
|
diff --git a/plugins/filter/get_path.py b/plugins/filter/get_path.py
index 6fd05a4..d648089 100644
--- a/plugins/filter/get_path.py
+++ b/plugins/filter/get_path.py
@@ -14,29 +14,29 @@ __metaclass__ = type
DOCUMENTATION = """
filter: get_path
author: Bradley Thornton (@cidrblock)
- version_added: "1.0"
+ version_added: "1.0.0"
short_description: Retrieve the value in a variable using a path
description:
- - Use a C(path) to retreive a nested value from a C(var)
- - C(get_path) is also available as a C(lookup plugin) for convenience
+ - Use a C(path) to retrieve a nested value from a C(var).
+ - C(get_path) is also available as a C(lookup plugin) for convenience.
- Using the parameters below- C(var|ansible.utils.get_path(path, wantlist))
options:
var:
description:
- - The variable from which the value should be extraced
- - This option represents the value that is passed to filter plugin in pipe format.
+ - The variable from which the value should be extracted.
+ - This option represents the value that is passed to the filter plugin in pipe format.
- For example I(config_data|ansible.utils.get_path()), in this case I(config_data) represents this option.
type: raw
required: True
path:
description:
- The C(path) in the C(var) to retrieve the value of.
- - The C(path) needs to a be a valid jinja path
+ - The C(path) needs to be a valid jinja path.
type: str
required: True
wantlist:
description:
- - If set to C(True), the return value will always be a list
+ - If set to C(True), the return value will always be a list.
type: bool
notes:
@@ -104,8 +104,8 @@ EXAMPLES = r"""
# paths:
# a.b.c.d[0]: 0
# a.b.c.d[1]: 1
-# a.b.c.e[0]: true
-# a.b.c.e[1]: false
+# a.b.c.e[0]: True
+# a.b.c.e[1]: False
# TASK [Retrieve the value of each path from vars] ******************
# ok: [nxos101] => (item=a.b.c.d[0]) =>
diff --git a/plugins/filter/index_of.py b/plugins/filter/index_of.py
index b8bc93b..b5d4c5a 100644
--- a/plugins/filter/index_of.py
+++ b/plugins/filter/index_of.py
@@ -14,18 +14,18 @@ __metaclass__ = type
DOCUMENTATION = """
filter: index_of
author: Bradley Thornton (@cidrblock)
- version_added: "1.0"
- short_description: Find the indicies of items in a list matching some criteria
+ version_added: "1.0.0"
+ short_description: Find the indices of items in a list matching some criteria
description:
- - This plugin returns the indicies of items matching some criteria in a list
- - When working with a list of dictionaries, the key to evaluate can be specified
- - C(index_of) is also available as a C(lookup plugin) for convenience
+ - This plugin returns the indices of items matching some criteria in a list.
+ - When working with a list of dictionaries, the key to evaluate can be specified.
+ - C(index_of) is also available as a C(lookup plugin) for convenience.
- Using the parameters below- C(data|ansible.utils.index_of(test, value, key, fail_on_missing, wantlist))
options:
data:
description:
- - A list of items to enumerate and test against
- - This option represents the value that is passed to filter plugin in pipe format.
+ - A list of items to enumerate and test against.
+ - This option represents the value that is passed to the filter plugin in pipe format.
- For example I(config_data|ansible.utils.index_of('x')), in this case I(config_data) represents this option.
type: list
required: True
@@ -38,23 +38,23 @@ DOCUMENTATION = """
required: True
value:
description:
- - The value used to test each list item against
+ - The value used to test each list item against.
- Not required for simple tests (eg: C(true), C(false), C(even), C(odd))
- May be a C(string), C(boolean), C(number), C(regular expesion) C(dict) etc, depending on the C(test) used
type: raw
key:
description:
- - When the data provided is a list of dictionaries, run the test againt this dictionary key
- - When using a C(key), the C(data) must only contain dictionaries
- - See C(fail_on_missing) below to determine the behaviour when the C(key) is missing from a dictionary in the C(data)
+ - When the data provided is a list of dictionaries, run the test against this dictionary key.
+ - When using a C(key), the C(data) must only contain dictionaries.
+ - See C(fail_on_missing) below to determine the behavior when the C(key) is missing from a dictionary in the C(data).
type: str
fail_on_missing:
- description: When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries
+ description: When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries.
type: bool
wantlist:
description:
- - When only a single entry in the C(data) is matched, that entries index is returned as an integer
- - If set to C(True), the return value will always be a list, even if only a single entry is matched
+ - When only a single entry in the C(data) is matched, the index of that entry is returned as an integer.
+ - If set to C(True), the return value will always be a list, even if only a single entry is matched.
type: bool
notes:
diff --git a/plugins/filter/to_paths.py b/plugins/filter/to_paths.py
index 06cd667..7829b48 100644
--- a/plugins/filter/to_paths.py
+++ b/plugins/filter/to_paths.py
@@ -15,19 +15,19 @@ __metaclass__ = type
DOCUMENTATION = """
filter: to_paths
author: Bradley Thornton (@cidrblock)
- version_added: "1.0"
+ version_added: "1.0.0"
short_description: Flatten a complex object into a dictionary of paths and values
description:
- Flatten a complex object into a dictionary of paths and values.
- - Paths are dot delimited whenever possible
- - Brakets are used for list indicies and keys that contain special characters
- - C(to_paths) is also available as a C(lookup plugin) for convenience
+ - Paths are dot delimited whenever possible.
+ - Brakets are used for list indices and keys that contain special characters.
+ - C(to_paths) is also available as a C(lookup plugin) for convenience.
- Using the parameters below- C(var|ansible.utils.to_paths(prepend, wantlist))
options:
var:
description:
- The value of C(var) will be will be used.
- - This option represents the value that is passed to filter plugin in pipe format.
+ - This option represents the value that is passed to the filter plugin in pipe format.
- For example I(config_data|ansible.utils.to_paths()), in this case I(config_data) represents this option.
type: raw
required: True
@@ -67,8 +67,8 @@ EXAMPLES = r"""
# paths:
# b.c.d[0]: 0
# b.c.d[1]: 1
-# b.c.e[0]: true
-# b.c.e[1]: false
+# b.c.e[0]: True
+# b.c.e[1]: False
- name: Use prepend to add the initial variable name
ansible.builtin.set_fact:
@@ -80,8 +80,8 @@ EXAMPLES = r"""
# paths:
# a.b.c.d[0]: 0
# a.b.c.d[1]: 1
-# a.b.c.e[0]: true
-# a.b.c.e[1]: false
+# a.b.c.e[0]: True
+# a.b.c.e[1]: False
#### Using a complex object
diff --git a/plugins/filter/validate.py b/plugins/filter/validate.py
index 1974d96..e919cf5 100644
--- a/plugins/filter/validate.py
+++ b/plugins/filter/validate.py
@@ -13,26 +13,26 @@ DOCUMENTATION = """
data:
type: raw
description:
- - A data that will be validated against C(criteria).
- - This option represents the value that is passed to filter plugin in pipe format.
+ - Data that will be validated against C(criteria).
+ - This option represents the value that is passed to the filter plugin in pipe format.
For example I(config_data|ansible.utils.validate()), in this case I(config_data)
represents this option.
- - For the type of C(data) that represents this value refer documentation of individual validator plugins.
+ - For the type of C(data) that represents this value refer to the documentation of individual validator plugins.
required: True
criteria:
type: raw
description:
- The criteria used for validation of value that represents C(data) options.
- - This option represents the first argument passed in the filter plugin
+ - This option represents the first argument passed in the filter plugin.
For example I(config_data|ansible.utils.validate(config_criteria)), in
this case the value of I(config_criteria) represents this option.
- - For the type of C(criteria) that represents this value refer documentation of individual validator plugins.
+ - For the type of C(criteria) that represents this value refer to the documentation of individual validator plugins.
required: True
engine:
type: str
description:
- The name of the validator plugin to use.
- - This option can be passed in lookup plugin as a key, value pair
+ - This option can be passed in lookup plugin as a key, value pair.
For example I(config_data|ansible.utils.validate(config_criteria, engine='ansible.utils.jsonschema')), in
this case the value I(ansible.utils.jsonschema) represents the engine to be use for data valdiation.
If the value is not provided the default value that is I(ansible.uitls.jsonschema) will be used.
@@ -40,9 +40,9 @@ DOCUMENTATION = """
I(..).
default: ansible.utils.jsonschema
notes:
- - For the type of options C(data) and C(criteria) refer the individual C(validate) plugin
+ - For the type of options C(data) and C(criteria) refer to the individual C(validate) plugin
documentation that is represented in the value of C(engine) option.
- - For additional plugin configuration options refer the individual C(validate) plugin
+ - For additional plugin configuration options refer to the individual C(validate) plugin
documentation that is represented by the value of C(engine) option.
- The plugin configuration option can be either passed as I(key=value) pairs within filter plugin
or environment variables.
@@ -56,7 +56,7 @@ EXAMPLES = r"""
data: "{{ lookup('file', './validate/data/show_interfaces_iosxr.json')}}"
criteria: "{{ lookup('file', './validate/criteria/jsonschema/show_interfaces_iosxr.json')}}"
-- name: validate data in json format using jsonschema with by passing plugin configuration variable as key/value pairs
+- name: validate data in json format using jsonschema by passing plugin configuration variable as key/value pairs
ansible.builtin.set_fact:
data_validilty: "{{ data|ansible.utils.validate(criteria, engine='ansible.utils.jsonschema', draft='draft7') }}"
"""
diff --git a/plugins/lookup/get_path.py b/plugins/lookup/get_path.py
index 0f6ba91..0536df9 100644
--- a/plugins/lookup/get_path.py
+++ b/plugins/lookup/get_path.py
@@ -15,28 +15,28 @@ __metaclass__ = type
DOCUMENTATION = """
lookup: get_path
author: Bradley Thornton (@cidrblock)
- version_added: "1.0"
+ version_added: "1.0.0"
short_description: Retrieve the value in a variable using a path
description:
- - Use a C(path) to retreive a nested value from a C(var)
+ - Use a C(path) to retrieve a nested value from a C(var)
- C(get_path) is also available as a C(filter plugin) for convenience
- Using the parameters below- C(lookup('ansible.utils.get_path', var, path, wantlist))
options:
var:
- description: The variable from which the value should be extraced
+ description: The variable from which the value should be extracted.
type: raw
required: True
path:
description: >
The C(path) in the C(var) to retrieve the value of.
- The C(path) needs to a be a valid jinja path
+ The C(path) needs to a be a valid jinja path.
type: str
required: True
wantlist:
description: >
- If set to C(True), the return value will always be a list
- This can also be accomplished using C(query) or C(q) instead of C(lookup)
- U(https://docs.ansible.com/ansible/latest/plugins/lookup.html)
+ If set to C(True), the return value will always be a list.
+ This can also be accomplished using C(query) or C(q) instead of C(lookup).
+ U(https://docs.ansible.com/ansible/latest/plugins/lookup.html).
type: bool
notes:
@@ -104,8 +104,8 @@ EXAMPLES = r"""
# paths:
# a.b.c.d[0]: 0
# a.b.c.d[1]: 1
-# a.b.c.e[0]: true
-# a.b.c.e[1]: false
+# a.b.c.e[0]: True
+# a.b.c.e[1]: False
# TASK [Retrieve the value of each path from vars] ******************
# ok: [nxos101] => (item=a.b.c.d[0]) =>
@@ -150,8 +150,8 @@ EXAMPLES = r"""
RETURN = """
_raw:
description:
- - One or more zero-based indicies of the matching list items
- - See C(wantlist) if a list is always required
+ - One or more zero-based indices of the matching list items.
+ - See C(wantlist) if a list is always required.
"""
from ansible.errors import AnsibleLookupError
diff --git a/plugins/lookup/index_of.py b/plugins/lookup/index_of.py
index c4bb4a7..a344f50 100644
--- a/plugins/lookup/index_of.py
+++ b/plugins/lookup/index_of.py
@@ -15,45 +15,45 @@ __metaclass__ = type
DOCUMENTATION = """
lookup: index_of
author: Bradley Thornton (@cidrblock)
- version_added: "1.0"
- short_description: Find the indicies of items in a list matching some criteria
+ version_added: "1.0.0"
+ short_description: Find the indices of items in a list matching some criteria
description:
- - This plugin returns the indicies of items matching some criteria in a list
- - When working with a list of dictionaries, the key to evaluate can be specified
- - C(index_of) is also available as a C(filter plugin) for convenience
- - Using the parameters below- C(lookup('ansible.utils.index_of', data, test, value, key, fail_on_missing, wantlist))
+ - This plugin returns the indices of items matching some criteria in a list.
+ - When working with a list of dictionaries, the key to evaluate can be specified.
+ - C(index_of) is also available as a C(filter plugin) for convenience.
+ - Using the parameters below- C(lookup('ansible.utils.index_of', data, test, value, key, fail_on_missing, wantlist)).
options:
data:
- description: A list of items to enumerate and test against
+ description: A list of items to enumerate and test against.
type: list
required: True
test:
description: >
The name of the test to run against the list, a valid jinja2 test or ansible test plugin.
Jinja2 includes the following tests U(http://jinja.palletsprojects.com/templates/#builtin-tests).
- An overview of tests included in ansible U(https://docs.ansible.com/ansible/latest/user_guide/playbooks_tests.html)
+ An overview of tests included in ansible U(https://docs.ansible.com/ansible/latest/user_guide/playbooks_tests.html).
type: str
required: True
value:
description: >
- The value used to test each list item against
+ The value used to test each list item against.
Not required for simple tests (eg: C(true), C(false), C(even), C(odd))
- May be a C(string), C(boolean), C(number), C(regular expesion) C(dict) etc, depending on the C(test) used
+ May be a C(string), C(boolean), C(number), C(regular expesion) C(dict) etc, depending on the C(test) used.
type: raw
key:
description: >
- When the data provided is a list of dictionaries, run the test againt this dictionary key
- When using a C(key), the C(data) must only contain dictionaries
- See C(fail_on_missing) below to determine the behaviour when the C(key) is missing from a dictionary in the C(data)
+ When the data provided is a list of dictionaries, run the test against this dictionary key.
+ When using a C(key), the C(data) must only contain dictionaries.
+ See C(fail_on_missing) below to determine the behaviour when the C(key) is missing from a dictionary in the C(data).
type: str
fail_on_missing:
- description: When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries
+ description: When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries.
type: bool
wantlist:
description: >
- When only a single entry in the C(data) is matched, that entries index is returned as an integer
- If set to C(True), the return value will always be a list, even if only a single entry is matched
- This can also be accomplised using C(query) or C(q) instead of C(lookup)
+ When only a single entry in the C(data) is matched, the index of that entry is returned as an integer.
+ If set to C(True), the return value will always be a list, even if only a single entry is matched.
+ This can also be accomplised using C(query) or C(q) instead of C(lookup).
U(https://docs.ansible.com/ansible/latest/plugins/lookup.html)
type: bool
@@ -310,8 +310,8 @@ EXAMPLES = r"""
RETURN = """
_raw:
description:
- - One or more zero-based indicies of the matching list items
- - See C(wantlist) if a list is always required
+ - One or more zero-based indicies of the matching list items.
+ - See C(wantlist) if a list is always required.
"""
from ansible.errors import AnsibleLookupError
diff --git a/plugins/lookup/to_paths.py b/plugins/lookup/to_paths.py
index ad791ea..33dbcd7 100644
--- a/plugins/lookup/to_paths.py
+++ b/plugins/lookup/to_paths.py
@@ -15,13 +15,13 @@ __metaclass__ = type
DOCUMENTATION = """
lookup: to_paths
author: Bradley Thornton (@cidrblock)
- version_added: "1.0"
+ version_added: "1.0.0"
short_description: Flatten a complex object into a dictionary of paths and values
description:
- Flatten a complex object into a dictionary of paths and values.
- - Paths are dot delimited whenever possible
- - Brakets are used for list indicies and keys that contain special characters
- - C(to_paths) is also available as a filter plugin
+ - Paths are dot delimited whenever possible.
+ - Brackets are used for list indices and keys that contain special characters.
+ - C(to_paths) is also available as a filter plugin.
- Using the parameters below- C(lookup('ansible.utils.to_paths', var, prepend, wantlist))
options:
var:
@@ -66,8 +66,8 @@ EXAMPLES = r"""
# paths:
# b.c.d[0]: 0
# b.c.d[1]: 1
-# b.c.e[0]: true
-# b.c.e[1]: false
+# b.c.e[0]: True
+# b.c.e[1]: False
- name: Use prepend to add the initial variable name
ansible.builtin.set_fact:
@@ -79,8 +79,8 @@ EXAMPLES = r"""
# paths:
# a.b.c.d[0]: 0
# a.b.c.d[1]: 1
-# a.b.c.e[0]: true
-# a.b.c.e[1]: false
+# a.b.c.e[0]: True
+# a.b.c.e[1]: False
#### Using a complex object
@@ -120,9 +120,9 @@ EXAMPLES = r"""
RETURN = """
_raw:
description:
- - A dictionary of key value pairs
- - The key is the path
- - The value is the value
+ - A dictionary of key value pairs.
+ - The key is the path.
+ - The value is the value.
"""
from ansible.errors import AnsibleLookupError
diff --git a/plugins/lookup/validate.py b/plugins/lookup/validate.py
index f60948a..1347553 100644
--- a/plugins/lookup/validate.py
+++ b/plugins/lookup/validate.py
@@ -18,11 +18,11 @@ DOCUMENTATION = """
data:
type: raw
description:
- - A data that will be validated against C(criteria).
- - This option represents the value that is passed to lookup plugin as first argument.
+ - Data that will be validated against C(criteria).
+ - This option represents the value that is passed to the lookup plugin as the first argument.
For example I(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')),
in this case I(config_data) represents this option.
- - For the type of C(data) that represents this value refer documentation of individual validate plugins.
+ - For the type of C(data) that represents this value refer to the documentation of individual validate plugins.
required: True
criteria:
type: raw
@@ -31,14 +31,14 @@ DOCUMENTATION = """
- This option represents the second argument passed in the lookup plugin
For example I(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')),
in this case the value of I(config_criteria) represents this option.
- - For the type of C(criteria) that represents this value refer documentation of individual
+ - For the type of C(criteria) that represents this value refer to the documentation of individual
validate plugins.
required: True
engine:
type: str
description:
- The name of the validate plugin to use.
- - This option can be passed in lookup plugin as a key, value pair
+ - This option can be passed in lookup plugin as a key, value pair.
For example I(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')), in
this case the value I(ansible.utils.jsonschema) represents the engine to be use for data valdiation.
If the value is not provided the default value that is I(ansible.uitls.jsonschema) will be used.
@@ -46,9 +46,9 @@ DOCUMENTATION = """
I(..).
default: ansible.utils.jsonschema
notes:
- - For the type of options C(data) and C(criteria) refer the individual C(validate) plugin
+ - For the type of options C(data) and C(criteria) refer to the individual C(validate) plugin
documentation that is represented in the value of C(engine) option.
- - For additional plugin configuration options refer the individual C(validate) plugin
+ - For additional plugin configuration options refer to the individual C(validate) plugin
documentation that is represented by the value of C(engine) option.
- The plugin configuration option can be either passed as I(key=value) pairs within lookup plugin
or task or environment variables.
@@ -76,8 +76,8 @@ EXAMPLES = r"""
RETURN = """
_raw:
description:
- - If data is valid returns empty list
- - If data is invalid returns list of errors in data
+ - If data is valid returns empty list.
+ - If data is invalid returns list of errors in data.
"""
from ansible.errors import AnsibleError, AnsibleLookupError
diff --git a/plugins/modules/fact_diff.py b/plugins/modules/fact_diff.py
index 0817d8e..b810772 100644
--- a/plugins/modules/fact_diff.py
+++ b/plugins/modules/fact_diff.py
@@ -15,16 +15,16 @@ module: fact_diff
short_description: Find the difference between currently set facts
version_added: "1.0.0"
description:
- - Compare two facts or variables and get a diff
+ - Compare two facts or variables and get a diff.
options:
before:
description:
- - The first fact to be used in the comparison
+ - The first fact to be used in the comparison.
type: raw
required: True
after:
description:
- - The second fact to be used in the comparison
+ - The second fact to be used in the comparison.
type: raw
required: True
plugin:
@@ -35,20 +35,20 @@ options:
suboptions:
name:
description:
- - The diff plugin to use, in collection format
+ - The diff plugin to use, in fully qualified collection name format.
default: ansible.utils.native
type: str
vars:
description:
- - Parameters passed to the diff plugin
+ - Parameters passed to the diff plugin.
type: dict
default: {}
suboptions:
skip_lines:
description:
- - Skip lines matching these regular expressions
- - Matches will be removed prior to the diff
- - If the provided I(before) and I(after) are a string, they will be split
+ - Skip lines matching these regular expressions.
+ - Matches will be removed prior to the diff.
+ - If the provided I(before) and I(after) are a string, they will be split.
- Each entry in each list will be cast to a string for the comparison
type: list
@@ -194,11 +194,11 @@ EXAMPLES = r"""
RETURN = """
diff_text:
- description: The diff in text format
+ description: The diff in text format.
returned: always
type: str
diff_lines:
- description: The C(diff_text) split into lines
+ description: The C(diff_text) split into lines.
returned: always
type: list
diff --git a/plugins/modules/update_fact.py b/plugins/modules/update_fact.py
index 7f4f491..fd1214e 100644
--- a/plugins/modules/update_fact.py
+++ b/plugins/modules/update_fact.py
@@ -17,26 +17,26 @@ version_added: "1.0.0"
description:
- This module allows updating existing variables.
- Variables are updated on a host-by-host basis.
- - Variable are not modified in place, instead they are returned by the module
+ - Variables are not modified in place, instead they are returned by the module.
options:
updates:
description:
- - A list of dictionaries, each a desired update to make
+ - A list of dictionaries, each a desired update to make.
type: list
elements: dict
required: True
suboptions:
path:
description:
- - The path in a currently set variable to update
- - The path can be in dot or bracket notation
- - It should be a valid jinja reference
+ - The path in a currently set variable to update.
+ - The path can be in dot or bracket notation.
+ - It should be a valid jinja reference.
type: str
required: True
value:
description:
- - The value to be set at the path
- - Can be a simple or complex data structure
+ - The value to be set at the path.
+ - Can be a simple or complex data structure.
type: raw
required: True
@@ -244,7 +244,7 @@ EXAMPLES = r"""
state: gathered
register: current
-- name: Update the source of sequenmce 10 in the IPv4 ACL named test1
+- name: Update the source of sequence 10 in the IPv4 ACL named test1
ansible.utils.update_fact:
updates:
- path: current.gathered[{{ afi }}].acls[{{ acl }}].aces[{{ ace }}].source
diff --git a/plugins/modules/validate.py b/plugins/modules/validate.py
index f3e1fc7..8c676f4 100644
--- a/plugins/modules/validate.py
+++ b/plugins/modules/validate.py
@@ -22,29 +22,29 @@ options:
data:
type: raw
description:
- - A data that will be validated against C(criteria). For the type of data refer
- documentation of individual validate plugins
+ - Data that will be validated against C(criteria). For the type of data refer to the
+ documentation of individual validate plugins.
required: True
engine:
type: str
description:
- - The name of the validate plugin to use. The engine value should follow
- the fully qualified collection name format that is
+ - The name of the validate plugin to use. The engine value should follow
+ the fully qualified collection name format, that is
...
default: ansible.utils.jsonschema
criteria:
type: raw
description:
- - The criteria used for validation of C(data). For the type of criteria refer
+ - The criteria used for validation of C(data). For the type of criteria refer to the
documentation of individual validate plugins.
required: True
notes:
-- For the type of options C(data) and C(criteria) refer the individual C(validate) plugin
+- For the type of options C(data) and C(criteria) refer to the individual C(validate) plugin
documentation that is represented in the value of C(engine) option.
-- For additional plugin configuration options refer the individual C(validate) plugin
+- For additional plugin configuration options refer to the individual C(validate) plugin
documentation that is represented by the value of C(engine) option.
- The plugin configuration option can be either passed as task or environment variables.
-- The precedence the C(validate) plugin configurable option is task variables followed
+- The precedence of the C(validate) plugin configurable option is task variables followed
by the environment variables.
"""
@@ -67,7 +67,7 @@ RETURN = r"""
msg:
description:
- The msg indicates if the C(data) is valid as per the C(criteria).
- - In case data is valid return success message I(all checks passed)
+ - In case data is valid return success message I(all checks passed).
- In case data is invalid return error message I(Validation errors were found)
along with more information on error is available.
returned: always