1 // Copyright 2012 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 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 <istream> 58 #include <map> 59 #include <ostream> 60 #include <string> 61 #include <vector> 62 63 #include "utils/fs/path.hpp" 64 65 namespace utils { 66 namespace text { 67 68 69 /// Definitions of the templates to apply to a file. 70 /// 71 /// This class provides the environment (e.g. the list of variables) that the 72 /// templating system has to use when generating the output files. This 73 /// definition is static in the sense that this is what the caller program 74 /// specifies. 75 class templates_def { 76 /// Mapping of variable names to their values. 77 typedef std::map< std::string, std::string > variables_map; 78 79 /// Collection of global variables available to the templates. 80 variables_map _variables; 81 82 /// Convenience name for a vector of strings. 83 typedef std::vector< std::string > strings_vector; 84 85 /// Mapping of vector names to their contents. 86 /// 87 /// Ideally, these would be represented as part of the _variables, but we 88 /// would need a complex mechanism to identify whether a variable is a 89 /// string or a vector. 90 typedef std::map< std::string, strings_vector > vectors_map; 91 92 /// Collection of vectors available to the templates. 93 vectors_map _vectors; 94 95 const std::string& get_vector(const std::string&, const std::string&) const; 96 97 public: 98 templates_def(void); 99 100 void add_variable(const std::string&, const std::string&); 101 void remove_variable(const std::string&); 102 void add_vector(const std::string&); 103 void add_to_vector(const std::string&, const std::string&); 104 105 bool exists(const std::string&) const; 106 const std::string& get_variable(const std::string&) const; 107 const strings_vector& get_vector(const std::string&) const; 108 109 std::string evaluate(const std::string&) const; 110 }; 111 112 113 void instantiate(const templates_def&, std::istream&, std::ostream&); 114 void instantiate(const templates_def&, const fs::path&, const fs::path&); 115 116 117 } // namespace text 118 } // namespace utils 119 120 #endif // !defined(UTILS_TEXT_TEMPLATES_HPP) 121