From 8c338f322e178741bb4734bb92cb498d121a8171 Mon Sep 17 00:00:00 2001 From: csilvers Date: Fri, 18 Jun 2010 23:14:04 +0000 Subject: [PATCH] * Avoid "unused var" warning in opt mode (mec) * Use ascii_is*() to avoid langtype issues (csilvers) * Fix 'class not properly dll-exported' warnings (csilvers) * mv README.windows to windows-friendly README-windows.txt (csilvers) * Update README.windows to emphasize $IncludeDir a bit more (csilvers) * Add :I=html, :I=css image URL modifiers (jshneier) * Document the new image URL modifier (dougy) * Update NEWS file to be non-empty (csilvers) --- INSTALL | 35 +++++ Makefile.am | 2 +- Makefile.in | 2 +- NEWS | 146 +++++++++++++++++++ README.windows => README_windows.txt | 81 ++++++----- doc/auto_escape.html | 53 +++---- doc/guide.html | 4 +- doc/reference.html | 142 +++++++++++-------- packages/deb/control | 2 +- packages/rpm/rpm.spec | 2 +- src/ctemplate/per_expand_data.h.in | 16 +-- src/ctemplate/template.h.in | 4 +- src/ctemplate/template_modifiers.h.in | 19 ++- src/make_tpl_varnames_h.cc | 12 +- src/per_expand_data.cc | 19 +++ src/template.cc | 17 ++- src/template_modifiers.cc | 49 ++++++- src/tests/template_cache_test.cc | 2 + src/tests/template_modifiers_unittest.cc | 156 +++++++++++++++++++-- src/windows/ctemplate/per_expand_data.h | 16 +-- src/windows/ctemplate/template.h | 4 +- src/windows/ctemplate/template_cache.h | 5 + src/windows/ctemplate/template_modifiers.h | 19 ++- src/windows/preprocess.sh | 26 +++- 24 files changed, 648 insertions(+), 185 deletions(-) rename README.windows => README_windows.txt (85%) diff --git a/INSTALL b/INSTALL index 23e5f25..84d9d84 100644 --- a/INSTALL +++ b/INSTALL @@ -1,3 +1,38 @@ +Ctemplate-Specific Install Notes +================================ + +This code should work on any modern C++ system. It has been tested on +the following systems: + FreeBSD 6.0 + Linux Fedora Core 3 + Linux Fedora Core 4 + Linux Fedora Core 5 + Linux Fedora Core 6 + Linux RedHat 9 + Linux Ubuntu 6.06.1 + Mac OS X 10.3.9 (Panther) + Mac OS X 10.4.8 (Tiger) + Solaris 10 (x86) + Windows XP, Visual Studio 2003 (VC++7.1) + Windows XP, Visual Studio 2005 (VC++8) + +The only known problem is with Mac OS X 10.3.9 (Panther), which may +have problems with the export-symbols optimization this library does +to limit its exposed API. If you have problems compiling that seem to +involve nmedit, the solution is to edit the Makefile and remove all +instances of + -export-symbols-regex $(CTEMPLATE_TESTING_SYMBOLS) +Just remove that string exactly. After that, code should build. + +For Solaris 10 6/06, we have tested only with gcc (not the Sun +compiler). To get this to work, and to work around a bug in Solaris, +install as follows: + % PATH=${PATH}:/usr/sfw/bin/:/usr/ccs/bin ./configure LDFLAGS="-Lsrc/solaris -lrt" + % PATH=${PATH}:/usr/sfw/bin/:/usr/ccs/bin make + +See README.windows for installation instructions for Windows. + + Installation Instructions ************************* diff --git a/Makefile.am b/Makefile.am index 2007ddc..c90db09 100644 --- a/Makefile.am +++ b/Makefile.am @@ -48,7 +48,7 @@ docdir = $(prefix)/share/doc/$(PACKAGE)-$(VERSION) ## This is for HTML and other documentation you want to install. ## Add your documentation files (in doc/) in addition to these ## top-level boilerplate files. Also add a TODO file if you have one. -dist_doc_DATA = AUTHORS COPYING ChangeLog INSTALL NEWS README README.windows \ +dist_doc_DATA = AUTHORS COPYING ChangeLog INSTALL NEWS README README_windows.txt \ doc/designstyle.css doc/index.html \ doc/howto.html doc/tips.html doc/example.html doc/auto_escape.html \ doc/xss_resources.html diff --git a/Makefile.in b/Makefile.in index 371a75b..e6c5f7f 100644 --- a/Makefile.in +++ b/Makefile.in @@ -673,7 +673,7 @@ noinst_HEADERS = \ src/ctemplate/template_namelist.h.in \ src/ctemplate/per_expand_data.h.in -dist_doc_DATA = AUTHORS COPYING ChangeLog INSTALL NEWS README README.windows \ +dist_doc_DATA = AUTHORS COPYING ChangeLog INSTALL NEWS README README_windows.txt \ doc/designstyle.css doc/index.html \ doc/howto.html doc/tips.html doc/example.html doc/auto_escape.html \ doc/xss_resources.html diff --git a/NEWS b/NEWS index e69de29..c10ae04 100644 --- a/NEWS +++ b/NEWS @@ -0,0 +1,146 @@ +=== 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. diff --git a/README.windows b/README_windows.txt similarity index 85% rename from README.windows rename to README_windows.txt index 58f2950..c40acae 100644 --- a/README.windows +++ b/README_windows.txt @@ -1,38 +1,43 @@ -This project has been ported to Windows. A working solution file -exists in this directory: - google-ctemplate.sln - -You can load this solution file into either VC++ 7.1 (Visual Studio -2003) or VC++ 8.0 (Visual Studio 2005) -- in the latter case, it will -automatically convert the files to the latest format for you. - -When you build the solution, it will create libctemplate.dll, the main -library for this project, plus a number of unittests, which you can -run by hand (or, more easily, under the Visual Studio debugger) to -make sure everything is working properly on your system. The binaries -will end up in a directory called "debug" or "release" in the -top-level directory (next to the .sln file). - -If you wish to link to ctemplate statically instead of using the .dll, -you can; see the example project template_unittest_static. For this -to work, you'll need to add "/D CTEMPLATE_DLL_DECL=" to the compile -line of every ctemplate .cc file. - -Note that these systems are set to build in Debug mode by default. -You may want to change them to Release mode. - -Currently, Template::StringToTemplate returns a Template object that -you, the caller, must free. We've heard reports that Windows can have -trouble allocating memory in a .dll that is meant to be freed in the -application. Thus, we suggest you not use StringToTemplate from -Windows. Instead, you can use Template::StringToTemplateCache() -followed by Template::GetTemplate(). - -I have little experience with Windows programming, so there may be -better ways to set this up than I've done! If you run across any -problems, please post to the google-ctemplate Google Group, or report -them on the google-ctemplate Google Code site: - http://groups.google.com/group/google-ctemplate - http://code.google.com/p/google-ctemplate/issues/list - --- craig +This project has been ported to Windows. A working solution file +exists in this directory: + google-ctemplate.sln + +You can load this solution file into either VC++ 7.1 (Visual Studio +2003) or VC++ 8.0 (Visual Studio 2005) -- in the latter case, it will +automatically convert the files to the latest format for you. + +When you build the solution, it will create libctemplate.dll, the main +library for this project, plus a number of unittests, which you can +run by hand (or, more easily, under the Visual Studio debugger) to +make sure everything is working properly on your system. The binaries +will end up in a directory called "debug" or "release" in the +top-level directory (next to the .sln file). + +I don't know very much about how to install DLLs on Windows, so you'll +have to figure out that part for yourself. If you choose to just +re-use the existing .sln, make sure you set the IncludeDir's +appropriately! Look at the properties for libctemplate.dll. + +If you wish to link to ctemplate statically instead of using the .dll, +you can; see the example project template_unittest_static. For this +to work, you'll need to add "/D CTEMPLATE_DLL_DECL=" to the compile +line of every ctemplate .cc file. + +Note that these systems are set to build in Debug mode by default. +You may want to change them to Release mode. + +Currently, Template::StringToTemplate returns a Template object that +you, the caller, must free. We've heard reports that Windows can have +trouble allocating memory in a .dll that is meant to be freed in the +application. Thus, we suggest you not use StringToTemplate from +Windows. Instead, you can use Template::StringToTemplateCache() +followed by Template::GetTemplate(). + +I have little experience with Windows programming, so there may be +better ways to set this up than I've done! If you run across any +problems, please post to the google-ctemplate Google Group, or report +them on the google-ctemplate Google Code site: + http://groups.google.com/group/google-ctemplate + http://code.google.com/p/google-ctemplate/issues/list + +-- craig diff --git a/doc/auto_escape.html b/doc/auto_escape.html index 299bc59..ee9f74f 100644 --- a/doc/auto_escape.html +++ b/doc/auto_escape.html @@ -94,12 +94,12 @@ the appropriate escaping modifiers after your own.

that use but allows you to indicate a different choice as shown below: -

+
- + @@ -116,6 +117,7 @@ the appropriate escaping modifiers after your own.

@@ -125,7 +127,7 @@ the appropriate escaping modifiers after your own.

+ @@ -133,10 +135,10 @@ the appropriate escaping modifiers after your own.

+ -
TemplateContextPrimary Modifier Accepted alternatives
TC_HTMLTC_HTML :html_escape
  • :pre_escape
    • @@ -108,6 +108,7 @@ the appropriate escaping modifiers after your own.

  • :html_escape_with_arg=url
  • :url_query_escape
  • :url_escape_with_arg=html
    • +
  • :img_src_url_escape_with_arg=html
:cleanse_css
  • :url_escape_with_arg=css
    • +
  • :img_src_url_escape_with_arg=css
  • :html_escape
  • :html_escape_with_arg=attribute
    • -
:javascript_escape
  • :json_escape
    • -

+
  • To add additional escaping modifiers. The Template System will never remove escaping directives you explicitly specify.
    • @@ -159,13 +161,13 @@ the semantics of the variable therefore we fail the template initialization. An error is logged indicating the cause of the failure.

    - - +
    + - + @@ -173,95 +175,95 @@ the failure.

    :html_escape - + - + - + - + - + - + - + - + - + - + - + - + - + - + - +
    ContextHTML Quoted? ExamplesAction Performed
    Regular HTML Body and HTML commentsAny 
    <p>Hello {{USER}}</p>
    In URL attribute: Starts at pos 0Yes
    <img src="{{URL}}">;
    <a href="{{URL}}">;
    		 Escape URL using :url_escape_with_arg=html
    In URL attribute: OtherYes 
    <a href="/foo?q={{QUERY}}">
    		 Escape QUERY using :html_escape
    In URL attribute: Starting at pos 0No 
    <form action={{URL}}>
    		 Fail template initialization
    In URL attribute: OtherNo 
    <a href=/foo?q={{QUERY}}>My Link</a>
    		 Escape QUERY using :url_query_escape
    In STYLE attributeYes 
    <div style="color:{{COLOR}};">
    		 Escape COLOR using :cleanse_css
    In STYLE attributeNo 
    <div style=color:{{COLOR}};>
    		 Fail template initialization
    In Javascript attribute: String literalYes 
    <a href="url" onclick="doFoo('{{ARG}}');">
    		 Escape ARG using :javascript_escape
    In Javascript attribute: Non-string literalYes 
    <a href="url" onclick="doFoo({{ARG}});">
    		 Escape ARG using :javascript_escape_with_arg=number
    In Javascript attribute: AnyNo 
    <a href="url" onclick=doFoo('{{ARG}}');>
    		 Fail template initialization.
    In all other attributesYes 
    <b class="{{CLASS}}">
    		 Escape CLASS using :html_escape
    In all other attributesNo 
    <table border={{BORDER}}>
    		 Escape BORDER using :html_escape_with_arg=attribute
    In Javascript code: In a string literalAny 
    <script>var a = '{{VALUE}}';</script>
    		 Escape VALUE using :javascript_escape
    In Javascript code: Non-string literalAny 
    <script>var a = {{VALUE}};</script>
    		 Escape VALUE using :javascript_escape_with_arg=number
    In a <style> tagAny 
    <style>font-size={{FONTSIZE}};</style>
    		 Escape FONTSIZE using @@ -270,7 +272,7 @@ the failure.

    -

    Comments:

    +

    Comments: