Resurrection of the comment filter

docsite/rst/playbooks_filters.rst

@@ -352,6 +352,73 @@ override those in `b`, and so on.
 This behaviour does not depend on the value of the `hash_behaviour`
 setting in `ansible.cfg`.
 
+.. _comment_filter:
+
+Comment Filter
+--------------
+
+.. versionadded:: 2.0
+
+The `comment` filter allows to decorate the text with a chosen comment
+style. For example the following::
+
+    {{ "Plain style (default)" | comment }}
+
+will produce the this output::
+
+    #
+    # Plain style (default)
+    #
+
+Similar way can be applied style for C (``//...``), C block
+(``/*...*/``), Erlang (``%...``) and XML (``<!--...-->``)::
+
+    {{ "C style" | comment('c') }}
+    {{ "C block style" | comment('cblock') }}
+    {{ "Erlang style" | comment('erlang') }}
+    {{ "XML style" | comment('xml') }}
+
+It is also possible to fully customize the comment style::
+
+    {{ "Custom style" | comment('plain', prefix='#######\n#', postfix='#\n#######\n   ###\n    #') }}
+
+That will create the following output::
+
+    #######
+    #
+    # Custom style
+    #
+    #######
+       ###
+        #
+
+The filter can also be applied to any Ansible variable. For example to
+make the output of the ``ansible_managed`` variable more readable, we can
+change the definition in the ``ansible.cfg`` file to this::
+
+    [defaults]
+
+    ansible_managed = This file is managed by Ansible.%n
+      template: {file}
+      date: %Y-%m-%d %H:%M:%S
+      user: {uid}
+      host: {host}
+
+and then use the variable with the `comment` filter::
+
+    {{ ansible_managed | comment }}
+
+which will produce this output::
+
+    #
+    # This file is managed by Ansible.
+    #
+    # template: /home/ansible/env/dev/ansible_managed/roles/role1/templates/test.j2
+    # date: 2015-09-10 11:02:58
+    # user: ansible
+    # host: myhost
+    #
+
 .. _other_useful_filters:
 
 Other Useful Filters

lib/ansible/plugins/filter/core.py

@@ -248,6 +248,83 @@ def combine(*terms, **kwargs):
     else:
         return dict(itertools.chain(*map(iteritems, terms)))
 
+def comment(text, style='plain', **kw):
+    # Predefined comment types
+    comment_styles = {
+        'plain': {
+            'decoration': '# '
+        },
+        'erlang': {
+            'decoration': '% '
+        },
+        'c': {
+            'decoration': '// '
+        },
+        'cblock': {
+            'beginning': '/*',
+            'decoration': ' * ',
+            'end': ' */'
+        },
+        'xml': {
+            'beginning': '<!--',
+            'decoration': ' - ',
+            'end': '-->'
+        }
+    }
+
+    # Pointer to the right comment type
+    style_params = comment_styles[style]
+
+    if 'decoration' in kw:
+        prepostfix = kw['decoration']
+    else:
+        prepostfix = style_params['decoration']
+
+    # Default params
+    p = {
+        'newline': '\n',
+        'beginning': '',
+        'prefix': (prepostfix).rstrip(),
+        'prefix_count': 1,
+        'decoration': '',
+        'postfix': (prepostfix).rstrip(),
+        'postfix_count': 1,
+        'end': ''
+    }
+
+    # Update default params
+    p.update(style_params)
+    p.update(kw)
+
+    # Compose substrings for the final string
+    str_beginning = ''
+    if p['beginning']:
+        str_beginning = "%s%s" % (p['beginning'], p['newline'])
+    str_prefix = str(
+        "%s%s" % (p['prefix'], p['newline'])) * int(p['prefix_count'])
+    str_text = ("%s%s" % (
+        p['decoration'],
+        # Prepend each line of the text with the decorator
+        text.replace(
+            p['newline'], "%s%s" % (p['newline'], p['decoration'])))).replace(
+                # Remove trailing spaces when only decorator is on the line
+                "%s%s" % (p['decoration'], p['newline']),
+                "%s%s" % (p['decoration'].rstrip(), p['newline']))
+    str_postfix = p['newline'].join(
+        [''] + [p['postfix'] for x in range(p['postfix_count'])])
+    str_end = ''
+    if p['end']:
+        str_end = "%s%s" % (p['newline'], p['end'])
+
+    # Return the final string
+    return "%s%s%s%s%s" % (
+        str_beginning,
+        str_prefix,
+        str_text,
+        str_postfix,
+        str_end)
+
+
 class FilterModule(object):
     ''' Ansible core jinja2 filters '''
 
@@ -320,4 +397,7 @@ class FilterModule(object):
 
             # merge dicts
             'combine': combine,
+
+            # comment-style decoration
+            'comment': comment,
         }