Add filter documentation

plugins/doc_fragments/filters.py

@@ -0,0 +1,70 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2022 Felix Fontein
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+
+    DOCUMENTATION = r'''
+options:
+    icann_only:
+        description:
+            - This controls whether only entries from the ICANN section of the Public Suffix List are used,
+              or also entries from the Private section. For example, C(.co.uk) is in the ICANN section,
+              but C(github.io) is in the Private section.
+        type: boolean
+        default: false
+'''
+
+    PUBLIC_SUFFIX = r'''
+options:
+    keep_unknown_suffix:
+        description:
+            - This treats unknown TLDs as valid public suffixes. So for example the public suffix
+              of C(example.tlddoesnotexist) is C(.tlddoesnotexist) if this is C(true). If set to
+              C(false), it will return an empty string in this case.
+            - This option corresponds to whether the global wildcard rule C(*) in the Public
+              Suffix List is used or not.
+        type: boolean
+        default: true
+'''
+
+    REGISTERABLE_DOMAIN = r'''
+options:
+    only_if_registerable:
+        description:
+            - This controls the behavior in case there is no label in front of the public suffix.
+              This is the case if the DNS name itself is a public suffix.
+            - If set to C(false), in this case the public suffix is treated as a registrable domain.
+            - If set to C(true) (default), the registrable domain of a public suffix is interpreted as an
+              empty string.
+        type: boolean
+        default: true
+    keep_unknown_suffix:
+        description:
+            - This treats unknown TLDs as valid public suffixes. So for example the public suffix of
+              C(example.tlddoesnotexist) is C(.tlddoesnotexist) if this is C(true), and hence the
+              registrable domain of C(www.example.tlddoesnotexist) is C(example.tlddoesnotexist).
+              If set to C(false), the registrable domain of C(www.example.tlddoesnotexist) is
+              C(tlddoesnotexist).
+            - This option corresponds to whether the global wildcard rule C(*) in the Public Suffix List
+              is used or not.
+        type: boolean
+        default: true
+'''
+
+    GET = r'''
+options:
+    normalize_result:
+        description:
+            - This controls whether the result is reconstructed from the normalized name used during lookup.
+              During normalization, ulabels are converted to alabels, and every label is converted to lowercase.
+              For example, the ulabel C(ëçãmplê) is converted to C(xn--mpl-llatwb) (puny-code), and
+              C(Example.COM) is converted to C(example.com).
+        type: boolean
+        default: false
+'''

plugins/filter/get_public_suffix.yml

@@ -0,0 +1,34 @@
+DOCUMENTATION:
+  name: get_public_suffix
+  short_description: Returns the public suffix of a DNS name
+  version_added: 0.1.0
+  description:
+    - Returns the public suffix of a DNS name.
+  options:
+    _input:
+      description:
+        - A DNS name.
+      type: string
+      required: true
+    keep_leading_period:
+      description:
+        - This controls whether the leading period of a public suffix is preserved or not.
+      type: boolean
+      default: true
+  extends_documentation_fragment:
+    - community.dns.filters
+    - community.dns.filters.public_suffix
+    - community.dns.filters.get
+  author:
+    - Felix Fontein (@felixfontein)
+
+EXAMPLES: |
+  - name: Extract the public suffix from a DNS name
+    ansible.builtin.set_fact:
+      public_suffix: "{{ 'www.ansible.co.uk' | community.dns.get_public_suffix }}"
+      # Should result in '.co.uk'
+
+RETURN:
+  _value:
+    description: The public suffix.
+    type: string

plugins/filter/get_registrable_domain.yml

@@ -0,0 +1,29 @@
+DOCUMENTATION:
+  name: get_registrable_domain
+  short_description: Returns the registrable domain name of a DNS name
+  version_added: 0.1.0
+  description:
+    - Returns the registrable domain name of a DNS name.
+  options:
+    _input:
+      description:
+        - A DNS name.
+      type: string
+      required: true
+  extends_documentation_fragment:
+    - community.dns.filters
+    - community.dns.filters.registerable_domain
+    - community.dns.filters.get
+  author:
+    - Felix Fontein (@felixfontein)
+
+EXAMPLES: |
+  - name: Extract the registrable domain from a DNS name
+    ansible.builtin.set_fact:
+      public_suffix: "{{ 'www.ansible.co.uk' | community.dns.get_registrable_domain }}"
+      # Should result in 'ansible.co.uk'
+
+RETURN:
+  _value:
+    description: The registrable domain.
+    type: string

plugins/filter/remove_public_suffix.yml

@@ -0,0 +1,34 @@
+DOCUMENTATION:
+  name: remove_public_suffix
+  short_description: Removes the public suffix from a DNS name
+  version_added: 0.1.0
+  description:
+    - Removes the public suffix from a DNS name.
+  options:
+    _input:
+      description:
+        - A DNS name.
+      type: string
+      required: true
+    keep_trailing_period:
+      description:
+        - This controls whether the trailing period of the prefix (that is, the part before the
+          public suffix) is preserved or not.
+      type: boolean
+      default: false
+  extends_documentation_fragment:
+    - community.dns.filters
+    - community.dns.filters.public_suffix
+  author:
+    - Felix Fontein (@felixfontein)
+
+EXAMPLES: |
+  - name: Remove the public suffix from a DNS name
+    ansible.builtin.set_fact:
+      public_suffix: "{{ 'www.ansible.co.uk' | community.dns.remove_public_suffix }}"
+      # Should result in 'www.ansible'
+
+RETURN:
+  _value:
+    description: The part of the DNS name before the public suffix.
+    type: string

plugins/filter/remove_registrable_domain.yml

@@ -0,0 +1,34 @@
+DOCUMENTATION:
+  name: remove_registrable_domain
+  short_description: Removes the registrable domain name from a DNS name
+  version_added: 0.1.0
+  description:
+    - Removes the registrable domain name from a DNS name.
+  options:
+    _input:
+      description:
+        - A DNS name.
+      type: string
+      required: true
+    keep_trailing_period:
+      description:
+        - This controls whether the trailing period of the prefix (that is, the part before the
+          registrable domain) is preserved or not.
+      type: boolean
+      default: false
+  extends_documentation_fragment:
+    - community.dns.filters
+    - community.dns.filters.registerable_domain
+  author:
+    - Felix Fontein (@felixfontein)
+
+EXAMPLES: |
+  - name: Remove the registrable domain from a DNS name
+    ansible.builtin.set_fact:
+      public_suffix: "{{ 'www.ansible.co.uk' | community.dns.remove_registrable_domain }}"
+      # Should result in 'www'
+
+RETURN:
+  _value:
+    description: The part of the DNS name before the registrable domain.
+    type: string

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

@@ -6,6 +6,7 @@
 __metaclass__ = type
 
 import os
+import os.path
 import sys
 
 
@@ -26,15 +27,30 @@ 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):
+            # Enable this once we no longer support Ansible 2.9:
+            # print('%s: is a symbolic link' % (path, ))
+            pass
+        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)))