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