.. contents::

Structures
==========

Structures are a new feature added to the templer system that goes a bit beyond
what normal Paster templates offer. The Structures system was added to templer
in order to solve a particular problem. What follows is a description of the
problem as well as a brief outline of the Structures solution.

The Problem
-----------

There are three design choices that Paster makes about its templates that can
cause problems in a complex package generating system like templer:

1. In Paster, each template is registered in setup.py as an entry point in the
   'paste.paster_create_template' category. This means that each template you
   create in a package like templer is always found as a 'runnable' template by
   paste when it looks to see what template commands are available from installed
   packages.
2. In Paster, each paster template can have one and only one 'template'
   directory which holds the source files to be generated when the paster 
   template is run.
3. In Paster, when a template is run, *all* the source files in its template
   directory are generated. If you wish to end up with only some of them, you
   *must* act after running the template to delete unwanted files. You cannot
   prevent them from being written before you run them.

In a package generating system like templer, these choices become problematic
because there is a high degree of redundancy across the available package
templates. The purpose of templer is to help encourage best-practice package
layout, and so common elements like top-level package documentation are shared
across all the available templates. We'd like to be able to ensure that any
package generated by the templer system has the following top-level structure::

  namespace.package
   |
   - CHANGES.txt
   - CONTRIBUTORS.txt
   - README.txt
   - setup.py
   - docs
      |
      - LICENSE.txt
      - LICENSE.GPL
   - src
      |
      - namespace
         |
         - package
            |
            - <package code ...>

Given the paster template system, we have two choices to help us achieve this
goal. 

* create a basic template that holds only the CHANGES.txt, CONTRIBUTORS.txt and
  README.txt files and ensure that all our other templates inherit from that
  one.
* include these three source files in *each* of our package templates
  separately.

In the first case, we end up with a runnable template registered in paster that
we really don't ever want to be able to run separately. In the second case we
end up with a maintenance nightmare as every time we update the format for one
of our source files, or change something about how that base structure is set up
we have to change it for all the templates we have.

Let's look at another example to further illustrate this point. In the templar
system, we'd like to be able to offer a user his or her choice of licenses for
their package. There are many license options out there, and we do not wish to
dictate which one our users choose for their package. 

The ZopeSkel package, from which templer is descended, actually offers the
choice of license as an option for most of its packages. However, due to the
third limitation in paster listed above we cannot actually give them the license
they ask for. No matter what choice they make, the license they end up with is
the GPL.

To solve this problem in paster, we'd need to add all the possible licenses to
our template package, render them all using the appropriate values from the
interactive portion of the template run, and then after rendering them all,
delete the ones we do not want. This is obviously inefficient.

The Structures Solution
-----------------------

In templer, we've chosen to solve this problem by creating 'structures', a close
parallel to paster templates, but with some key differences.

* structures cannot be 'run' like templates, they do not define questions to be
  answered interactively by the user. Instead, templates which rely on a given
  structure are responsible for gathering the answers to any questions on which
  the structure will rely.
* structures are registered in a separate category of entry points. This way,
  they do not end up being listed alongside our actual templates as individually
  usable.
* structures provide an additional var type, the structure_select, which allows
  a user to choose from a number of options at template runtime. The selected
  structure is then injected into the template's required_structures list before
  the rendering phase of the template run.

These changes allow us to solve the problems above in a clean, efficient manner.

