1// Copyright 2012 The Kyua Authors. 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 copyright 11// notice, this list of conditions and the following disclaimer in the 12// documentation and/or other materials provided with the distribution. 13// * Neither the name of Google Inc. nor the names of its contributors 14// may be used to endorse or promote products derived from this software 15// without specific prior written permission. 16// 17// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 20// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 21// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 22// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 23// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 27// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 29/// \file utils/text/templates.hpp 30/// Custom templating engine for text documents. 31/// 32/// This module provides a simple mechanism to generate text documents based on 33/// templates. The templates are just text files that contain template 34/// statements that instruct this processor to perform transformations on the 35/// input. 36/// 37/// While this was originally written to handle HTML templates, it is actually 38/// generic enough to handle any kind of text document, hence why it lives 39/// within the utils::text library. 40/// 41/// An example of how the templates look like: 42/// 43/// %if names 44/// List of names 45/// ------------- 46/// Amount of names: %%length(names)%% 47/// Most preferred name: %%preferred_name%% 48/// Full list: 49/// %loop names iter 50/// * %%last_names(iter)%%, %%names(iter)%% 51/// %endloop 52/// %endif names 53 54#if !defined(UTILS_TEXT_TEMPLATES_HPP) 55#define UTILS_TEXT_TEMPLATES_HPP 56 57#include "utils/text/templates_fwd.hpp" 58 59#include <istream> 60#include <map> 61#include <ostream> 62#include <string> 63#include <vector> 64 65#include "utils/fs/path_fwd.hpp" 66 67namespace utils { 68namespace text { 69 70 71/// Definitions of the templates to apply to a file. 72/// 73/// This class provides the environment (e.g. the list of variables) that the 74/// templating system has to use when generating the output files. This 75/// definition is static in the sense that this is what the caller program 76/// specifies. 77class templates_def { 78 /// Mapping of variable names to their values. 79 typedef std::map< std::string, std::string > variables_map; 80 81 /// Collection of global variables available to the templates. 82 variables_map _variables; 83 84 /// Convenience name for a vector of strings. 85 typedef std::vector< std::string > strings_vector; 86 87 /// Mapping of vector names to their contents. 88 /// 89 /// Ideally, these would be represented as part of the _variables, but we 90 /// would need a complex mechanism to identify whether a variable is a 91 /// string or a vector. 92 typedef std::map< std::string, strings_vector > vectors_map; 93 94 /// Collection of vectors available to the templates. 95 vectors_map _vectors; 96 97 const std::string& get_vector(const std::string&, const std::string&) const; 98 99public: 100 templates_def(void); 101 102 void add_variable(const std::string&, const std::string&); 103 void remove_variable(const std::string&); 104 void add_vector(const std::string&); 105 void add_to_vector(const std::string&, const std::string&); 106 107 bool exists(const std::string&) const; 108 const std::string& get_variable(const std::string&) const; 109 const strings_vector& get_vector(const std::string&) const; 110 111 std::string evaluate(const std::string&) const; 112}; 113 114 115void instantiate(const templates_def&, std::istream&, std::ostream&); 116void instantiate(const templates_def&, const fs::path&, const fs::path&); 117 118 119} // namespace text 120} // namespace utils 121 122#endif // !defined(UTILS_TEXT_TEMPLATES_HPP) 123