[Checkins] SVN: zc.buildout/trunk/ New features:

[Jim Fulton]

Log message for revision 103244:
  New features:
  
  - When doing variable substitutions, you can omit the section name to
    refer to a variable in the same section (e.g. ${:foo}).
  
  - When doing variable substitution, you can use the special option,
    ``_buildout_section_name_`` to get the section name.  This is most handy
    for getting the current section name (e.g. ${:_buildout_section_name_}).
  
  - A new special option, ``<`` allows sections to be used as macros.
  

Changed:
  U   zc.buildout/trunk/CHANGES.txt
  U   zc.buildout/trunk/src/zc/buildout/buildout.py
  U   zc.buildout/trunk/src/zc/buildout/buildout.txt

-=-
Modified: zc.buildout/trunk/CHANGES.txt
===================================================================
--- zc.buildout/trunk/CHANGES.txt	2009-08-26 21:43:17 UTC (rev 103243)
+++ zc.buildout/trunk/CHANGES.txt	2009-08-26 22:43:04 UTC (rev 103244)
@@ -9,8 +9,10 @@
 
 - When doing variable substitution, you can use the special option,
   ``_buildout_section_name_`` to get the section name.  This is most handy
-  for getting the current section name (e.g. ${:_buildout_section_name_}.
+  for getting the current section name (e.g. ${:_buildout_section_name_}).
 
+- A new special option, ``<`` allows sections to be used as macros.
+
 - Added annotate command for annotated sections. Displays sections
   key-value pairs along with the value origin.
 

Modified: zc.buildout/trunk/src/zc/buildout/buildout.py
===================================================================
--- zc.buildout/trunk/src/zc/buildout/buildout.py	2009-08-26 21:43:17 UTC (rev 103243)
+++ zc.buildout/trunk/src/zc/buildout/buildout.py	2009-08-26 22:43:04 UTC (rev 103244)
@@ -1027,6 +1027,9 @@
         name = self.name
         __doing__ = 'Initializing section %s.', name
 
+        if '<' in self._raw:
+            self._raw = self._do_extend_raw(name, self._raw, [])
+
         # force substitutions
         for k, v in self._raw.items():
             if '${' in v:
@@ -1047,6 +1050,33 @@
         self.recipe = recipe_class(buildout, name, self)
         buildout._parts.append(name)
 
+    def _do_extend_raw(self, name, data, doing):
+        if name == 'buildout':
+            return data
+        if name in doing:
+            raise zc.buildout.UserError("Infinite extending loop %r" % name)
+        doing.append(name)
+        try:
+            to_do = data.pop('<', None)
+            if to_do is None:
+                return data
+            __doing__ = 'Loading input sections for %r', name
+
+            result = {}
+            for iname in to_do.split('\n'):
+                iname = iname.strip()
+                if not iname:
+                    continue
+                raw = self.buildout._raw.get(iname)
+                if raw is None:
+                    raise zc.buildout.UserError("No section named %r" % iname)
+                result.update(self._do_extend_raw(iname, raw, doing))
+
+            result.update(data)
+            return result
+        finally:
+            assert doing.pop() == name
+
     def _dosub(self, option, v):
         __doing__ = 'Getting option %s:%s.', self.name, option
         seen = [(self.name, option)]
@@ -1178,7 +1208,7 @@
                     elif os.path.isfile(p):
                         os.remove(p)
                     else:
-                        self._buildout._logger.warn("Couldn't clean up %r.", p)
+                        self.buildout._logger.warn("Couldn't clean up %r.", p)
                 raise
         finally:
             self._created = None

Modified: zc.buildout/trunk/src/zc/buildout/buildout.txt
===================================================================
--- zc.buildout/trunk/src/zc/buildout/buildout.txt	2009-08-26 21:43:17 UTC (rev 103243)
+++ zc.buildout/trunk/src/zc/buildout/buildout.txt	2009-08-26 22:43:04 UTC (rev 103244)
@@ -979,7 +979,56 @@
     parts = data-dir debug
     ...
 
+Extending sections (macros)
+---------------------------
 
+A section (other than the buildout section) can extend one or more
+other sections using the ``<`` option.  Options from the referenced
+sections are copied to the refering section *before* variable
+substitution.  This, together with the ability to refer to variables
+of the current section allows sections to be used as macros.
+
+    >>> write(sample_buildout, 'buildout.cfg',
+    ... """
+    ... [buildout]
+    ... develop = recipes
+    ... parts = myfiles
+    ... log-level = INFO
+    ...
+    ... [debug]
+    ... recipe = recipes:debug
+    ...
+    ... [with_file1]
+    ... <= debug
+    ... file1 = ${:path}/file1
+    ... color = red
+    ...
+    ... [with_file2]
+    ... <= debug
+    ... file2 = ${:path}/file2
+    ... color = blue
+    ...
+    ... [myfiles]
+    ... <= with_file1
+    ...    with_file2
+    ... path = mydata
+    ... """)
+
+    >>> print system(buildout),
+    Develop: '/sample-buildout/recipes'
+    Uninstalling debug.
+    Uninstalling data-dir.
+    Installing myfiles.
+    color blue
+    file1 mydata/file1
+    file2 mydata/file2
+    path mydata
+    recipe recipes:debug
+
+In this example, the debug, with_file1 and with_file2 sections act as
+macros. In particular, the variable substitutions are performed
+relative to the myfiles section.
+
 Adding and removing options
 ---------------------------
 
@@ -1083,11 +1132,10 @@
     >>> os.chdir(sample_buildout)
     >>> print system(os.path.join(sample_buildout, 'bin', 'buildout')),
     Develop: '/sample-buildout/demo'
-    Uninstalling debug.
+    Uninstalling myfiles.
     Getting distribution for 'recipes'.
     zip_safe flag not set; analyzing archive contents...
     Got recipes 0.0.0.
-    Uninstalling data-dir.
     warning: install_lib: 'build/lib' does not exist -- no Python modules to install
 
 Verify option values.
@@ -1107,7 +1155,8 @@
 Annotated sections output shows which files are responsible for which
 operations.
 
-    >>> print system(os.path.join('bin', 'buildout') + ' annotate'), # doctest: +ELLIPSIS
+    >>> print system(os.path.join('bin', 'buildout') + ' annotate'),
+    ... # doctest: +ELLIPSIS
     <BLANKLINE>
     Annotated sections
     ==================