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