Package: zc.recipe.macro
Macro Quickstartzc.recipe.macro is a set of recipes allowing sections, or even parts, to be
created dynamically from a macro section and a parameter section.  This enables
the buildout to keep its data seperate from its output format.Basic UseIn the most basic use of a macro, a section invokes the macro on itself, and
uses itself as the parameter provider.
Buildout:[buildout]
parts = hard-rocker

[rock]
question = Why do I rock $${:rocking-style}?

[hard-rocker]
recipe = zc.recipe.macro
macro = rock
rocking-style = so hardResult:[hard-rocker]
recipe = zc.recipe.macro:empty
result-sections = hard-rocker
rocking-style = so hard
question = Why do I rock so hard?The recipe gets changed to zc.recipe.macro:empty, which is a do nothing recipe,
because the invoking secion must be a part in order to execute recipes, and
buildout demands that parts have a recipe, so it couldn’t be emptied.Default ValuesIt is possible to include default values for parameters in a macro.Buildout:[buildout]
parts = hard-rocker

[rock]
question = Why do I rock $${:rocking-style}?
rocking-style = so hard

[hard-rocker]
recipe = zc.recipe.macro
macro = rockResult:[hard-rocker]
recipe = zc.recipe.macro:empty
result-sections = hard-rocker
rocking-style = so hard
question = Why do I rock so hard?Creating PartsOf course, there wouldn’t much point to this if one could only create sections
with a dummy recipe.  This is where the result-recipe option comes in.Buildout:[buildout]
parts = hard-rocker

[rock]
question = Why do I rock $${:rocking-style}?

[hard-rocker]
recipe = zc.recipe.macro
result-recipe = zc.recipe.macro:test1
macro = rock
rocking-style = so hardResult:[hard-rocker]
recipe = zc.recipe.macro:test1
result-sections = hard-rocker
question = Why do I rock so hard?
rocking-style = so hardTargetsOften, one wants to create multiple new sections.  This is possible with the
targets option.  This is only useful, however, if one can provide multiple
sources for parameters.  Fortunately, you can.  Each new section can optionally
be followed by a colon and the name of a section to use for parameters.Buildout:[buildout]
parts = rockers hard-rocker socks-rocker tired-rocker

[rock]
question = Why do I rock $${:rocking-style}?
rocking-style = $${:rocking-style}

[hard-rocker-parameters]
rocking-style = so hard

[socks-rocker-parameters]
rocking-style = my socks

[tired-rocker-parameters]
rocking-style = all night

[rockers]
recipe = zc.recipe.macro
result-recipe = zc.recipe.macro:empty
macro = rock
targets =
    hard-rocker:hard-rocker-parameters
    socks-rocker:socks-rocker-parameters
    tired-rocker:tired-rocker-parametersResult:[rockers]
recipe = zc.recipe.macro:empty
result-sections = hard-rocker socks-rocker tired-rocker

[hard-rocker]
recipe = zc.recipe.macro:empty
rocking-style = so hard
question = Why do I rock so hard?

[socks-rocker]
recipe = zc.recipe.macro:empty
rocking-style = my socks
question = Why do I rock my socks?

[tired-rocker]
recipe = zc.recipe.macro:empty
rocking-style = all night
question = Why do I rock all night?In the previous example we hardcoded the result parts after the invoker in
${buildout:parts}.  This is brittle, because someone might change the names of
the targets or alphabetize the parts list. An invocation will have a list of
the sections it modified in its result-sections variable, which is created when
the macro is executed.Buildout:[buildout]
parts = ${rockers:result-sections}

[rock]
question = Why do I rock $${:rocking-style}?
rocking-style = $${:rocking-style}

[hard-rocker-parameters]
rocking-style = so hard

[socks-rocker-parameters]
rocking-style = my socks

[tired-rocker-parameters]
rocking-style = all night

[rockers]
recipe = zc.recipe.macro
result-recipe = zc.recipe.macro:test1
macro = rock
targets =
    hard-rocker:hard-rocker-parameters
    socks-rocker:socks-rocker-parameters
    tired-rocker:tired-rocker-parametersResult:[rockers]
result-sections = hard-rocker socks-rocker tired-rocker

[hard-rocker]
question = Why do I rock so hard?
recipe = zc.recipe.macro:test1
rocking-style = so hard

[socks-rocker]
question = Why do I rock my socks?
recipe = zc.recipe.macro:test1
rocking-style = my socks

[tired-rocker]
question = Why do I rock all night?
recipe = zc.recipe.macro:test1
rocking-style = all nightOrder of Precedence for Recipes for Result SectionsThe source for therecipeoption for result sections has a particular
precedence, as follows:1) recipe in the parameters section of the macro target
2) result-recipe in the parameters section for the macro target
3) result-recipe in the macro invocation
4) recipe in the macro definitionThe following tests will illustrate these rules, starting with rule 4 and
building up.In the following buildout, rock:recipe will be used in the [hard-rockers]
section as the recipe, because of rule 4.
Buildout:[buildout]
parts = rockers

[rock]
question = Why do I rock $${:rocking-style}?
rocking-style = $${:rocking-style}
recipe = zc.recipe.macro:test4

[hard-rocker-parameters]
rocking-style = so hard

[rockers]
recipe = zc.recipe.macro
macro = rock
targets = hard-rocker:hard-rocker-parametersResult:[hard-rocker]
question = Why do I rock so hard?
recipe = zc.recipe.macro:test4
rocking-style = so hardIn the following buildout, ${rockers:result-recipe} will be used because of rule 3.
Buildout:[buildout]
parts = rockers

[rock]
question = Why do I rock $${:rocking-style}?
rocking-style = $${:rocking-style}
recipe = zc.recipe.macro:test4

[hard-rocker-parameters]
rocking-style = so hard

[rockers]
recipe = zc.recipe.macro
result-recipe = zc.recipe.macro:test3
macro = rock
targets = hard-rocker:hard-rocker-parametersResult:[hard-rocker]
question = Why do I rock so hard?
recipe = zc.recipe.macro:test3
rocking-style = so hardIn the following buildout, ${hard-rocker-paramers:result-recipe} will be used because of rule 2.
Buildout:[buildout]
parts = rockers

[rock]
question = Why do I rock $${:rocking-style}?
rocking-style = $${:rocking-style}
recipe = zc.recipe.macro:test4

[hard-rocker-parameters]
result-recipe = zc.recipe.macro:test2
rocking-style = so hard

[rockers]
recipe = zc.recipe.macro
result-recipe = zc.recipe.macro:test3
macro = rock
targets = hard-rocker:hard-rocker-parametersResult:[hard-rocker]
question = Why do I rock so hard?
recipe = zc.recipe.macro:test2
rocking-style = so hardIn the following buildout, ${hard-rocker-parameters:recipe} will be used because of rule 1.
Buildout:[buildout]
parts = rockers

[rock]
question = Why do I rock $${:rocking-style}?
rocking-style = $${:rocking-style}
recipe = zc.recipe.macro:test4

[hard-rocker-parameters]
recipe = zc.recipe.macro:test1
result-recipe = zc.recipe.macro:test2
rocking-style = so hard

[rockers]
recipe = zc.recipe.macro
result-recipe = zc.recipe.macro:test3
macro = rock
targets = hard-rocker:hard-rocker-parametersResult:[hard-rocker]
question = Why do I rock so hard?
recipe = zc.recipe.macro:test1
rocking-style = so hardSpecial Variableszc.recipe.macro uses __name__ to mean the name of the section the macro is
being invoked upon.  This allows one to not know the name of particular
section, but still use it in output.Buildout:[buildout]
parts = rockers

[rock]
question = Why does $${:__name__} rock $${:rocking-style}?

[hard-rocker-parameters]
rocking-style = so hard

[socks-rocker-parameters]
rocking-style = my socks

[tired-rocker-parameters]
rocking-style = all night

[rockers]
recipe = zc.recipe.macro
result-recipe = zc.recipe.macro:empty
macro = rock
targets =
    hard-rocker:hard-rocker-parameters
    socks-rocker:socks-rocker-parameters
    tired-rocker:tired-rocker-parametersResult:[rockers]
recipe = zc.recipe.macro:empty
result-sections = hard-rocker socks-rocker tired-rocker

[hard-rocker]
question = Why does hard-rocker rock so hard?
recipe = zc.recipe.macro:empty

[socks-rocker]
question = Why does socks-rocker rock my socks?
recipe = zc.recipe.macro:empty

[tired-rocker]
question = Why does tired-rocker rock all night?
recipe = zc.recipe.macro:emptyCHANGES1.3.0 (2009-07-22)The recipe option for result sections is now pulled from the following
sources, in this order:recipe in the parameters section of the macro targetresult-recipe in the parameters section for the macro targetresult-recipe in the macro invocationrecipe in the macro definitionCorrect a rest error, that prevent the package of being installed with
docutils 0.4.1.2.5 (2009-03-05)Removed version sections from the documentation.Improved test coverage.Put QUICKSTART.txt under test, using manuel.Macro invocations will grow a result-sections value that lists the sections
they modified or created.README.txt is now mostly Manuellified.1.2.4 (2008-07-18)Fixed a bug that made self-targetting invocations fail when the macro utilized
default values and the option that read the default came out the Options
iteration first, added a regression test.Changed the test setup so that buildouts are tested by calling methods rather
than creating a subprocess.  This allows for the –coverage flage to work in
bin/test, and makes debugging and mimmicking the test output significantly
easier.Fixed addition of targets so that they will show up properly when one calls
buildout.keys().1.2.3 (2008-07-11)Fixed a bug in the CHANGES ReST1.2.2 (2008-07-11)Fixed a bug in setup.py where setuptools was not being importedChanged date format in CHANGES.txt to YYYY-MM-DD1.2.1 (2008-07-10)Fixed a typo in the quickstart1.2.0 (2008-07-10)First release