zc.recipe.macro 1.3.0

Macro-recipe for buildout.

Basic Use

In 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 hard

Result:

[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 Values

It 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 = rock

Result:

[hard-rocker]

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

Creating Parts

Of 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 hard

Result:

[hard-rocker]

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

Targets

Often, 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-parameters

Result:

[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-parameters

Result:

[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 night

Order of Precedence for Recipes for Result Sections

The source for the recipe option 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 definition

The 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-parameters

Result:

[hard-rocker]

question = Why do I rock so hard? recipe = zc.recipe.macro:test4 rocking-style = so hard

In 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-parameters

Result:

[hard-rocker]

question = Why do I rock so hard? recipe = zc.recipe.macro:test3 rocking-style = so hard

In 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-parameters

Result:

[hard-rocker]

question = Why do I rock so hard? recipe = zc.recipe.macro:test2 rocking-style = so hard

In 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-parameters

Result:

[hard-rocker]

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

Special Variables

zc.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-parameters

Result:

[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:empty

1.3.0 (2009-07-22)

• The recipe option for result sections is now pulled from the following

sources, in this order:

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 definition

• Correct 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 ReST

1.2.2 (2008-07-11)

• Fixed a bug in setup.py where setuptools was not being imported
• Changed date format in CHANGES.txt to YYYY-MM-DD

1.2.1 (2008-07-10)

• Fixed a typo in the quickstart

1.2.0 (2008-07-10)

• First release