blob: 29c703a601caa8fdc3486174eded6a2c02d2e39c [file] [log] [blame]
Brian Silverman70325d62015-09-20 17:00:43 -04001// Copyright (c) 2009, Google Inc.
2// All rights reserved.
3//
4// Redistribution and use in source and binary forms, with or without
5// modification, are permitted provided that the following conditions are
6// met:
7//
8// * Redistributions of source code must retain the above copyright
9// notice, this list of conditions and the following disclaimer.
10// * Redistributions in binary form must reproduce the above
11// copyright notice, this list of conditions and the following disclaimer
12// in the documentation and/or other materials provided with the
13// distribution.
14// * Neither the name of Google Inc. nor the names of its
15// contributors may be used to endorse or promote products derived from
16// this software without specific prior written permission.
17//
18// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29
30// ---
31//
32// The template expansion system provides a set of hooks that allow for
33// the insertion of diagnostic content into the output stream for the use
34// by content developers and testers. For instance, the default text
35// annotation mode inserts strings bracketed by {{ }} to describe every
36// occurrence of a dynamic substitution feature. That mode turns the
37// rendering into a logical text description of the construction of
38// template-based output. It is useful for regression testing of output
39// in conjunction with text-based diffing tools.
40//
41// An annotation mode is implemented with the TemplateAnnotator interface.
42// When template annotation is turned on, then during template expansion
43// whenever a dynamic substitution feature is encountered, a call is made
44// to one of the TemplateAnnotator functions. In response to a call
45// an implementation can render any additional content into the passed
46// emitter, which is the same emitter that the rendering output is going
47// to.
48//
49// Template annotation is turned on and the template annotator subclass
50// set by methods in @ac_google_namespace@::PerExpandData.
51
52#ifndef TEMPLATE_TEMPLATE_ANNOTATOR_H_
53#define TEMPLATE_TEMPLATE_ANNOTATOR_H_
54
55#include <string>
56
57@ac_windows_dllexport_defines@
58
59namespace ctemplate {
60
61class ExpandEmitter;
62
63// This is the abstract interface for an annotation mode. A new annotation
64// mode is introduced by subclassing and implementing each function
65// to add annotation content. There is one function for each internal
66// template expansion event type. The emitter argument passed to the
67// function is the same stream that the expanding content is being output to;
68// so the action of an implementation will be to add additional inline
69// content. The emitter argument is never to be remembered beyond each
70// function call.
71class @ac_windows_dllexport@ TemplateAnnotator {
72 public:
73 TemplateAnnotator() { }
74 virtual ~TemplateAnnotator() { }
75
76 // Called before processing a subtemplate include marker.
77 // Passed value is the include marker name.
78 virtual void EmitOpenInclude(ExpandEmitter* emitter, const std::string& value) = 0;
79 // Called after processing a subtemplate include marker.
80 virtual void EmitCloseInclude(ExpandEmitter* emitter) = 0;
81
82 // Called before opening a template or subtemplate file for processing.
83 // Passed value is the filename.
84 virtual void EmitOpenFile(ExpandEmitter* emitter, const std::string& value) = 0;
85 // Called after processing a template or subtemplate file.
86 virtual void EmitCloseFile(ExpandEmitter* emitter) = 0;
87
88 // Called before processing a section.
89 // Passed value is the section name.
90 virtual void EmitOpenSection(ExpandEmitter* emitter, const std::string& value) = 0;
91 // Called after processing a section.
92 virtual void EmitCloseSection(ExpandEmitter* emitter) = 0;
93
94 // Called before processing a variable marker.
95 // Passed value is the variable name.
96 virtual void EmitOpenVariable(ExpandEmitter* emitter,
97 const std::string& value) = 0;
98 // Called after processing a variable marker.
99 virtual void EmitCloseVariable(ExpandEmitter* emitter) = 0;
100
101 virtual void EmitFileIsMissing(ExpandEmitter* emitter,
102 const std::string& value) = 0;
103
104 private:
105 // Can't invoke copy constructor or assignment operator
106 TemplateAnnotator(const TemplateAnnotator&);
107 void operator=(const TemplateAnnotator&);
108};
109
110// This is a concrete template annotator class that inserts annotations
111// that have a standard text form bracketed by {{ }}. It is used as
112// the default annotation implementation when annotation is turned on
113// by PerExpandData and no annotator type is specified.
114class @ac_windows_dllexport@ TextTemplateAnnotator : public TemplateAnnotator {
115 public:
116 TextTemplateAnnotator() { }
117 virtual void EmitOpenInclude(ExpandEmitter* emitter, const std::string& value);
118 virtual void EmitCloseInclude(ExpandEmitter* emitter);
119 virtual void EmitOpenFile(ExpandEmitter* emitter, const std::string& value);
120 virtual void EmitCloseFile(ExpandEmitter* emitter);
121 virtual void EmitOpenSection(ExpandEmitter* emitter, const std::string& value);
122 virtual void EmitCloseSection(ExpandEmitter* emitter);
123 virtual void EmitOpenVariable(ExpandEmitter* emitter, const std::string& value);
124 virtual void EmitCloseVariable(ExpandEmitter* emitter);
125 virtual void EmitFileIsMissing(ExpandEmitter* emitter,
126 const std::string& value);
127
128 private:
129 // Can't invoke copy constructor or assignment operator
130 TextTemplateAnnotator(const TextTemplateAnnotator&);
131 void operator=(const TextTemplateAnnotator&);
132};
133
134}
135
136#endif // TEMPLATE_TEMPLATE_ANNOTATOR_H_