/usr/include/ctemplate/template_dictionary.h is in libctemplate-dev 2.2-4ubuntu3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 | // 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: csilvers@google.com (Craig Silverstein)
//
// Based on the 'old' TemplateDictionary by Frank Jernigan.
//
// A template dictionary maps names (as found in template files)
// to their values. There are three types of names:
// variables: value is a string.
// sections: value is a list of sub-dicts to use when expanding the section;
// the section is expanded once per sub-dict.
// template-include: value is a list of pairs: name of the template file
// to include, and the sub-dict to use when expanding it.
// TemplateDictionary has routines for setting these values.
//
// For (many) more details, see the doc/ directory.
#ifndef TEMPLATE_TEMPLATE_DICTIONARY_H_
#define TEMPLATE_TEMPLATE_DICTIONARY_H_
#include <stdarg.h> // for StringAppendV()
#include <stddef.h> // for size_t and ptrdiff_t
#include <stdlib.h> // for NULL
#include <sys/types.h>
#include <functional> // for less<>
#include <cstddef>
#include <map>
#include <string>
#include <vector>
#include <ctemplate/str_ref.h>
#include <ctemplate/template_dictionary_interface.h>
#include <ctemplate/template_modifiers.h>
#include <ctemplate/template_string.h>
namespace ctemplate {
template <class T, class C> class ArenaAllocator;
class UnsafeArena;
template<typename A, int B, typename C, typename D> class small_map;
template<typename NormalMap> class small_map_default_init; // in small_map.h
}
namespace ctemplate {
class TemplateDictionary : public TemplateDictionaryInterface {
public:
// name is used only for debugging.
// arena is used to store all names and values. It can be NULL (the
// default), in which case we create own own arena.
explicit TemplateDictionary(const TemplateString& name,
UnsafeArena* arena=NULL);
~TemplateDictionary();
// If you want to be explicit, you can use NO_ARENA as a synonym to NULL.
static UnsafeArena* const NO_ARENA;
std::string name() const {
return std::string(name_.data(), name_.size());
}
// Returns a recursive copy of this dictionary. This dictionary
// *must* be a "top-level" dictionary (that is, not created via
// AddSectionDictionary() or AddIncludeDictionary()). Caller owns
// the resulting dict, and must delete it. If arena is NULL, we
// create our own. Returns NULL if the copy fails (probably because
// the "top-level" rule was violated).
TemplateDictionary* MakeCopy(const TemplateString& name_of_copy,
UnsafeArena* arena=NULL);
// --- Routines for VARIABLES
// These are the five main routines used to set the value of a variable.
// As always, wherever you see TemplateString, you can also pass in
// either a char* or a C++ string, or a TemplateString(s, slen).
void SetValue(const TemplateString variable, const TemplateString value);
void SetIntValue(const TemplateString variable, long value);
void SetFormattedValue(const TemplateString variable, const char* format, ...)
#if 1
__attribute__((__format__ (__printf__, 3, 4)))
#endif
; // starts at 3 because of implicit 1st arg 'this'
class SetProxy {
public:
SetProxy(TemplateDictionary& dict, const TemplateString& variable) :
dict_(dict),
variable_(variable) {
}
void operator=(str_ref value) {
dict_.SetValue(variable_, TemplateString(value.data(), value.size()));
}
void operator=(long value) {
dict_.SetIntValue(variable_, value);
}
private:
TemplateDictionary& dict_;
const TemplateString& variable_;
};
SetProxy operator[](const TemplateString& variable) {
return SetProxy(*this, variable);
}
// We also let you set values in the 'global' dictionary which is
// referenced when all other dictionaries fail. Note this is a
// static method: no TemplateDictionary instance needed. Since
// this routine is rarely used, we don't provide variants.
static void SetGlobalValue(const TemplateString variable,
const TemplateString value);
// This is used for a value that you want to be 'global', but only
// in the scope of a given template, including all its sections and
// all its sub-included dictionaries. The main difference between
// SetTemplateGlobalValue() and SetValue(), is that
// SetTemplateGlobalValue() values persist across template-includes.
// This is intended for session-global data; since that should be
// fairly rare, we don't provide variants.
void SetTemplateGlobalValue(const TemplateString variable,
const TemplateString value);
// Similar SetTemplateGlobalValue above, this method shows a section in this
// template, all its sections, and all its template-includes. This is intended
// for session-global data, for example allowing you to show variant portions
// of your template for certain browsers/languages without having to call
// ShowSection on each template you use.
void ShowTemplateGlobalSection(const TemplateString variable);
// These routines are like SetValue and SetTemplateGlobalValue, but
// they do not make a copy of the input data. THE CALLER IS
// RESPONSIBLE FOR ENSURING THE PASSED-IN STRINGS LIVE FOR AT LEAST
// AS LONG AS THIS DICTIONARY! In general, they yield a quite minor
// performance increase for significant increased code fragility,
// so do not use them unless you really need the speed improvements.
void SetValueWithoutCopy(const TemplateString variable,
const TemplateString value);
void SetTemplateGlobalValueWithoutCopy(const TemplateString variable,
const TemplateString value);
// --- Routines for SECTIONS
// We show a section once per dictionary that is added with its name.
// Recall that lookups are hierarchical: if a section tried to look
// up a variable in its sub-dictionary and fails, it will look next
// in its parent dictionary (us). So it's perfectly appropriate to
// keep the sub-dictionary empty: that will show the section once,
// and take all var definitions from us. ShowSection() is a
// convenience routine that does exactly that.
// Creates an empty dictionary whose parent is us, and returns it.
// As always, wherever you see TemplateString, you can also pass in
// either a char* or a C++ string, or a TemplateString(s, slen).
TemplateDictionary* AddSectionDictionary(const TemplateString section_name);
void ShowSection(const TemplateString section_name);
// A convenience method. Often a single variable is surrounded by
// some HTML that should not be printed if the variable has no
// value. The way to do this is to put that html in a section.
// This method makes it so the section is shown exactly once, with a
// dictionary that maps the variable to the proper value. If the
// value is "", on the other hand, this method does nothing, so the
// section remains hidden.
void SetValueAndShowSection(const TemplateString variable,
const TemplateString value,
const TemplateString section_name);
// --- Routines for TEMPLATE-INCLUDES
// Included templates are treated like sections, but they require
// the name of the include-file to go along with each dictionary.
TemplateDictionary* AddIncludeDictionary(const TemplateString variable);
// This is required for include-templates; it specifies what template
// to include. But feel free to call this on any dictionary, to
// document what template-file the dictionary is intended to go with.
void SetFilename(const TemplateString filename);
// --- DEBUGGING TOOLS
// Logs the contents of a dictionary and its sub-dictionaries.
// Dump goes to stdout/stderr, while DumpToString goes to the given string.
// 'indent' is how much to indent each line of the output.
void Dump(int indent=0) const;
virtual void DumpToString(std::string* out, int indent=0) const;
// --- DEPRECATED ESCAPING FUNCTIONALITY
// Escaping in the binary has been deprecated in favor of using modifiers
// to do the escaping in the template:
// "...{{MYVAR:html_escape}}..."
void SetEscapedValue(const TemplateString variable, const TemplateString value,
const TemplateModifier& escfn);
void SetEscapedFormattedValue(const TemplateString variable,
const TemplateModifier& escfn,
const char* format, ...)
#if 1
__attribute__((__format__ (__printf__, 4, 5)))
#endif
; // starts at 4 because of implicit 1st arg 'this'
void SetEscapedValueAndShowSection(const TemplateString variable,
const TemplateString value,
const TemplateModifier& escfn,
const TemplateString section_name);
private:
friend class SectionTemplateNode; // for access to GetSectionValue(), etc.
friend class TemplateTemplateNode; // for access to GetSectionValue(), etc.
friend class VariableTemplateNode; // for access to GetSectionValue(), etc.
// For unittesting code using a TemplateDictionary.
friend class TemplateDictionaryPeer;
class DictionaryPrinter; // nested class
friend class DictionaryPrinter;
// We need this functor to tell small_map how to create a map<> when
// it decides to do so: we want it to create that map on the arena.
class map_arena_init;
typedef std::vector<TemplateDictionary*,
ArenaAllocator<TemplateDictionary*, UnsafeArena> >
DictVector;
// The '4' here is the size where small_map switches from vector<> to map<>.
typedef small_map<std::map<TemplateId, TemplateString, std::less<TemplateId>,
ArenaAllocator<std::pair<const TemplateId, TemplateString>,
UnsafeArena> >,
4, std::equal_to<TemplateId>, map_arena_init>
VariableDict;
typedef small_map<std::map<TemplateId, DictVector*, std::less<TemplateId>,
ArenaAllocator<std::pair<const TemplateId, DictVector*>,
UnsafeArena> >,
4, std::equal_to<TemplateId>, map_arena_init>
SectionDict;
typedef small_map<std::map<TemplateId, DictVector*, std::less<TemplateId>,
ArenaAllocator<std::pair<const TemplateId, DictVector*>,
UnsafeArena> >,
4, std::equal_to<TemplateId>, map_arena_init>
IncludeDict;
// This is used only for global_dict_, which is just like a VariableDict
// but does not bother with an arena (since this memory lives forever).
typedef small_map<std::map<TemplateId, TemplateString, std::less<TemplateId> >,
4, std::equal_to<TemplateId>,
small_map_default_init<
std::map<TemplateId, TemplateString,
std::less<TemplateId> > > >
GlobalDict;
// These are helper functions to allocate the parts of the dictionary
// on the arena.
template<typename T> inline void LazilyCreateDict(T** dict);
inline void LazyCreateTemplateGlobalDict();
inline DictVector* CreateDictVector();
inline TemplateDictionary* CreateTemplateSubdict(
const TemplateString& name,
UnsafeArena* arena,
TemplateDictionary* parent_dict,
TemplateDictionary* template_global_dict_owner);
// This is a helper function to insert <key,value> into m.
// Normally, we'd just use m[key] = value, but map rules
// require default constructor to be public for that to compile, and
// for some types we'd rather not allow that. HashInsert also inserts
// the key into an id(key)->key map, to allow for id-lookups later.
template<typename MapType, typename ValueType>
static void HashInsert(MapType* m, TemplateString key, ValueType value);
// Constructor created for all children dictionaries. This includes
// both a pointer to the parent dictionary and also the the
// template-global dictionary from which all children (both
// IncludeDictionary and SectionDictionary) inherit. Values are
// filled into global_template_dict via SetTemplateGlobalValue.
explicit TemplateDictionary(const TemplateString& name,
class UnsafeArena* arena,
TemplateDictionary* parent_dict,
TemplateDictionary* template_global_dict_owner);
// Helps set up the static stuff. Must be called exactly once before
// accessing global_dict_. GoogleOnceInit() is used to manage that
// initialization in a thread-safe way.
static void SetupGlobalDict();
// Utility functions for copying a string into the arena.
// Memdup also copies in a trailing NUL, which is why we have the
// trailing-NUL check in the TemplateString version of Memdup.
TemplateString Memdup(const char* s, size_t slen);
TemplateString Memdup(const TemplateString& s) {
if (s.is_immutable() && s.data()[s.size()] == '\0') {
return s;
}
return Memdup(s.data(), s.size());
}
// Used for recursive MakeCopy calls.
TemplateDictionary* InternalMakeCopy(
const TemplateString& name_of_copy,
UnsafeArena* arena,
TemplateDictionary* parent_dict,
TemplateDictionary* template_global_dict_owner);
// A helper for creating section and include dicts.
static std::string CreateSubdictName(
const TemplateString& dict_name, const TemplateString& sub_name,
size_t index, const char* suffix);
// Must be called whenever we add a value to one of the dictionaries above,
// to ensure that we can reconstruct the id -> string mapping.
static void AddToIdToNameMap(TemplateId id, const TemplateString& str);
// Used to do the formatting for the SetFormatted*() functions
static int StringAppendV(char* space, char** out,
const char* format, va_list ap);
// How Template::Expand() and its children access the template-dictionary.
// These fill the API required by TemplateDictionaryInterface.
virtual TemplateString GetValue(const TemplateString& variable) const;
virtual bool IsHiddenSection(const TemplateString& name) const;
virtual bool IsUnhiddenSection(const TemplateString& name) const {
return !IsHiddenSection(name);
}
virtual bool IsHiddenTemplate(const TemplateString& name) const;
virtual const char* GetIncludeTemplateName(
const TemplateString& variable, int dictnum) const;
// Determine whether there's anything set in this dictionary
bool Empty() const;
// This is needed by DictionaryPrinter because it's not a friend
// of TemplateString, but we are
static std::string PrintableTemplateString(
const TemplateString& ts) {
return std::string(ts.data(), ts.size());
}
static bool InvalidTemplateString(const TemplateString& ts) {
return ts.data() == NULL;
}
// Compilers differ about whether nested classes inherit our friendship.
// The only thing DictionaryPrinter needs is IdToString, so just re-export.
static TemplateString IdToString(TemplateId id) { // for DictionaryPrinter
return TemplateString::IdToString(id);
}
// CreateTemplateIterator
// This is SectionIterator exactly, just with a different name to
// self-document the fact the value applies to a template include.
// Caller frees return value.
virtual TemplateDictionaryInterface::Iterator* CreateTemplateIterator(
const TemplateString& section_name) const;
// CreateSectionIterator
// Factory method implementation that constructs a iterator representing the
// set of dictionaries associated with a section name, if any. This
// implementation checks the local dictionary itself, not the template-wide
// dictionary or the global dictionary.
// Caller frees return value.
virtual TemplateDictionaryInterface::Iterator* CreateSectionIterator(
const TemplateString& section_name) const;
// TemplateDictionary-specific implementation of dictionary iterators.
template <typename T> // T is *TemplateDictionary::const_iterator
class Iterator : public TemplateDictionaryInterface::Iterator {
protected:
friend class TemplateDictionary;
Iterator(T begin, T end) : begin_(begin), end_(end) { }
public:
virtual ~Iterator() { }
virtual bool HasNext() const;
virtual const TemplateDictionaryInterface& Next();
private:
T begin_;
const T end_;
};
// A small helper factory function for Iterator
template <typename T>
static Iterator<typename T::const_iterator>* MakeIterator(const T& dv) {
return new Iterator<typename T::const_iterator>(dv.begin(), dv.end());
}
// The "name" of the dictionary for debugging output (Dump, etc.)
// The arena, also set at construction time.
class UnsafeArena* const arena_;
bool should_delete_arena_; // only true if we 'new arena' in constructor
TemplateString name_; // points into the arena, or to static memory
// The three dictionaries that I own -- for vars, sections, and template-incs
VariableDict* variable_dict_;
SectionDict* section_dict_;
IncludeDict* include_dict_;
// The template_global_dict is consulted if a lookup in the variable, section,
// or include dicts named above fails. It forms a convenient place to store
// session-specific data that's applicable to all templates in the dictionary
// tree.
// For the parent-template, template_global_dict_ is not NULL, and
// template_global_dict_owner_ is this. For all of its children,
// template_global_dict_ is NULL, and template_global_dict_owner_ points to
// the root parent-template (the one with the non-NULL template_global_dict_).
TemplateDictionary* template_global_dict_;
TemplateDictionary* template_global_dict_owner_;
// My parent dictionary, used when variable lookups at this level fail.
// Note this is only for *variables* and *sections*, not templates.
TemplateDictionary* parent_dict_;
// The static, global dictionary, at the top of the parent-dictionary chain
static GlobalDict* global_dict_;
static TemplateString* empty_string_; // what is returned on lookup misses
// The filename associated with this dictionary. If set, this declares
// what template the dictionary is supposed to be expanded with. Required
// for template-includes, optional (but useful) for 'normal' dicts.
const char* filename_;
private:
// Can't invoke copy constructor or assignment operator
TemplateDictionary(const TemplateDictionary&);
void operator=(const TemplateDictionary&);
};
}
#endif // TEMPLATE_TEMPLATE_DICTIONARY_H_
|