src/gromacs/utility/keyvaluetreebuilder.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2016,2017,2019, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \libinternal \file
  36  * \brief
  37  * Declares classes for building the data structures in keyvaluetree.h.
  38  *
  39  * These are separate from the data structures to enforce clear separation of
  40  * the APIs, and to make the data structure immutable after construction.
  41  *
  42  * For the main use case described in \ref page_mdmodules, they are mainly
  43  * used internally, but currently gmx::KeyValueTreeObjectBuilder (and
  44  * everything it references) is exposed for more complex transforms through
  45  * gmx::IKeyValueTreeTransformRules.
  46  *
  47  * \author Teemu Murtola <teemu.murtola@gmail.com>
  48  * \inlibraryapi
  49  * \ingroup module_utility
  50  */
  51 #ifndef GMX_UTILITY_KEYVALUETREEBUILDER_H
  52 #define GMX_UTILITY_KEYVALUETREEBUILDER_H
  53
  54 #include <initializer_list>
  55 #include <string>
  56 #include <utility>
  57 #include <vector>
  58
  59 #include "gromacs/utility/any.h"
  60 #include "gromacs/utility/gmxassert.h"
  61 #include "gromacs/utility/keyvaluetree.h"
  62
  63 namespace gmx
  64 {
  65
  66 class KeyValueTreeArrayBuilder;
  67 class KeyValueTreeObjectBuilder;
  68
  69 /*! \libinternal \brief
  70  * Root builder for creating trees that have an object at the root.
  71  *
  72  * \inlibraryapi
  73  * \ingroup module_utility
  74  */
  75 class KeyValueTreeBuilder
  76 {
  77     public:
  78         //! Returns a builder for the root object.
  79         KeyValueTreeObjectBuilder rootObject();
  80
  81         /*! \brief
  82          * Builds the final object.
  83          *
  84          * The builder should not be accessed after this call.
  85          */
  86         KeyValueTreeObject build() { return std::move(root_); }
  87
  88     private:
  89         /*! \brief
  90          * Helper function for other builders to create values of certain type.
  91          */
  92         template <typename T>
  93         static KeyValueTreeValue createValue(const T &value)
  94         {
  95             return KeyValueTreeValue(Any::create<T>(value));
  96         }
  97         /*! \brief
  98          * Helper function for other builders to create default-constructed
  99          * values.
 100          */
 101         template <typename T>
 102         static KeyValueTreeValue createValue()
 103         {
 104             return KeyValueTreeValue(Any::create<T>(T()));
 105         }
 106
 107         KeyValueTreeObject root_;
 108
 109         //! For access to createValue() methods.
 110         friend class KeyValueTreeObjectArrayBuilder;
 111         //! For access to createValue() methods.
 112         friend class KeyValueTreeObjectBuilder;
 113         //! For access to createValue() methods.
 114         template <typename T>
 115         friend class KeyValueTreeUniformArrayBuilder;
 116 };
 117
 118 /*! \libinternal \brief
 119  * Builder for KeyValueTreeValue objects.
 120  *
 121  * This builder can be constructed directly and can create self-standing
 122  * KeyValueTreeValue objects.
 123  *
 124  * \inlibraryapi
 125  * \ingroup module_utility
 126  */
 127 class KeyValueTreeValueBuilder
 128 {
 129     public:
 130         //! Assigns a scalar value of certain type.
 131         template <typename T>
 132         void setValue(const T &value)
 133         {
 134             value_ = Any::create<T>(value);
 135         }
 136         //! Assigns a Any value to the built value.
 137         void setAnyValue(Any &&value)
 138         {
 139             value_ = std::move(value);
 140         }
 141         /*! \brief
 142          * Returns an object builder for building an object into this value.
 143          *
 144          * Any method call in this value builder invalidates the returned
 145          * builder.
 146          */
 147         KeyValueTreeObjectBuilder createObject();
 148         /*! \brief
 149          * Returns an array builder for building an array into this value.
 150          *
 151          * Any method call in this value builder invalidates the returned
 152          * builder.
 153          */
 154         KeyValueTreeArrayBuilder createArray();
 155
 156         /*! \brief
 157          * Builds the final value.
 158          *
 159          * The builder should not be accessed after this call.
 160          */
 161         KeyValueTreeValue build() { return KeyValueTreeValue(std::move(value_)); }
 162
 163     private:
 164         Any value_;
 165 };
 166
 167 class KeyValueTreeArrayBuilderBase
 168 {
 169     protected:
 170         //! Creates an array builder for populating given array object.
 171         explicit KeyValueTreeArrayBuilderBase(KeyValueTreeArray *array)
 172             : array_(array)
 173         {
 174         }
 175
 176         //! Appends a raw Any value to the array.
 177         KeyValueTreeValue &addRawValue(Any &&value)
 178         {
 179             KeyValueTreeValueBuilder builder;
 180             builder.setAnyValue(std::move(value));
 181             array_->values_.push_back(builder.build());
 182             return array_->values_.back();
 183         }
 184         //! Appends a raw KeyValueTreeValue to the array.
 185         KeyValueTreeValue &addRawValue(KeyValueTreeValue &&value)
 186         {
 187             array_->values_.push_back(std::move(value));
 188             return array_->values_.back();
 189         }
 190
 191     private:
 192         KeyValueTreeArray *array_;
 193 };
 194
 195 class KeyValueTreeArrayBuilder : public KeyValueTreeArrayBuilderBase
 196 {
 197     public:
 198         using KeyValueTreeArrayBuilderBase::addRawValue;
 199
 200     private:
 201         explicit KeyValueTreeArrayBuilder(KeyValueTreeArray *array)
 202             : KeyValueTreeArrayBuilderBase(array)
 203         {
 204         }
 205
 206         friend class KeyValueTreeObjectBuilder;
 207         friend class KeyValueTreeValueBuilder;
 208 };
 209
 210 /*! \libinternal \brief
 211  * Builder for KeyValueTreeArray objects where all elements are of type `T`.
 212  *
 213  * The builder does not own the array being constructed, but instead holds a
 214  * reference to an object within a tree rooted in KeyValueTreeBuilder or
 215  * KeyValueTreeValueBuilder.
 216  *
 217  * \inlibraryapi
 218  * \ingroup module_utility
 219  */
 220 template <typename T>
 221 class KeyValueTreeUniformArrayBuilder : public KeyValueTreeArrayBuilderBase
 222 {
 223     public:
 224         //! Appends a value to the array.
 225         void addValue(const T &value)
 226         {
 227             addRawValue(KeyValueTreeBuilder::createValue<T>(value));
 228         }
 229
 230     private:
 231         explicit KeyValueTreeUniformArrayBuilder(KeyValueTreeArray *array)
 232             : KeyValueTreeArrayBuilderBase(array)
 233         {
 234         }
 235
 236         friend class KeyValueTreeObjectBuilder;
 237 };
 238
 239 /*! \libinternal \brief
 240  * Builder for KeyValueTreeArray objects where all elements are
 241  * KeyValueTreeObject objects.
 242  *
 243  * The builder does not own the array being constructed, but instead holds a
 244  * reference to an object within a tree rooted in KeyValueTreeBuilder or
 245  * KeyValueTreeValueBuilder.
 246  *
 247  * \inlibraryapi
 248  * \ingroup module_utility
 249  */
 250 class KeyValueTreeObjectArrayBuilder : public KeyValueTreeArrayBuilderBase
 251 {
 252     public:
 253         /*! \brief
 254          * Appends an object to the array.
 255          *
 256          * The object is created empty and can be built using the returned
 257          * builder.
 258          */
 259         KeyValueTreeObjectBuilder addObject();
 260
 261     private:
 262         explicit KeyValueTreeObjectArrayBuilder(KeyValueTreeArray *array)
 263             : KeyValueTreeArrayBuilderBase(array)
 264         {
 265         }
 266
 267         friend class KeyValueTreeObjectBuilder;
 268 };
 269
 270 /*! \libinternal \brief
 271  * Builder for KeyValueTreeObject objects.
 272  *
 273  * The builder does not own the object being constructed, but instead holds a
 274  * reference to an object within a tree rooted in KeyValueTreeBuilder or
 275  * KeyValueTreeValueBuilder.
 276  *
 277  * \inlibraryapi
 278  * \ingroup module_utility
 279  */
 280 class KeyValueTreeObjectBuilder
 281 {
 282     public:
 283         //! Adds a property with given key from a KeyValueTreeValue.
 284         void addRawValue(const std::string &key, KeyValueTreeValue &&value)
 285         {
 286             addProperty(key, std::move(value));
 287         }
 288         //! Adds a property with given key from a Any value.
 289         void addRawValue(const std::string &key, Any &&value)
 290         {
 291             addProperty(key, KeyValueTreeValue(std::move(value)));
 292         }
 293         //! Adds a scalar property with given key, type, and value.
 294         template <typename T>
 295         void addValue(const std::string &key, const T &value)
 296         {
 297             addRawValue(key, KeyValueTreeBuilder::createValue<T>(value));
 298         }
 299         /*! \brief
 300          * Adds an object-valued property with given key.
 301          *
 302          * The object is created empty and can be built using the returned
 303          * builder.
 304          */
 305         KeyValueTreeObjectBuilder addObject(const std::string &key)
 306         {
 307             auto iter = addProperty(key, KeyValueTreeBuilder::createValue<KeyValueTreeObject>());
 308             return KeyValueTreeObjectBuilder(&iter->second);
 309         }
 310         /*! \brief
 311          * Adds a generic array-valued property with given key.
 312          *
 313          * The array is created empty and can be built using the returned
 314          * builder.
 315          */
 316         KeyValueTreeArrayBuilder addArray(const std::string &key)
 317         {
 318             auto iter = addProperty(key, KeyValueTreeBuilder::createValue<KeyValueTreeArray>());
 319             return KeyValueTreeArrayBuilder(&iter->second.asArray());
 320         }
 321         /*! \brief
 322          * Adds an array-valued property with uniform value types with given
 323          * key.
 324          *
 325          * \tparam T  Type for all values in the array.
 326          *
 327          * The array is created empty and can be built using the returned
 328          * builder.
 329          */
 330         template <typename T>
 331         KeyValueTreeUniformArrayBuilder<T> addUniformArray(const std::string &key)
 332         {
 333             auto iter = addProperty(key, KeyValueTreeBuilder::createValue<KeyValueTreeArray>());
 334             return KeyValueTreeUniformArrayBuilder<T>(&iter->second.asArray());
 335         }
 336         /*! \brief
 337          * Adds an array-valued property with uniform value types with given
 338          * key and values.
 339          *
 340          * \tparam T  Type for all values in the array.
 341          *
 342          * The array is created to contain the values from `values`.
 343          */
 344         template <typename T>
 345         void addUniformArray(const std::string &key, std::initializer_list<T> values)
 346         {
 347             auto builder = addUniformArray<T>(key);
 348             for (const auto &value : values)
 349             {
 350                 builder.addValue(value);
 351             }
 352         }
 353         /*! \brief
 354          * Adds an array-valued property with objects in the array with given
 355          * key.
 356          *
 357          * The array is created empty and can be built using the returned
 358          * builder.
 359          */
 360         KeyValueTreeObjectArrayBuilder addObjectArray(const std::string &key)
 361         {
 362             auto iter = addProperty(key, KeyValueTreeBuilder::createValue<KeyValueTreeArray>());
 363             return KeyValueTreeObjectArrayBuilder(&iter->second.asArray());
 364         }
 365
 366         //! Whether a property with given key exists.
 367         bool keyExists(const std::string &key) const { return object_->keyExists(key); }
 368         //! Returns value for a given key.
 369         const KeyValueTreeValue &operator[](const std::string &key) const
 370         {
 371             return (*object_)[key];
 372         }
 373         //! Returns an object builder for an existing object.
 374         KeyValueTreeObjectBuilder getObjectBuilder(const std::string &key)
 375         {
 376             GMX_ASSERT(keyExists(key), "Requested non-existent value");
 377             GMX_ASSERT((*this)[key].isObject(), "Accessing non-object value as object");
 378             return KeyValueTreeObjectBuilder(&object_->valueMap_.at(key).asObject());
 379         }
 380
 381         /*! \brief
 382          * Returns whether the given object shares any keys with \p this.
 383          */
 384         bool objectHasDistinctProperties(const KeyValueTreeObject &obj) const
 385         {
 386             return object_->hasDistinctProperties(obj);
 387         }
 388         /*! \brief
 389          * Merges properties from a given object to `this`.
 390          *
 391          * The objects should not share any keys, i.e.,
 392          * objectHasDistinctProperties() should return `true`.
 393          */
 394         void mergeObject(KeyValueTreeObject &&obj)
 395         {
 396             GMX_ASSERT(objectHasDistinctProperties(obj),
 397                        "Trying to merge overlapping object");
 398             for (auto &prop : obj.valueMap_)
 399             {
 400                 addRawValue(prop.first, std::move(prop.second));
 401             }
 402         }
 403
 404     private:
 405         explicit KeyValueTreeObjectBuilder(KeyValueTreeObject *object)
 406             : object_(object)
 407         {
 408         }
 409         explicit KeyValueTreeObjectBuilder(KeyValueTreeValue *value)
 410             : object_(&value->asObject())
 411         {
 412         }
 413
 414         std::map<std::string, KeyValueTreeValue>::iterator
 415         addProperty(const std::string &key, KeyValueTreeValue &&value)
 416         {
 417             GMX_RELEASE_ASSERT(!keyExists(key), "Duplicate key value");
 418             object_->values_.reserve(object_->values_.size() + 1);
 419             auto iter = object_->valueMap_.insert(std::make_pair(key, std::move(value))).first;
 420             object_->values_.push_back(KeyValueTreeProperty(iter));
 421             return iter;
 422         }
 423
 424         KeyValueTreeObject *object_;
 425
 426         friend class KeyValueTreeBuilder;
 427         friend class KeyValueTreeValueBuilder;
 428         friend class KeyValueTreeObjectArrayBuilder;
 429 };
 430
 431 /********************************************************************
 432  * Inline functions that could not be declared within the classes
 433  */
 434
 435 inline KeyValueTreeObjectBuilder KeyValueTreeBuilder::rootObject()
 436 {
 437     return KeyValueTreeObjectBuilder(&root_);
 438 }
 439
 440 inline KeyValueTreeObjectBuilder KeyValueTreeValueBuilder::createObject()
 441 {
 442     value_ = Any::create<KeyValueTreeObject>(KeyValueTreeObject());
 443     return KeyValueTreeObjectBuilder(&value_.castRef<KeyValueTreeObject>());
 444 }
 445
 446 inline KeyValueTreeArrayBuilder KeyValueTreeValueBuilder::createArray()
 447 {
 448     value_ = Any::create<KeyValueTreeArray>(KeyValueTreeArray());
 449     return KeyValueTreeArrayBuilder(&value_.castRef<KeyValueTreeArray>());
 450 }
 451
 452 inline KeyValueTreeObjectBuilder KeyValueTreeObjectArrayBuilder::addObject()
 453 {
 454     auto &value = addRawValue(KeyValueTreeBuilder::createValue<KeyValueTreeObject>());
 455     return KeyValueTreeObjectBuilder(&value);
 456 }
 457
 458 } // namespace gmx
 459
 460 #endif