collective.recipe.template Buildout recipe to generate a text file from a template Introduction ************ This recipe can be used to generate textfiles from a (text) template. .. contents:: Starting with version 1.3 you can also specify a path to the output file and the path will be created, if it does not exist. A short example:: [buildout] parts = zope.conf [message] recipe = collective.recipe.template input = templates/message.in output = ${buildout:parts-directory}/etc/message mymessage = Hello, World! In the template you can use the exact same variables as you can use in the buildout configuration. For example an input file can look like this:: My top level directory is ${buildout:directory} Executables are stored in ${buildout:bin-directory} As an extension to the buildout syntax you can reference variables from the current buildout part directly. For example:: My message is: ${mymessage} Why another template recipe? ============================ Both `iw.recipe.template`_ and `inquant.recipe.textfile`_ claim to do the same thing. I have found them to be undocumented and too buggy for real world use, and neither are in a public repository where I could fix them. In addition this implementation leverages the buildout variable substitution code, making it a lot simpler. .. _iw.recipe.template: http://pypi.python.org/pypi/iw.recipe.template .. _inquant.recipe.textfile: http://pypi.python.org/pypi/inquant.recipe.textfile Detailed Description ******************** Simple creation of a file out of a template =========================================== Lets create a minimal `buildout.cfg` file:: >>> write('buildout.cfg', ... ''' ... [buildout] ... parts = template ... offline = true ... ... [template] ... recipe = collective.recipe.template ... input = template.in ... output = template ... ''') We create a template file:: >>> write('template.in', ... '''# ... My template knows about buildout path: ... ${buildout:directory} ... ''') Now we can run buildout:: >>> print system(join('bin', 'buildout')), Installing template. The template was indeed created:: >>> cat('template') # My template knows about buildout path: .../sample-buildout The variable ``buildout:directory`` was also substituted by a path. Creating a template in a variable path ====================================== Lets create a minimal `buildout.cfg` file. This time the output should happen in a variable path:: >>> write('buildout.cfg', ... ''' ... [buildout] ... parts = template ... offline = true ... ... [template] ... recipe = collective.recipe.template ... input = template.in ... output = ${buildout:parts-directory}/template ... ''') Now we can run buildout:: >>> print system(join('bin', 'buildout')), Uninstalling template. Installing template. The template was indeed created:: >>> cat('parts', 'template') # My template knows about buildout path: .../sample-buildout Creating missing paths ====================== If an output file should be created in a path that does not yet exist, then the missing items will be created for us:: >>> write('buildout.cfg', ... ''' ... [buildout] ... parts = template ... offline = true ... ... [template] ... recipe = collective.recipe.template ... input = template.in ... output = ${buildout:parts-directory}/etc/template ... ''') >>> print system(join('bin', 'buildout')), Uninstalling template. Installing template. Also creation of several subdirectories is supported:: >>> write('buildout.cfg', ... ''' ... [buildout] ... parts = template ... offline = true ... ... [template] ... recipe = collective.recipe.template ... input = template.in ... output = ${buildout:parts-directory}/foo/bar/template ... ''') >>> print system(join('bin', 'buildout')), Uninstalling template. Installing template. >>> cat('parts', 'foo', 'bar', 'template') # My template knows about buildout path: .../sample-buildout When changes happen to the output path, then the old path is removed on uninstall. Therefore the ``etc/`` directory created above has vanished now:: >>> ls('parts') d foo Changelog ********* 1.3 - 2009-04-28 ================ * Add support for output path creation. You can do:: output = /path/to/target and intermediate path items will be created if they do not exist. [ulif] * Add tests. [ulif] 1.2 - 2008-12-09 ================ (By accident the 1.1 release was marked as 1.2. So in fact they are the same.) 1.1 - 2008-12-09 ================ * Correct handling of multiple variables in a line. Bugreport and patch from Roman Susi. [wichert] 1.0 - 2008-10-16 ================ * Copy the mode of the input file to the output file. This makes it possible to create executable scripts. [wichert] * Add missing link in README. [wichert] 1.0rc2 - 2008-07-04 =================== * Add a MANIFEST.in with instructions to include docs/, otherwise the package will not install. [wichert] 1.0rc1 - 2008-07-04 =================== * Initial release. [wichert] Wichert Akkerman b63a6afc1b6baf3563100e9a42e7f274c0f8bdc2 1.3