Invocation
==========

The Magro Tool
--------------

You can use the ``magro_eval`` script to evaluate your magro template,
this script receives input from ``stdin`` and outputs to ``stdout`` by
default; but you can tell it to receive its input from a file and to write
its output to another file.
::

    magro_eval -o target.html source_template

Python Library
--------------

Template class
~~~~~~~~~~~~~~

The ``Template`` class is used to transform a template string to an output string.

Templates can be created using the ``Template`` constructor, which requires
a ``string`` argument with the source code of the template:

        >>> template = Template("'hello ' target \n")
        >>> template.render({ 'target' : 'world' })
        u'hello world'

The ``render`` method is used for evaluating the template to a ``dict`` or
``Context`` (a ``dict`` subclass) containing the values for the symbols used
in the template.

Environment class
~~~~~~~~~~~~~~~~~

The central class of the Magro API is the ``Environment`` class, which is used
to obtain instances of the ``Template`` class.

The constructor of ``Environment`` has two optional arguments; a ``loader``
that will be used to fetch the source code of the templates and a dictionary
of settings, which is only a set of values that will be available for all the
templates created using this environment.

By default, the ``Environment`` will use a ``FileSystemLoader`` instance
as loader.

        >>> from magro import Environment
        >>> env = Environment()
        >>> env.loader
        <magro.loaders.FileSystemLoader object at 0x00B46030>

Templates can be obtained by using the get_template method which requires a
``template_id`` that identifies the requested template. In the case of
``FileSystemLoader``, the ``template_id`` is the name of the template file
relative to any of the paths in its ``path`` attribute.

        >>> env = Environment()
        >>> template = env.get_template( 'welcome.html' )
        >>> template.render()
        u'This is the output of the template'

Templates created by directly calling the ``Template`` constructor will share
a common default ``Environment``, unless the ``environment`` argument of the
constructor is especified.