Rename !include to !import-variables (#91)

New name is more fitting, because we're actually not including anything
into the file itself, but importing a set of variables into the
namespace available to macros in the file. The old name also clashed
with the actual !include directive recommended to be used to include
data into the YAML structure, and we will need that directive one day,
therefore getting rid of ambiguity.

gluetool/tests/test_load_yaml.py

@@ -2,6 +2,7 @@
 
 import pytest
 
+import gluetool
 from gluetool import GlueError
 from gluetool.log import format_dict
 from gluetool.utils import load_yaml
@@ -53,3 +54,23 @@ def test_bad_yaml(tmpdir):
     with pytest.raises(GlueError,
                        match=r"(?ms)Unable to load YAML file '{}': .*? line 1, column 2".format(re.escape(filepath))):
         load_yaml(filepath)
+
+
+def test_import_variables(tmpdir, logger):
+    g = tmpdir.join('vars.yaml')
+    g.write("""---
+
+FOO: bar
+""")
+
+    f = tmpdir.join('test.yml')
+    f.write("""---
+
+# !import-variables {}
+
+- dummy: "{{{{ FOO }}}}"
+""".format(str(g)))
+
+
+    mapping = gluetool.utils.PatternMap(str(f), logger=logger, allow_variables=True)
+    assert mapping.match('dummy') == 'bar'

gluetool/utils.py

@@ -1161,7 +1161,7 @@ def _load_yaml_variables(data, enabled=True, logger=None):
     """
     Load all variables from files referenced by a YAML, and return function to render a string
     as a template using these variables. The files containing variables are mentioned in comments,
-    in a form ``# !include <filepath>`` form.
+    in a form ``# !import-variables <filepath>`` form.
 
     :param data: data loaded from a YAML file.
     :param bool enabled: when set to ``False``, variables are not loaded and a simple no-op
@@ -1188,14 +1188,14 @@ def _render_template_nop(s):
 
         return _render_template_nop
 
-    # Ok, so this YAML data contains comments. Check their values to find `!include` directives.
+    # Ok, so this YAML data contains comments. Check their values to find `!import-variables` directives.
     # Load referenced files and merged them into a single context.
     context = {}  # type: Dict[str, Any]
 
     for comment in data.ca.comment[1]:
         value = comment.value.strip()
 
-        if not value.startswith('# !include'):
+        if not value.startswith('# !import-variables'):
             continue
 
         try:
@@ -1239,7 +1239,7 @@ class SimplePatternMap(LoggerMixin, object):
     :param gluetool.log.ContextLogger logger: Logger used for logging.
     :param bool allow_variables: if set, both patterns and converters are first treated as templates,
         and as such are rendered before doing anything else. Map may contain special comments,
-        ``# !include <path>``, where path refers to a YAML file providing the necessary variables.
+        ``# !import-variables <path>``, where path refers to a YAML file providing the necessary variables.
     """
 
     def __init__(self, filepath, logger=None, allow_variables=False):
@@ -1357,7 +1357,7 @@ def _spice(pattern, s):
     :param gluetool.log.ContextLogger logger: Logger used for logging.
     :param bool allow_variables: if set, both patterns and converters are first treated as templates,
         and as such are rendered before doing anything else. Map may contain special comments,
-        ``# !include <path>``, where path refers to a YAML file providing the necessary variables.
+        ``# !import-variables <path>``, where path refers to a YAML file providing the necessary variables.
     """
 
     def __init__(self,