pongo2 v2 released

I'm happy to release the first major update for pongo2: v2. It got a lot of new features and bug fixes. Thanks to all reporters and contributors.

This release is backwards-incompatible to v1 which means chances are you have to adapt your codebase (slightly) in order to use v2. The pongo2 playground already uses pongo v2 (including the new features like sandboxing) and now got the official pongo2-addons package enabled for testing and playing with pongo2. pongo2-addons is already ready to use with pongo v2.

To install v2 and get backwards-compatible changes and bugfixes for later versions of the v2 series, use this import path:

gopkg.in/flosch/pongo2.v2 (documentation)

Use this import path to stick with the latest development version of pongo2:

github.com/flosch/pongo2 (documentation)

New major features

• Template sets: pongo2 allows to group similar kind of templates using a technique called template sets (for example web vs. email templates). Users can apply different configurations and sandbox restrictions (see below) on a specific template set. A default template set is created when pongo2 is imported (this is the one all pongo2-global API functions like From* are working on); see the DefaultSet here. Features of the template sets include:
  • Debugging: If Debug is set to true, logging of specific errors occur to stdout (you can print out errors as well using the new ExecutionContext.Logf function which will only print out your logging information when Debug is true). Debug has implications on the new template caching function as well (see below).
  • Globals: It is now possible to provide a global context (in addition to a per-template context) for a template set. It's always possible to override global variables through a per-template context.
  • Base directory: The previous behavior of a filename lookup (inside templates, for example when using the include, extends or ssi-tag, or outside templates when calling the From*()-functions) was, in case of a relative path, to lookup the filename relative to the application's directory or, in case of an absolute path, to take this absolute one. It's now possible to change the base lookup directory (for relative paths) by using the new template set functions SetBaseDirectory() and BaseDirectory().
  • Sandboxing: To provide more security, pongo2 introduces a per-template-set sandbox. It can prohibit the usage of filters and tags or restrict file accesses (within templates when using a file-sensitive tag/filter like include or outside of templates when using a function like From*()). Use the attribute SandboxDirectories to provide path patterns supported by http://golang.org/pkg/path/filepath/#Match in order to restrict the access to specifc files or directories. You can limit the tag/filter access by using the two new template set functions BanFilter and BanTag.
• Template caching: pongo2 introduces a new API function FromCache which behaves like FromFile, but includes caching: FromCache only compiles a template once per template (even if called multiple times) and can be called from multiple Goroutines (it's thread-safe). When debugging is activated (see above), FromCache will re-compile the given template on any request (simplifies development to see live changes).
• Macro imports/exports: pongo2 supports now importing and exporting of macros. Exporting is done by appending the export keyword to your macro declaration (like this: {% macro my_exported_macro(args1, args2="default string") export %}). You can import exported macros by using the new import tag: {% import "my_file_with_macros.html" my_exported_macro, another_exported_macro as renamed_macro %}. Macros import macros (chaining macros) is supported.
• New pongo2-specific tag set: Sets a variable to a given expression like this: {% set my_variable = 5 + 10 / another_var_number %}

New minor features

• Added support for the reversed argument for the for-tag
• elif-tag added (to support multiple cases when using the if-tag)
• It's now possible to replace the behavior of already registered tags and filters through 2 new API-functions: ReplaceTag and ReplaceFilter.
• It's now possible to mark a pongo2.Value as safe (so the escape filter won't get applied when outputting the value) using the new API-function AsSafeValue. This reduces the necessary to apply the safe filter manually, for example when using the markdown filter from the pongo2-addons package.
• New Error type which returns detailed machine-readable information (including the affected raw template line) about the error occurred and is now much more specific in some cases on which error occurred

Bugfixes and other improvements

• Better UTF-8 handling of filters and tags
• Performance of template execution improved
• Bugfix in handling of the parsed argument of the ssi-tag
• Bugfix related to the operator associativity
• Better documentation (but still not perfect)

Notable backward-incompatible API-changes (v1 <-> v2):

• The interface type INodeEvavluator got replaced by IEvaluator
• Function signature for tag and filter parsing/execution changed (error return type changed to *Error).

See the whole changelog here: v1...v2

As always, I'm happy about any feedback!