Metadata-Version: 2.1
Name: z3c.recipe.template
Version: 0.1
Summary: Buildout recipe to generate a text file from a template
Home-page: http://pypi.python.org/pypi/z3c.recipe.template
Author: Uli Fouquet based on work of Wichert Akkerman
Author-email: grok-dev@zope.org
License: ZPL 2.1
Description: Introduction
        ************
        
        This recipe can be used to generate textfiles from a (text)
        template. Different to `collective.recipe.template`_ 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.
        
        `collective.recipe.template`_ actually lacks support for creating
        paths of target files to be generated (and tests).
        
        
        .. _iw.recipe.template: http://pypi.python.org/pypi/iw.recipe.template
        .. _inquant.recipe.textfile: http://pypi.python.org/pypi/inquant.recipe.textfile
        .. _collective.recipe.template: http://pypi.python.org/pypi/collective.recipe.template
        
        
        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 = z3c.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 = z3c.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 = z3c.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 = z3c.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
        
        
        Changes
        *******
        
        0.1 (2009-03-09)
        ================
        
        Initial build based on `collective.recipe.template`_
        
        .. _collective.recipe.template: http://pypi.python.org/pypi/collective.recipe.template
        
Keywords: template buildout zope
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Buildout
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: Zope Public License
Provides-Extra: test
