Metadata-Version: 1.0
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
