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 67 namespace utils { 68 namespace 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. 77 class 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 99 public: 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 115 void instantiate(const templates_def&, std::istream&, std::ostream&); 116 void 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