Add filter documentation (#87)

* Add filter documentation.

* Update no-unwanted-files sanity check.

plugins/filter/join.yml

@@ -0,0 +1,26 @@
+DOCUMENTATION:
+ name: join
+ short_description: Join a list of arguments to a command
+ version_added: 2.0.0
+ description:
+ - Join and quotes a list of arguments to a command.
+ options:
+ _input:
+ description:
+ - A list of arguments to quote and join.
+ type: list
+ elements: string
+ required: true
+ author:
+ - Felix Fontein (@felixfontein)
+
+EXAMPLES: |
+ - name: Join arguments for a RouterOS CLI command
+ ansible.builtin.set_fact:
+ arguments: "{{ ['foo=bar', 'comment=foo is bar'] | community.routeros.join }}"
+ # Should result in 'foo=bar comment="foo is bar"'
+
+RETURN:
+ _value:
+ description: The joined and quoted result.
+ type: string

plugins/filter/list_to_dict.yml

@@ -0,0 +1,36 @@
+DOCUMENTATION:
+ name: list_to_dict
+ short_description: Convert a list of arguments to a dictionary
+ version_added: 2.0.0
+ description:
+ - Convert a list of arguments to a dictionary.
+ options:
+ _input:
+ description:
+ - A list of assignments. Can be the result of the C(community.routeros.split) filter.
+ type: list
+ elements: string
+ required: true
+ require_assignment:
+ description:
+ - Allows to accept arguments without values when set to C(false).
+ type: boolean
+ default: true
+ skip_empty_values:
+ description:
+ - Allows to skip arguments whose value is empty when set to C(true).
+ type: boolean
+ default: false
+ author:
+ - Felix Fontein (@felixfontein)
+
+EXAMPLES: |
+ - name: Convert a list to a dictionary
+ ansible.builtin.set_fact:
+ dictionary: "{{ ['foo=bar', 'comment=foo is bar'] | community.routeros.list_to_dict }}"
+ # dictionary == {'foo': 'bar', 'comment': 'foo is bar'}
+
+RETURN:
+ _value:
+ description: A dictionary representation of the input data.
+ type: dictionary

plugins/filter/quote_argument.yml

@@ -0,0 +1,25 @@
+DOCUMENTATION:
+ name: quote_argument
+ short_description: Quote an argument
+ version_added: 2.0.0
+ description:
+ - Quote an argument.
+ options:
+ _input:
+ description:
+ - An argument to quote.
+ type: string
+ required: true
+ author:
+ - Felix Fontein (@felixfontein)
+
+EXAMPLES: |
+ - name: Quote a RouterOS CLI command argument
+ ansible.builtin.set_fact:
+ quoted: "{{ 'comment=this is a "comment"' | community.routeros.quote_argument }}"
+ # Should result in 'comment="this is a \"comment\""'
+
+RETURN:
+ _value:
+ description: The quoted argument.
+ type: string

plugins/filter/quote_argument_value.yml

@@ -0,0 +1,25 @@
+DOCUMENTATION:
+ name: quote_argument_value
+ short_description: Quote an argument value
+ version_added: 2.0.0
+ description:
+ - Quote an argument value.
+ options:
+ _input:
+ description:
+ - An argument value to quote.
+ type: string
+ required: true
+ author:
+ - Felix Fontein (@felixfontein)
+
+EXAMPLES: |
+ - name: Quote a RouterOS CLI command argument's value
+ ansible.builtin.set_fact:
+ quoted: "{{ 'this is a "comment"' | community.routeros.quote_argument_value }}"
+ # Should result in '"this is a \"comment\""'
+
+RETURN:
+ _value:
+ description: The quoted argument value.
+ type: string

plugins/filter/split.yml

@@ -0,0 +1,26 @@
+DOCUMENTATION:
+ name: split
+ short_description: Split a command into arguments
+ version_added: 2.0.0
+ description:
+ - Split a command into arguments.
+ options:
+ _input:
+ description:
+ - A command.
+ type: string
+ required: true
+ author:
+ - Felix Fontein (@felixfontein)
+
+EXAMPLES: |
+ - name: Split command into list of arguments
+ ansible.builtin.set_fact:
+ argument_list: "{{ 'foo=bar comment="foo is bar" baz' | community.routeros.split }}"
+ # Should result in ['foo=bar', 'comment=foo is bar', 'baz']
+
+RETURN:
+ _value:
+ description: The list of arguments.
+ type: list
+ elements: string

tests/sanity/extra/no-unwanted-files.py

@@ -6,6 +6,7 @@
 __metaclass__ = type
 
 import os
+import os.path
 import sys
 
 
@@ -26,15 +27,28 @@ def main():
  skip_directories = (
  )
 
+ yaml_directories = (
+ 'plugins/test/',
+ 'plugins/filter/',
+ )
+
  for path in paths:
  if path in skip_paths:
  continue
 
  if any(path.startswith(skip_directory) for skip_directory in skip_directories):
  continue
 
+ if os.path.islink(path):
+ print('%s: is a symbolic link' % (path, ))
+ elif not os.path.isfile(path):
+ print('%s: is not a regular file' % (path, ))
+
  ext = os.path.splitext(path)[1]
 
+ if ext in ('.yml', ) and any(path.startswith(yaml_directory) for yaml_directory in yaml_directories):
+ continue
+
  if ext not in allowed_extensions:
  print('%s: extension must be one of: %s' % (path, ', '.join(allowed_extensions)))