HOWTO

          _/_/_/    _/_/_/  _/_/_/_/_/
       _/        _/            _/
      _/        _/            _/
     _/        _/            _/
      _/_/_/    _/_/_/      _/


Fast and efficient Python based templating
language designed for generating source code.


What is CCT?
------------

CCT is templating language specialized for
generating source code. It has been developed
with a C/C++  in mind but should be usable
with basically any text based programming
language as well.


How does it work?
-----------------

CCT runs in two passes. First pass takes the
template file and generates a Python script
from it. The Python script is then executed
and generates the desired source code.

Given this choice the whole CCT engine is
just about 300 lines of python code.


Basic CCT code structure
------------------------

There are two types of lines, verbatim lines
and Python code lines. Python code lines are
escaped by the '@\s' characters. The rest of
the lines are considered verbatim (i.e.
copied to the output as they are).

Verbatim lines may also contain expressions
or function calls.

Expression is a Python code that yields
a value, which is converted into string and
included in the output.

Expressions are enclosed in double curly
braces i.e. {{ expression }}.

Function call is a Python code that produces
output (function that includes verbatim
lines). In order to keep the implementation
simple only one function call per line is
allowed.

Function calls are enclosed in curly braces
followed by at sing i.e. {@ call() @}.

Simple CCT code example and output
--------------------------------------------
@ def func()
Hello World!
@ end
@
@ for i in range(1, 4):
{@ func() @} #{{ i }}!
--------------------------------------------
Hello World #1!
Hello World #2!
Hello World #3!
--------------------------------------------

The include and end keywords
----------------------------

There are two more keywords (which are not
part of the Python language) that are
recognized by the CCT parser.

The 'include' keyword is used for including
template files (e.g. configuration, common
functions, etc.).

The 'end' keyword is used for controlling
indentation level for the verbatim lines.
Consider following example:

--------------------------------------------
int arr[] = {
@ for i in range(1, 10):
@     if i % 2:
	{{ i }},
};
--------------------------------------------

Here it's not immediately clear to which
block does the last line '};' belongs to. As
a matter of fact CCT will use the last
opened block here. To get the expected
output here we need to terminate it
explicitly by the 'end' keyword.

--------------------------------------------
int arr[] = {
@ for i in range(1, 10):
@     if i % 2:
	{{ i }},
@ end
};
--------------------------------------------

Now the CCT knows that the last line is
outside of the for block.


Header and footer functions
---------------------------

CCT can be also used to generate header
and footer which may be useful for example
for generating guards for C header files.

All that is needed is to define header
and/or footer function.

Following example shows automatic C header
guards. This snippet of code could be
placed into a file header.t and included
in the actual header.

Automatic C header guards
--------------------------------------------
@ def cct_header(filename, template):
/*
 * {{ filename }}
 *
 * DO NOT MODIFY THIS FILE DIRECTLY!
 */
@     guard = filename.upper().replace('.', '_')
#ifndef {{ guard }}
#define {{ guard }}

@ def cct_footer(filename, template):
@     guard = filename.upper().replace('.', '_')
#endif /* {{ guard }} */
--------------------------------------------