2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2016,2017,2018,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.
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.
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.
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.
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.
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.
35 /*! \libinternal \file
37 * Declares utilities for transforming key-value trees.
39 * See \ref page_mdmodules for the main use case that these support.
41 * \author Teemu Murtola <teemu.murtola@gmail.com>
43 * \ingroup module_utility
45 #ifndef GMX_UTILITY_KEYVALUETREETRANSFORM_H
46 #define GMX_UTILITY_KEYVALUETREETRANSFORM_H
53 #include "gromacs/utility/any.h"
54 #include "gromacs/utility/classhelpers.h"
55 #include "gromacs/utility/keyvaluetree.h"
60 class IKeyValueTreeErrorHandler
;
61 class KeyValueTreeObjectBuilder
;
63 enum class StringCompareType
;
65 class KeyValueTreeTransformResult
;
66 class KeyValueTreeTransformRuleBuilder
;
67 class KeyValueTreeTransformRulesScoped
;
71 class KeyValueTreeTransformerImpl
;
74 /*! \libinternal \brief
75 * Interface to declare rules for transforming key-value trees.
77 * This interface is used to add transformation rules for key-value trees.
78 * A transformation is a set of rules that is used to map an input key-value
79 * tree to an output key-value tree, with possible conversion steps performed
80 * in the process. Currently, each rule maps one item from the source tree to
81 * one item in the target tree (it is possible to expand a single value into an
82 * object with multiple properties). See KeyValueTreeTransformRuleBuilder for
83 * the kinds of rules currently supported.
85 * The main use currently is in converting flat-format mdp files to a
86 * structured internal representation.
89 * \ingroup module_utility
91 class IKeyValueTreeTransformRules
97 * Properties of the new rule must be specified using the returned
100 virtual KeyValueTreeTransformRuleBuilder
addRule() = 0;
102 * Creates a scoped set of rules, where all rules use a target sub-tree.
104 * \param[in] scope Prefix defining the scope in the target tree
106 * Any rules added to the returned scope will have `scope` prefixed to
107 * their target paths, i.e., it is not possible to produce elements
108 * outside the specified subtree.
110 virtual KeyValueTreeTransformRulesScoped
scopedTransform(const KeyValueTreePath
& scope
) = 0;
113 virtual ~IKeyValueTreeTransformRules();
116 /*! \libinternal \brief
117 * Helper object returned from IKeyValueTreeTransformRules::scopedTransform().
120 * \ingroup module_utility
122 class KeyValueTreeTransformRulesScoped
125 //! Internal constructor for creating the scope.
126 KeyValueTreeTransformRulesScoped(internal::KeyValueTreeTransformerImpl
* impl
,
127 const KeyValueTreePath
& prefix
);
128 //! Supports returning the object from IKeyValueTreeTransformRules::scopedTransform().
129 KeyValueTreeTransformRulesScoped(KeyValueTreeTransformRulesScoped
&& other
) noexcept
;
130 //! Supports returning the object from IKeyValueTreeTransformRules::scopedTransform().
131 KeyValueTreeTransformRulesScoped
& operator=(KeyValueTreeTransformRulesScoped
&& other
) noexcept
;
132 ~KeyValueTreeTransformRulesScoped();
134 //! Returns the interface for adding rules to this scope.
135 IKeyValueTreeTransformRules
* rules();
140 PrivateImplPointer
<Impl
> impl_
;
143 /*! \libinternal \brief
144 * Provides methods to specify one transformation rule.
147 * The builder is implemented as a set of nested objects, each of which is
148 * provides methods for setting a particular property of the rule. Setting a
149 * property returns another object that has relevant methods for the context.
150 * This provides some structure to the methods, and catches at least some types
151 * of incorrect rules already at compile time.
152 * Additionally, if you use an IDE with completion facilities, it can nicely
153 * guide you through which values you need to specify.
154 * All values are stored within the main builder object, and the rule is
155 * created at the end of the statement.
159 * \ingroup module_utility
161 class KeyValueTreeTransformRuleBuilder
165 * Base class used for implementing parameter provider objects.
170 //! Creates a parameter provider object within given builder.
171 explicit Base(KeyValueTreeTransformRuleBuilder
* builder
) : builder_(builder
) {}
173 //! The parent builder.
174 KeyValueTreeTransformRuleBuilder
* builder_
;
177 /*! \libinternal \brief
178 * Properties that can be specified after from().to().
180 * \tparam FromType Type specified for from() to map from.
181 * \tparam ToType Type specified for to() to map to.
183 template<typename FromType
, typename ToType
>
184 class ToValue
: public Base
187 //! Creates a parameter provider object within given builder.
188 explicit ToValue(KeyValueTreeTransformRuleBuilder
* builder
) : Base(builder
) {}
191 * Specifies the transformation function to convert the value
192 * from FromType to ToType.
194 void transformWith(std::function
<ToType(const FromType
&)> transform
)
196 builder_
->addTransformToAny([transform
](const Any
& value
) {
197 return Any::create
<ToType
>(transform(value
.cast
<FromType
>()));
202 /*! \libinternal \brief
203 * Properties that can be specified after from().toObject().
205 * \tparam FromType Type specified for from() to map from.
207 template<typename FromType
>
208 class ToObject
: public Base
211 //! Creates a parameter provider object within given builder.
212 explicit ToObject(KeyValueTreeTransformRuleBuilder
* builder
) : Base(builder
) {}
215 * Specifies the transformation function to build the output
218 * The transform should build the output object with the
221 void transformWith(std::function
<void(KeyValueTreeObjectBuilder
*, const FromType
&)> transform
)
223 builder_
->addTransformToObject([transform
](KeyValueTreeObjectBuilder
* builder
, const Any
& value
) {
224 transform(builder
, value
.cast
<FromType
>());
229 /*! \libinternal \brief
230 * Properties that can be specified after from().
232 * \tparam FromType Type specified for from() to map from.
234 template<typename FromType
>
235 class AfterFrom
: public Base
238 //! Creates a parameter provider object within given builder.
239 explicit AfterFrom(KeyValueTreeTransformRuleBuilder
* builder
) : Base(builder
) {}
242 * Specifies a rule that maps to a value at given path.
244 * \tparam ToType Type to map to.
245 * \param[in] path Path to map to.
247 * It is an error if multiple rules map to the same path, or to
248 * a parent path of the target of an existing rule.
249 * Note that it is possible to have a to() rule map to a child
250 * of a toObject() rule, provided that the path is not created
251 * by the object rule.
253 template<typename ToType
>
254 ToValue
<FromType
, ToType
> to(const KeyValueTreePath
& path
)
256 builder_
->setToPath(path
);
257 return ToValue
<FromType
, ToType
>(builder_
);
261 * Specifies a rule that maps to an object (collection of named
262 * values) at given path.
264 * \param[in] path Path to map to.
266 * It is an error if multiple rules map to the same path, or to
267 * a parent path of the target of an existing rule.
268 * However, it is allowed to have two toObject() rules map to
269 * the same path, provided that the properties they produce are
272 ToObject
<FromType
> toObject(const KeyValueTreePath
& path
)
274 builder_
->setToPath(path
);
275 return ToObject
<FromType
>(builder_
);
279 //! Internal constructor for creating a builder.
280 KeyValueTreeTransformRuleBuilder(internal::KeyValueTreeTransformerImpl
* impl
,
281 const KeyValueTreePath
& prefix
);
282 //! Supports returning the builder from IKeyValueTreeTransformRules::addRule().
283 KeyValueTreeTransformRuleBuilder(KeyValueTreeTransformRuleBuilder
&&) = default;
284 //! Supports returning the builder from IKeyValueTreeTransformRules::addRule().
285 KeyValueTreeTransformRuleBuilder
& operator=(KeyValueTreeTransformRuleBuilder
&&) = default;
286 ~KeyValueTreeTransformRuleBuilder(); // NOLINT(bugprone-exception-escape)
289 * Specifies a rule that maps a value at given path.
291 * \tparam FromType Type of value expected at `path`.
292 * \param[in] path Path to map in this rule.
294 * If the input tree has `path`, but it is not of type `FromType`,
295 * the transform will produce an error.
297 * It is an error to use the same path in two from() rules. Similarly,
298 * it is an error to use a child path of a path used in a different
301 template<typename FromType
>
302 AfterFrom
<FromType
> from(const KeyValueTreePath
& path
)
305 setExpectedType(typeid(FromType
));
306 return AfterFrom
<FromType
>(this);
309 * Specifies how strings are matched when matching rules against a path.
311 * For properties of the object at `path`, `keyMatchType` is used for
314 * This rule must be specified first for a path, before any other
315 * from() rule specifies the path or a subpath.
316 * The rule only applies to immediate properties at the given path, not
318 * It is an error to specify the match type multiple times for a path.
320 void keyMatchType(const KeyValueTreePath
& path
, StringCompareType keyMatchType
)
323 setKeyMatchType(keyMatchType
);
327 void setFromPath(const KeyValueTreePath
& path
);
328 void setExpectedType(const std::type_index
& type
);
329 void setToPath(const KeyValueTreePath
& path
);
330 void setKeyMatchType(StringCompareType keyMatchType
);
331 void addTransformToAny(const std::function
<Any(const Any
&)>& transform
);
332 void addTransformToObject(const std::function
<void(KeyValueTreeObjectBuilder
*, const Any
&)>& transform
);
336 internal::KeyValueTreeTransformerImpl
* impl_
;
337 std::unique_ptr
<Data
> data_
;
340 class KeyValueTreeTransformer
343 KeyValueTreeTransformer();
344 ~KeyValueTreeTransformer();
346 IKeyValueTreeTransformRules
* rules();
348 std::vector
<KeyValueTreePath
> mappedPaths() const;
350 KeyValueTreeTransformResult
transform(const KeyValueTreeObject
& tree
,
351 IKeyValueTreeErrorHandler
* errorHandler
) const;
354 PrivateImplPointer
<internal::KeyValueTreeTransformerImpl
> impl_
;
357 class IKeyValueTreeBackMapping
360 virtual ~IKeyValueTreeBackMapping();
362 virtual KeyValueTreePath
originalPath(const KeyValueTreePath
& path
) const = 0;
365 class KeyValueTreeTransformResult
368 KeyValueTreeObject
object() { return std::move(object_
); }
369 const IKeyValueTreeBackMapping
& backMapping() const { return *mapping_
; }
372 typedef std::unique_ptr
<IKeyValueTreeBackMapping
> MappingPointer
;
374 KeyValueTreeTransformResult(KeyValueTreeObject
&& object
, MappingPointer
&& mapping
) :
375 object_(std::move(object
)),
376 mapping_(std::move(mapping
))
380 KeyValueTreeObject object_
;
381 MappingPointer mapping_
;
383 friend class internal::KeyValueTreeTransformerImpl
;