j2 / README.rst

Full commit


j2 is commandline text templating & rendering tool, it brings the power of the Jinja2 engine to general purpose text compilation. The tool excels at the various situations where you need to compile/generate text files as part of a build system or other types of automation process (sysadmin to configuration files etc)


Jinja2 is a very capable templating system used throughout the Python community. Its features & capabilities are extensive & robust. However to access, one typically writes a python application or script and programatically loads & renders templates.

j2 makes this Jinja2 templating available on the command line. Using an MVC metaphor, think of the python file (module foo) as the (M)odel, a template file template.j2t as the (View) and the commandline j2 interface as the (C)ontroller.

Template files (usually suffixed with j2t) are simply normal Jinja2 templates. The format of these files is extensively documented at the Jinja2 project homepage.

Modules are just a fancy word for py files. They provide the mechanism to load the context that is used in rendering the template. All modules are loaded into the global namespace via an exec of "from module import *". The entire global namespace is then made available in the templates for rendering.

The combination of templates and flexible module loading makes j2 a very useful tool in code generation or any other general purpose cmdline template processing. We have been using j2 successfully in our build environment similarly to a compiler for rendering templates into output files.

See doc/info.txt for a detailed man page