Home | History | Annotate | Line # | Download | only in text 
      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