template.h

C++ web template engine

  // ExpandWithData
  //   If you want any per-expand data to be used at expand time, call
  //   this routine instead of Expand.  You pass in an extra PerExpandData
  //   structure (see per_expand_data.h) which sets this data:
  //   whether or not you want the template to be annotated, and any
  //   data you want to pass in to template modifers.  If per_expand_data
  //   is NULL, this is exactly the same as Expand().
  bool ExpandWithData(std::string *output_buffer,
                      const TemplateDictionaryInterface *dictionary,
                      const ctemplate::PerExpandData* per_expand_data) const;

  // Expand
  //   Expands the template into a string using the values
  //   in the supplied dictionary.  Returns true iff all the template
  //   files load and parse correctly.
  bool Expand(std::string *output_buffer,
              const TemplateDictionaryInterface *dictionary) const {
    return ExpandWithData(output_buffer, dictionary, NULL);
  }

  // Dump
  //   Dumps the parsed structure of the template for debugging assistance.
  //   It goes to stdout because it could be too big for LOG(INFO) and
  //   would end up truncated.
  void Dump(const char *filename) const;

  // DumpToString
  //   Same as Dump above except it dumps to the given string instead.
  //   Format is identical to Dump.
  void DumpToString(const char *filename, std::string *out) const;

  // state
  //   Retrieves the state of the template (see TemplateState above).
  TemplateState state() const;

  // template_file
  //   Returns the name of the template file used to build this template.
  const char *template_file() const;

  // ReloadIfChanged
  //   Reloads the file from the filesystem iff its mtime is different
  //   now from what it was last time the file was reloaded.  Note a
  //   file is always "reloaded" the first time this is called.  If
  //   the file is in fact reloaded, then the contents of the file are
  //   parsed into the template node parse tree by calling BuildTree
  //   After this call, the state of the Template will be either
  //   TS_READY or TS_ERROR.  Return value is true iff we reloaded
  //   because the content changed and could be parsed with no errors.
  bool ReloadIfChanged();

  // template_root_directory
  //   Returns the stored template root directory name
  static std::string template_root_directory();

  // WriteHeaderEntries
  void WriteHeaderEntries(std::string *outstring) const;

 protected:
  friend class SectionTemplateNode;  // for access to set_state(), ParseState
  friend class TemplateTemplateNode; // for recursive call to Expand()

  // Performs the actual work for both factory methods
  // GetTemplate and GetTemplateWithAutoEscaping.
  // See description of member variable selective_autoescape_ for
  // information on Selective Auto-Escape.
  static Template *GetTemplateCommon(const std::string& filename, Strip strip,
                                     TemplateContext context,
                                     bool selective_autoescape);

  // AssureGlobalsInitialized
  //   Initializes the global (static) variables the first time it is
  //   called. After that it simply checks one of the
  //   initialized pointers and finds it has already been called.
  static void AssureGlobalsInitialized();

  // Template constructor
  //   Reads the template file and parses it into a parse tree of TemplateNodes
  //   by calling the method ReloadIfChanged
  //   The top node is a section node with the arbitrary name "__{{MAIN}}__"
  //   '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.  It also removes
  //   any linefeed (possibly following whitespace) that follows a closing
  //   '}}' of any kind of template marker EXCEPT a template variable.
  //   This means a linefeed may be removed anywhere by simply placing
  //   a comment marker as the last element on the line.
  //   These two options allow the template to include whitespace for
  //   readability without adding to the expanded output.
  //   If context is not TC_MANUAL we enable auto-escaping
  //   for that template and any template it includes.
  Template(const std::string& filename, Strip strip, TemplateContext context,
           bool selective_autoescape);

  // MaybeInitHtmlParser
  //   In TemplateContexts where the HTML parser is needed, we initialize it
  //   in the appropriate mode. Also we do a sanity check (cannot fail) on the
  //   template filename. This function is called at most once for a Template.
  //   In_tag is only meaningful for TC_HTML: It is true for templates that
  //   start inside an HTML tag and hence are expected to contain HTML attribute
  //   name/value pairs only. It is false for standard HTML templates.
  void MaybeInitHtmlParser(bool in_tag);

  // BuildTree
  //   Parses the contents of the file (retrieved via ReloadIfChanged)
  //   and stores the resulting parse structure in tree_.  Returns true
  //   iff the tree-builder encountered no errors.  Note: takes
  //   ownership of input_buffer, and will delete it.  It should have
  //   been created via new[].
  bool BuildTree(const char *input_buffer, const char* input_buffer_end);

  // Internal version of Expand, used for recursive calls.
  bool Expand(class ExpandEmitter *expand_emitter,
              const TemplateDictionaryInterface *dictionary,
              const ctemplate::PerExpandData *per_expand_data) const;

  // Internal version of ReloadIfChanged, used when the function already
  // has a write-lock on mutex_.
  bool ReloadIfChangedLocked();

  // set_state
  //   Sets the state of the template.  Used during BuildTree().
  void set_state(TemplateState new_state);

  // StripBuffer
  //   Modifies buffer in-place based on the strip_ mode, to remove
  //   extra whitespace.  May delete[] the input buffer and replace
  //   it with a new buffer.  Used by ReloadIfChanged().
  void StripBuffer(char **buffer, size_t* len);

  // The file we read the template from
  const std::string filename_;
  time_t filename_mtime_;   // lastmod time for filename last time we loaded it

  // What to do with whitespace at template-expand time
  Strip strip_;

  // Keeps track of where we are in reloading, or if there was an error loading
  TemplateState state_;

  // The current template-contents, as read from the file
  const char* template_text_;
  int template_text_len_;

  // The current parsed template structure.  Has pointers into template_text_.
  class SectionTemplateNode *tree_;       // defined in template.cc

  // Template markers have the form {{VARIABLE}}, etc.  These constants
  // define the {{ and }} that delimit template markers.
  struct MarkerDelimiters {
    const char* start_marker;
    size_t start_marker_len;
    const char* end_marker;
    size_t end_marker_len;

    MarkerDelimiters() {
      start_marker = "{{";    // The default start-marker
      start_marker_len = strlen(start_marker);
      end_marker = "}}";
      end_marker_len = strlen(end_marker);
    }
  };

  // The current parsing state.  Used in BuildTree() and subroutines
  struct ParseState {
    const char* bufstart;
    const char* bufend;
    enum { PS_UNUSED, GETTING_TEXT, GETTING_NAME } phase;
    MarkerDelimiters current_delimiters;
    ParseState()
        : bufstart(NULL), bufend(NULL), phase(PS_UNUSED), current_delimiters()
    {}
  };
  ParseState parse_state_;

  // The mutex object used during ReloadIfChanged to prevent the same
  // object from reloading the template file in parallel by different
  // threads.
  mutable class Mutex* mutex_;

  // The root directory for all templates. Defaults to "./" until
  // SetTemplateRootDirectory changes it
  static std::string *template_root_directory_;

  // TC_MANUAL indicates the template is not in auto-escaping mode.
  // other values imply auto-escape mode is enabled.
  TemplateContext initial_context_;
  // Non-null if template was initialized in auto_escape mode.
  google_ctemplate_streamhtmlparser::HtmlParser *htmlparser_;

  // We now support two types of Auto-Escape:
  // 1. Full-on Auto-Escape where a template and all its included templates
  //    get auto-escaped. This is the case when the top-level template is
  //    obtained via GetTemplateWithAutoEscaping, or for string Templates
  //    via StringToTemplate with an auto-escape template context.
  // 2. Selective Auto-Escape where only templates which contain the AUTOESCAPE
  //    pragma {{%AUTOESCAPE ...}} are auto-escaped. The top-level template
  //    must be obtained via GetTemplate, or for string Templates, via
  //    StringToTemplate with TC_MANUAL template context.
  // In the first case, selective_autoescape_ is false, in the second case
  // it is true. Note: It is propagated as-is from parent to included template.
  const bool selective_autoescape_;

 private:
  // These are helper routines to StripFile.  I would make them static
  // inside template.cc, but they use the MarerDelimiters struct.
  static bool ParseDelimiters(const char* text, size_t textlen,
                              MarkerDelimiters* delim);
  static bool IsBlankOrOnlyHasOneRemovableMarker(const char** line, size_t* len,
                                                 const MarkerDelimiters& delim);
  static size_t InsertLine(const char *line, size_t len, Strip strip,
                           const MarkerDelimiters& delim, char* buffer);

  // Can't invoke copy constructor or assignment operator
  Template(const Template&);
  void operator=(const Template &);
};

}

#endif // CTEMPLATE_TEMPLATE_H_