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 45 namespace utils { 46 namespace 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(). 80 class 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 89 public: 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