######
Vision
######

`piecutter` is about file generation. Its primary goal is to provide a generic
API to render templates against data.


****************************
Render template against data
****************************

`piecutter` has been created for the following pattern:

* you have a template. To its simplest expression, it is content with
  placeholders ;

* you have data, typically a mapping ;

* you want to render the template against the data.

The important point here is that, **as an user you want to focus on templates
and data**, because they are your content, the bits that you own and manage.

**As an user, you do not want to bother with the rendering process.** And that
is `piecutter`'s primary goal: encapsulate content generation, whatever the
template and the data you provide.


**********************
Wherever the templates
**********************

Templates can theorically live anywhere: on local filesystem, on remote places,
or they could be generated in some way... As an user, I do not want to bother
with template loading, I just want templates to be loaded and rendered against
data.

One could say templates are just strings and loading could be done by the user,
i.e. the feature could be simplified to "render string against data". But
templates often take advantage of features like "includes" or "extends". Such
features require loaders.

Of course `piecutter` cannot implement all template storages. It provides
implementation for simplest ones (string, local filesystem) and an API for
third-parties to implement additional loaders.


****************************
Whatever the template engine
****************************

As a matter of fact, templates are written using the syntax of one template
engine. But whatever this syntax, you basically want it rendered.


***********************
Data is dictionary-like
***********************

`piecutter` supports neither loading of various data formats nor loading from
various locations. The `Python`_ language has nice libraries for that purpose.

`piecutter` expects a structured data input, i.e. a dictionary-like object.
And it should be enough.


***********
A framework
***********

`piecutter` is a framework. It is built with flexibility in mind. It is a
library to build other software. It provides material to connect to third-party
tools. It is easy to extend.


.. rubric:: Notes & references

.. target-notes::

.. _`Python`: https://www.python.org