ansible-collections.communi.../docs/docsite/rst/quoting.rst

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

.. _ansible_collections.community.routeros.docsite.quoting:

How to quote and unquote commands and arguments
===============================================

When using the :ansplugin:`community.routeros.command module <community.routeros.command#module>` or the :ansplugin:`community.routeros.api module <community.routeros.api#module>` modules, you need to pass text data in quoted form. While in some cases quoting is not needed (when passing IP addresses or names without spaces, for example), in other cases it is required, like when passing a comment which contains a space.

The community.routeros collection provides a set of Jinja2 filter plugins which helps you with these tasks:

- The :ansplugin:`community.routeros.quote_argument_value filter <community.routeros.quote_argument_value#filter>` quotes an argument value: ``'this is a "comment"' | community.routeros.quote_argument_value == '"this is a \\"comment\\""'``.
- The :ansplugin:`community.routeros.quote_argument filter <community.routeros.quote_argument#filter>` quotes an argument with or without a value: ``'comment=this is a "comment"' | community.routeros.quote_argument == 'comment="this is a \\"comment\\""'``.
- The :ansplugin:`community.routeros.join filter <community.routeros.join#filter>` quotes a list of arguments and joins them to one string: ``['foo=bar', 'comment=foo is bar'] | community.routeros.join == 'foo=bar comment="foo is bar"'``.
- The :ansplugin:`community.routeros.split filter <community.routeros.split#filter>` splits a command into a list of arguments (with or without values): ``'foo=bar comment="foo is bar"' | community.routeros.split == ['foo=bar', 'comment=foo is bar']``
- The :ansplugin:`community.routeros.list_to_dict filter <community.routeros.list_to_dict#filter>` splits a list of arguments with values into a dictionary: ``['foo=bar', 'comment=foo is bar'] | community.routeros.list_to_dict == {'foo': 'bar', 'comment': 'foo is bar'}``. It has two optional arguments: :ansopt:`community.routeros.list_to_dict#filter:require_assignment` (default value :ansval:`true`) allows to accept arguments without values when set to :ansval:`false`; and :ansopt:`community.routeros.list_to_dict#filter:skip_empty_values` (default value :ansval:`false`) allows to skip arguments whose value is empty.
Move licenses to LICENSES/, use SPDX-License-Identifier, mention all licenses in galaxy.yml, add missing license file (#101) * Add SPDX license identifiers, mention all licenses in galaxy.yml. * Add default copyright headers. * Adjust remaining/missing entries. * Fix/add more copyright statements. * Add sanity test. * Add changelog. * Add missing license file. * Remove colon after 'Copyright'. * Avoid colon after 'Copyright' in lint script. 2022-07-18 23:16:54 +02:00			`..`
			`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`

Add module_utils and filters for quoting and unquoting (#53) * Move splitting code to own file. * Move list to dictionary code to quoting as well. * Add quoting functionality. * Add quoting filters. * Add integration tests to CI. * Fix bugs, increase coverage. * Make parsing more strict. * Extract function parse_argument_value from split_routeros_command to make proper parsing of WHERE possible. * Adjust expected error message in integration tests. * Simplify code and improve coverage. * Add changelog fragment for WHERE strictness in api module. * Add documenation. * Fix typo. * Add documentation references. * Add example to api module which uses quote_argument_value. * Fix bug, and add tests which prevent this in the future. * Add more escape sequence tests. * Make sure all control characters are quoted. 2021-10-11 23:44:40 +02:00			`.. _ansible_collections.community.routeros.docsite.quoting:`

			`How to quote and unquote commands and arguments`
			`===============================================`

Fix typos, improve markup (#231) * Fix typos. * Improve markup. 2023-10-29 08:28:00 +01:00			When using the :ansplugin:`community.routeros.command module <community.routeros.command#module>` or the :ansplugin:`community.routeros.api module <community.routeros.api#module>` modules, you need to pass text data in quoted form. While in some cases quoting is not needed (when passing IP addresses or names without spaces, for example), in other cases it is required, like when passing a comment which contains a space.
Add module_utils and filters for quoting and unquoting (#53) * Move splitting code to own file. * Move list to dictionary code to quoting as well. * Add quoting functionality. * Add quoting filters. * Add integration tests to CI. * Fix bugs, increase coverage. * Make parsing more strict. * Extract function parse_argument_value from split_routeros_command to make proper parsing of WHERE possible. * Adjust expected error message in integration tests. * Simplify code and improve coverage. * Add changelog fragment for WHERE strictness in api module. * Add documenation. * Fix typo. * Add documentation references. * Add example to api module which uses quote_argument_value. * Fix bug, and add tests which prevent this in the future. * Add more escape sequence tests. * Make sure all control characters are quoted. 2021-10-11 23:44:40 +02:00
			`The community.routeros collection provides a set of Jinja2 filter plugins which helps you with these tasks:`

Fix typos, improve markup (#231) * Fix typos. * Improve markup. 2023-10-29 08:28:00 +01:00			- The :ansplugin:`community.routeros.quote_argument_value filter <community.routeros.quote_argument_value#filter>` quotes an argument value: ``'this is a "comment"' \| community.routeros.quote_argument_value == '"this is a \\"comment\\""'``.
			- The :ansplugin:`community.routeros.quote_argument filter <community.routeros.quote_argument#filter>` quotes an argument with or without a value: ``'comment=this is a "comment"' \| community.routeros.quote_argument == 'comment="this is a \\"comment\\""'``.
			- The :ansplugin:`community.routeros.join filter <community.routeros.join#filter>` quotes a list of arguments and joins them to one string: ``['foo=bar', 'comment=foo is bar'] \| community.routeros.join == 'foo=bar comment="foo is bar"'``.
			- The :ansplugin:`community.routeros.split filter <community.routeros.split#filter>` splits a command into a list of arguments (with or without values): ``'foo=bar comment="foo is bar"' \| community.routeros.split == ['foo=bar', 'comment=foo is bar']``
			- The :ansplugin:`community.routeros.list_to_dict filter <community.routeros.list_to_dict#filter>` splits a list of arguments with values into a dictionary: ``['foo=bar', 'comment=foo is bar'] \| community.routeros.list_to_dict == {'foo': 'bar', 'comment': 'foo is bar'}``. It has two optional arguments: :ansopt:`community.routeros.list_to_dict#filter:require_assignment` (default value :ansval:`true`) allows to accept arguments without values when set to :ansval:`false`; and :ansopt:`community.routeros.list_to_dict#filter:skip_empty_values` (default value :ansval:`false`) allows to skip arguments whose value is empty.