Global: create first example (formatting of namelists as YAML)

CHANGES.txt

@@ -9,6 +9,11 @@ Release Changes
 Release 1.2.1
 =============
 
+Global
+------
+
+* Created first example (formatting of namelists as YAML)
+
 Config
 ------
 

examples/README.rst

+=============
+Example files
+=============
+
+Templates
+=========
+
+``yaml.tmpl``
+-------------
+
+Format arbitrary namelists as YAML.
+
+To use this, place ``yaml.tmpl`` under ``standard_experiments`` and add ``.use_template = yaml`` to your namelist definition. See the header comment for details.

examples/yaml.tmpl

+#%#-
+#%#-Format namelist as YAML
+#%#-
+#%#-Take all definitions from context that are mappings, sequences, strings,
+#%#-numbers, or boolean, and format them as YAML entities.
+#%#-
+#%#-To mimic YAML expressiveness in configobj, we follow these conventions:
+#%#-(1) YAML lists with dictionary items
+#%#-  Sections the name of which starts with '-' are taken to be lists,
+#%#-  consisting of their scalars and subsections.
+#%#-  Empty subsections are formatted as YAML scalars without trailing ':'.
+#%#-  For convenience, empty scalars are also formatted as YAML scalars
+#%#-(2) Unnamed dictionaries
+#%#-  For sections the name of which starts with '+',
+#%#-  no identifier is generated.
+#%#-  Note that configobj still requires unambiguous naming of sections,
+#%#-  eg. [+ 1], [+ 2] etc.
+#%#-
+#%- macro format_yaml(key, value, level=0, item=false):
+#%      set indent = '  '*level+('- ' if item else '')
+#%      set separator = ' ' if key == '-' else ': '
+#%      if key.startswith('+'):
+#%          set key = ''
+#%          set separator = ''
+#%      endif
+#%      if item:
+#%          if key:
+#%              set level = level + 1
+#%          endif
+#%          if not value:
+#%              set separator = ''
+#%          endif
+#%      endif
+#%      if not key.startswith('.'):
+#%          if value is mapping and not key.startswith('-'):
+%{indent}%{key}%{separator}
+#%              for k_, v_ in value.items():
+%{format_yaml(k_, v_, level+1)-}
+#%              endfor
+#%          elif value is mapping and key.startswith('-'):
+#%              set key = key.lstrip('- ')
+%{indent}%{key}%{separator}
+#%              for k_, v_ in value.items():
+%{format_yaml(k_, v_, level+1, true)-}
+#%              endfor
+#%          elif value is sequence and value is not string:
+%{indent}%{key}%{separator}
+#%              for i_ in value:
+%{format_yaml('-', i_, level+1)-}
+#%              endfor
+#%          elif value is string or value is number or value is boolean
+%{indent}%{key}%{separator}%{value}
+#%          endif
+#%      endif
+#%  endmacro
+#%  for key, value in context().get_all().items():
+%{format_yaml(key, value)-}
+#%  endfor