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 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 import os
+import os.path
 import sys
 
 
@@ -26,6 +27,11 @@ def main():
     skip_directories = (
     )
 
+    yaml_directories = (
+        'plugins/test/',
+        'plugins/filter/',
+    )
+
     for path in paths:
         if path in skip_paths:
             continue
@@ -33,8 +39,16 @@ def main():
         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)))