template.h

C++ web template engine

// Copyright (c) 2006, Google Inc.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//     * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//     * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

// ---
// Author: Frank H. Jernigan
//
// This file implements the Template class.  For information about
// how to use this class, and to write the templates it takes as input,
// see doc/howto.html

#ifndef CTEMPLATE_TEMPLATE_H_
#define CTEMPLATE_TEMPLATE_H_

#include <time.h>             // for time_t
#include <string>
#include <google/template_enums.h>

// We include this just so folks don't have to include both template.h
// and template_dictionary.h, or template_namelist.h etc, to use the
// template system; we don't actually use anything in these files ourselves.
#if 1
#include <google/template_dictionary.h>
#include <google/template_namelist.h>
#include <google/per_expand_data.h>
#else
namespace google {
class TemplateDictionaryInterface;
class PerExpandData;
}
#endif

// NOTE: if you are statically linking the template library into your binary
// (rather than using the template .dll), set '/D CTEMPLATE_DLL_DECL='
// as a compiler flag in your project file to turn off the dllimports.
#ifndef CTEMPLATE_DLL_DECL
# define CTEMPLATE_DLL_DECL  __declspec(dllimport)
#endif

namespace google_ctemplate_streamhtmlparser {
class HtmlParser;
}

namespace google {

// TemplateState of a template is:
// - TS_EMPTY before parsing is complete,
// - TS_ERROR if a syntax error was found during parsing, and
// - TS_READY if parsing has completed successfully
// - TS_SHOULD_RELOAD if marked to reload next time it is called for
// (TS_UNUSED is not used)
enum TemplateState { TS_UNUSED, TS_EMPTY, TS_ERROR, TS_READY, TS_SHOULD_RELOAD };

// To use the auto-escape mode you will need to provide the context (a.k.a type)
// of the template in GetTemplate. We provide:
// - TC_HTML:   The template contains HTML code. Need not be a complete HTML
//              page just content the browser interprets in the context of
//              HTML parsing. This should be the most common context to use.
//              This mode activates our HTML parser.
// - TC_JS:     The template contains raw javascript. If your template
//              starts with <script> tag, it is of type TC_HTML not TC_JS.
//              TC_JS is typically associated with a content-type of
//              text/javascript. This mode activates our HTML parser.
// - TC_CSS:    The template contains CSS (cascaded style-sheet). If your
//              template starts with a <style> tag, it is of type TC_HTML
//              not TC_CSS. A TC_CSS template is typically associated with a
//              text/css content-type header. Currently treated same as
//              TC_HTML but don't rely on that. We may later develop
//              CSS-specific sanitizers and parsers.
// - TC_JSON:   The template contains raw JSON. Applies javascript_escape
//              to variables. Note: javascript_escape is safer than
//              json_escape which we may want to remove.
// - TC_XML:    The template contains raw XML. Applies xml_escape to variables.
//              CAUTION: This mode is not suitable for cases where the
//              application data encapsulated in XML requires special
//              escaping, such as the case of XHTML.
//              TC_XML is typically associated with text/xml content-type.
// - TC_NONE:   Don't use, Internal use only to support passivating the
//              HTML-aware parsing and auto-escaping when template-includes
//              specify modifiers.
// - TC_MANUAL: Equivalent to not specifying auto-escaping at all.
//              That is, GetTemplateWithAutoEscaping(..., TC_MANUAL) is
//              equivalent to GetTemplate(...).
//
// TODO(jad): Move declaration to inside Template class.
enum TemplateContext { TC_UNUSED, TC_HTML, TC_JS, TC_CSS, TC_JSON,
                       TC_XML, TC_NONE, TC_MANUAL };

// Template
//   The object which reads and parses the template file and then is used to
//   expand the parsed structure to a string.
class CTEMPLATE_DLL_DECL Template {
 public:
  // GetTemplate (static Template factory method)
  //   Attempts to retrieve the template object from the cache, stored
  //   under its filename. This will fail only the first time the method
  //   is invoked for a given filename.
  //   Any object retrieved from the cache is then checked to see if
  //   its status is marked for "reload if changed." If so, ReloadIfChanged
  //   is called on the retrieved object. Then the retrieved object is
  //   returned.
  //   When it fails to retrieve one from the cache, it creates a new
  //   template object, passing the filename and 'strip' values to the
  //   constructor. (See constructor below for the meaning of the flags.)
  //   If it succeeds in creating an object, including loading and parsing
  //   the associated template file, the object is stored in the cache
  //   and then returned.
  //   If it fails in loading and parsing the template file, either
  //   because the file was not found or it contained syntax errors, then
  //   the newly created object is deleted and the method returns NULL.
  //   (NOTE: This description is much longer and less precise and probably
  //   harder to understand than the method itself. Read the code.)
  //
  //   'Strip' indicates how to handle whitespace when expanding the
  //   template.  DO_NOT_STRIP keeps the template exactly as-is.
  //   STRIP_BLANK_LINES elides all blank lines in the template.
  //   STRIP_WHITESPACE elides all blank lines, and also all whitespace
  //   at either the beginning or end of a line.  See template constructor
  //   for more details.
  static Template *GetTemplate(const std::string& filename, Strip strip);

  // GetTemplateWithAutoEscaping (static Template factory method)
  //   Same logic as GetTemplate above except it also enables
  //   auto-escaping for that template and for all templates it may
  //   include. The auto-escaping mode is not for everyone, in particular
  //   it is only useful when you are using the Template System in the
  //   context of web-applications which operate on untrusted
  //   content that requires proper escaping when expanded into the template.
  //   In order to automatically determine the correct escaping to apply
  //   to all variable substitutions, the Template System becomes
  //   "HTML-aware" and parses the template during initial creation.
  //
  //   TemplateContext must match the context in which the template
  //   is being returned or the auto-escaping will be wrong.
  static Template *GetTemplateWithAutoEscaping(const std::string& filename,
                                               Strip strip,
                                               TemplateContext context);

  // Template destructor
  virtual ~Template();

  // SetTemplateRootDirectory
  //   Sets the root directory for all templates used by the program.
  //   After calling this method, the filename passed to GetTemplate
  //   may be a relative pathname (no leading '/'), in which case
  //   this root-directory is prepended to the filename.
  static bool SetTemplateRootDirectory(const std::string& directory);

  // Parses the string as a template file (e.g. "Hello {{WORLD}}"),
  // and returns the generated Template object, or NULL on parse
  // error.  It is the caller's responsibility to free the template
  // when done.  NOTE: since there is no 'key' associated with these
  // templates, you cannot use include them inside another template
  // (via "{{>TEMPLATE_THAT_COMES_FROM_A_STRING}}").  If you need that
  // functionality, use StringToTemplateCache.
  static Template* StringToTemplate(const char* content, size_t content_len,
                                    Strip strip, TemplateContext context);
  static Template* StringToTemplate(const std::string& content,
                                    Strip strip, TemplateContext context) {
    return StringToTemplate(content.data(), content.length(), strip, context);
  }

  // Parses the string as a template file (e.g. "Hello {{WORLD}}"),
  // and inserts it into the template cache, so it can later be
  // retrieved by GetTemplate.  The user specifies a key, which is
  // passed in to GetTemplate.  (Note the user does not specify strip
  // or context; those will be specified later in the GetTemplate
  // call.)  The template system will manage memory for this template.
  // Returns true if the template was successfully parsed and
  // submitted to the template cache, or false otherwise.  In particular,
  // we return false if a string was already cached with the given key.
  // NOTE: to include this template from within another template (via
  // "{{>TEMPLATE_THAT_COMES_FROM_A_STRING}}"), the argument you pass
  // to TemplateDictionary::SetFilename() is the key you used to register
  // the string-template.
  static bool StringToTemplateCache(const std::string& key,
                                    const char* content, size_t content_len);
  static bool StringToTemplateCache(const std::string& key, const std::string& content) {
    return StringToTemplateCache(key, content.data(), content.length());
  }

  // ReloadAllIfChanged
  //   Marks each template object in the cache to check to see if
  //   its template file has changed the next time it is invoked
  //   via GetTemplate. If it finds the file has changed, it
  //   then reloads and parses the file before being returned by
  //   GetTemplate.
  static void ReloadAllIfChanged();

  // ClearCache
  //   Deletes all the template objects in the cache and all raw
  //   contents cached from StringToTemplateCache. This should only
  //   be done once, just before exiting the program and after all
  //   template expansions are completed. (If you want to refresh the
  //   cache, the correct method to use is ReloadAllIfChanged, not
  //   this one.) Note: this method is not necessary unless you are
  //   testing for memory leaks. Calling this before exiting the
  //   program will prevent unnecessary reporting in that case.
  static void ClearCache();