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/config/tree.hpp
30/// Data type to represent a tree of arbitrary values with string keys.
31
32#if !defined(UTILS_CONFIG_TREE_HPP)
33#define UTILS_CONFIG_TREE_HPP
34
35#include "utils/config/tree_fwd.hpp"
36
37#include <memory>
38#include <string>
39
40#include <lutok/state.hpp>
41
42#include "utils/config/keys_fwd.hpp"
43#include "utils/config/nodes_fwd.hpp"
44
45namespace utils {
46namespace config {
47
48
49/// Representation of a tree.
50///
51/// The string keys of the tree are in dotted notation and actually represent
52/// path traversals through the nodes.
53///
54/// Our trees are "strictly-keyed": keys must be defined as "existent" before
55/// their values can be set.  Defining a key is a separate action from setting
56/// its value.  The rationale is that we want to be able to control what keys
57/// get defined: because trees are used to hold configuration, we want to catch
58/// typos as early as possible.  Also, users cannot set keys unless the types
59/// are known in advance because our leaf nodes are strictly typed.
60///
61/// However, there is an exception to the strict keys: the inner nodes of the
62/// tree can be static or dynamic.  Static inner nodes have a known subset of
63/// children and attempting to set keys not previously defined will result in an
64/// error.  Dynamic inner nodes do not have a predefined set of keys and can be
65/// used to accept arbitrary user input.
66///
67/// For simplicity reasons, we force the root of the tree to be a static inner
68/// node.  In other words, the root can never contain a value by itself and this
69/// is not a problem because the root is not addressable by the key space.
70/// Additionally, the root is strict so all of its direct children must be
71/// explicitly defined.
72///
73/// This is, effectively, a simple wrapper around the node representing the
74/// root.  Having a separate class aids in clearly representing the concept of a
75/// tree and all of its public methods.  Also, the tree accepts dotted notations
76/// for the keys while the internal structures do not.
77///
78/// Note that trees are shallow-copied unless a deep copy is requested with
79/// deep_copy().
80class tree {
81    /// Whether keys must be validated at "set" time.
82    bool _strict;
83
84    /// The root of the tree.
85    std::shared_ptr< detail::static_inner_node > _root;
86
87    tree(const bool, detail::static_inner_node*);
88
89public:
90    tree(const bool = true);
91    ~tree(void);
92
93    tree deep_copy(void) const;
94    tree combine(const tree&) const;
95
96    template< class LeafType >
97    void define(const std::string&);
98
99    void define_dynamic(const std::string&);
100
101    bool is_set(const std::string&) const;
102
103    template< class LeafType >
104    const typename LeafType::value_type& lookup(const std::string&) const;
105    template< class LeafType >
106    typename LeafType::value_type& lookup_rw(const std::string&);
107
108    template< class LeafType >
109    void set(const std::string&, const typename LeafType::value_type&);
110
111    void push_lua(const std::string&, lutok::state&) const;
112    void set_lua(const std::string&, lutok::state&, const int);
113
114    std::string lookup_string(const std::string&) const;
115    void set_string(const std::string&, const std::string&);
116
117    properties_map all_properties(const std::string& = "",
118                                  const bool = false) const;
119
120    bool operator==(const tree&) const;
121    bool operator!=(const tree&) const;
122};
123
124
125}  // namespace config
126}  // namespace utils
127
128#endif  // !defined(UTILS_CONFIG_TREE_HPP)
129