ctemplate/NEWS

=== 23 September 2010 ===

I've just released ctemplate 0.98.  The changes are settling down as
we approach ctemplate 1.0 -- a few new default modifiers, a few
performance tweaks, a few portability improvements, but nothing
disruptive.

In my testing for this release, I noticed that the template regression
test (but not other template tests) would segfault on gcc 4.1.1 when
compiled with -O2.  This seems pretty clearly to be a compiler bug; if
you need to use gcc 4.1.1 to compile ctemplate, you may wish to build
via `./configure CXXFLAGS="-O1 -g"` just to be safe.

=== 20 April 2010 ===

I've just released ctemplate 0.97.  This change consists primarily of
a significant change to the API: the addition of the `TemplateCache`
class, combined with deprecation of the `Template` class.

`TemplateCache` is a class that holds a collection of templates; this
concept always existed in ctemplate, but was not previously exposed.
Many static methods of the `Template` class, such as
`ReloadAllIfChanged()`, have become methods on `TemplateCache` instead
(the `Template` methods have been retained for backwards
compatibility.)  Other methods, such as `Expand()`, have become free
functions.  In fact, the entire `Template` class has been deprecated.

The deprecation of `Template` calls for changes in all clients of the
template code -- you can see in the example at the top of this page
how the code has changed from `Template* tpl =
ctemplate::Template::GetTemplate("example.tpl",
ctemplate::DO_NOT_STRIP); tpl->Expand(&output, &dict);` to
`ctemplate::ExpandTemplate("example.tpl", ctemplate::DO_NOT_STRIP,
&dict, &output);`.  These changes will make the code simpler and more
thread-safe.

Old code should continue to work -- the `Template` class remains --
but new code should use the new API, and old code should transition as
convenient.  One old API method is intrinsically thread-unsafe, and
should be prioritized to change: `tpl->ReloadIfChanged` should change
to `ctemplate::Template::ReloadAllIfChanged()`.  Note this is a
semantic change: all templates are now reloaded, rather than just one.
However, since templates are reloaded lazily, and only if they've
changed on disk, I'm hopeful it will always be a reasonable change to
make.

To go along with these changes, the documentation has been almost
entirely revamped and made more accessible.  Obscure ctemplate
features have been excised from the user's guide and moved into a
separate reference document.  The new API is fully documented,
including new flexibility around reloading templates, made available
by the introduction of `TemplateCache`.

There are some more minor changes as well, such as the addition of
#include guards in the auto-generated .tpl.h files, to make it safe to
multiply-include them.  I've also been continuing the portability
work: ctemplate should now work under Cygwin and MinGW.  A full list
of changes is available in the
[http://google-ctemplate.googlecode.com/svn/tags/ctemplate-0.97/ChangeLog
ChangeLog].

I know I've said this before, but I don't expect major API changes
before the 1.0 release.  The most significant changes I expect to see
are the potential removal of some of the 'forwarding' methods in the
(deprecated) `Template` class.

=== 12 June 2009 ===

I've just released ctemplate 0.95.  This is entirely an API cleanup
release.  Actually, relatively little of the API proper has changed:
`StringToTemplate` no longer takes an autoescape-context arg (instead
you specify this as part of the template-string, using the
`AUTOESCAPE` pragma).  A few obsolete constructs have gone away, such
as the `TemplateFromString` class and
`TemplateDictionary::html_escape` and friends (just use the top-level
`html_escape`).  See the
[http://google-ctemplate.googlecode.com/svn/tags/ctemplate-0.95/ChangeLog
ChangeLog] for a full list of these changes.

The biggest change is a renaming: the default namespace is now
`ctemplate` rather than `google`, and the include directory is
`ctemplate` rather than `google`.  Other namespaces, such as
`template_modifiers`, have gone away.

All these changes will require you to modify your old code to get it
working with ctemplate 0.95.  I've written a
[http://google-ctemplate.googlecode.com/svn/trunk/contrib/convert_to_95.pl
script] to help you do that.  Please open an
[http://code.google.com/p/google-ctemplate/issues/list issue] if you
see a problem with the script.  I've tested it, but not as widely as
I'd like.  Also note the script will not be perfect for more complex
constructs, which you will have to clean up by hand.

I hope (expect) the API is now stable, and we won't see any more such
changes before ctemplate 1.0.  I tried to isolate them all in this
release; except for the API changes, this release should behave
identically to ctemplate 0.94.

=== 7 May 2009 ===

I've just released ctemplate 0.94.  A few new features have been
added, such as the ability to expand a template into your own custom
`ExpandEmitter` instance, and the ability to hook the annotation
system (typically used for debugging).  You can now remove strings
from the template cache in addition to adding them.  Also, there
continues to be a trickle of new modifiers, in this case a modifier
for URL's in a CSS context.

However, the most invasive changes were made for speed reasons.  The
biggest is that (almost) all `TemplateDictionary` allocations are now
done on the arena -- this includes allocations by the STL classes
inside the dictionary.  This allows us to free all the memory at once,
rather than item by item, and has yielded a 3-4% speed improvement in
our tests.  I've combined this with a `small_map` class that stores
items in a vector instead of a hash-map until we get to 3 or 4 items;
this gives another speed increase in the (common) case a template has
only a few sections or includes.

I also changed the hashing code to use
[http://murmurhash.googlepages.com/ MurmurHash] everywhere, rather
than the string hash function built into the STL library.  This should
be faster.

All these changes should not be outwardly visible, but they do use
more advanced features of C++ than ctemplate has to date.  This may
result in some problems compiling, or conceivably when running.  If
you see any, please file an
[http://code.google.com/p/google-ctemplate/issues/list issue report].

You can see a full list of changes on the
[http://google-ctemplate.googlecode.com/svn/tags/ctemplate-0.94/ChangeLog
ChangeLog].

=== 20 August 2008 ===

ctemplate 0.91 introduces the beginning of some API changes, as I look
to clean up the API in preparation for ctemplate 1.0.  After 1.0, the
API will remain backwards compatible, but until that time, the API may
change.  Please take a look at the
[http://google-ctemplate.googlecode.com/svn/trunk/ChangeLog ChangeLog]
to see if any of these changes affect you.

One change is the introduction of a new `PerExpandData` class, which
holds some state that was formerly in the `TemplateDictionary` class.
I'm still not sure if this class is a good idea, if it should be
separate from `TemplateDictionary` or a member, or what functionality
should move there (for instance, should `SetTemplateGlobal` move
there, since template-global variables are really, in some sense,
per-expand variables?)  If you have any feedback, ideally based on
your own experience using the current API, feel free to post it at
`google-ctemplate@googlegroups.com`.

ctemplate also has several new features, including the addition of
"separator" sections, and the ability to change the markup character
(from `{{`).  See the
[http://google-ctemplate.googlecode.com/svn/trunk/ChangeLog ChangeLog]
for a complete list, and the
[http://google-ctemplate.googlecode.com/svn/trunk/doc/howto.html howto
documentation] for more details on these new features.