ReflectorInterface.h

Go to the documentation of this file.

/*
 * Copyright (C) 2012 by
 *   MetraLabs GmbH (MLAB), GERMANY
 * and
 *   Neuroinformatics and Cognitive Robotics Labs (NICR) at TU Ilmenau, GERMANY
 * All rights reserved.
 *
 * Contact: info@mira-project.org
 *
 * Commercial Usage:
 *   Licensees holding valid commercial licenses may use this file in
 *   accordance with the commercial license agreement provided with the
 *   software or, alternatively, in accordance with the terms contained in
 *   a written agreement between you and MLAB or NICR.
 *
 * GNU General Public License Usage:
 *   Alternatively, this file may be used under the terms of the GNU
 *   General Public License version 3.0 as published by the Free Software
 *   Foundation and appearing in the file LICENSE.GPL3 included in the
 *   packaging of this file. Please review the following information to
 *   ensure the GNU General Public License version 3.0 requirements will be
 *   met: http://www.gnu.org/copyleft/gpl.html.
 *   Alternatively you may (at your option) use any later version of the GNU
 *   General Public License if such license has been publicly approved by
 *   MLAB and NICR (or its successors, if any).
 *
 * IN NO EVENT SHALL "MLAB" OR "NICR" BE LIABLE TO ANY PARTY FOR DIRECT,
 * INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
 * THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF "MLAB" OR
 * "NICR" HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * "MLAB" AND "NICR" SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
 * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND "MLAB" AND "NICR" HAVE NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS OR MODIFICATIONS.
 */

#ifndef _MIRA_REFLECTORINTERFACE_H_
#define _MIRA_REFLECTORINTERFACE_H_

#include <string>
#include <unordered_map>

#ifndef Q_MOC_RUN
#include <boost/preprocessor/repetition.hpp>
#include <boost/mpl/bool.hpp>
#include <boost/type_traits/integral_constant.hpp>
#endif

#include <platform/Environment.h>
#include <platform/Typename.h>

#include <rpc/RPCPatternCheck.h>
#include <serialization/GetterSetter.h>
#include <serialization/PropertyHint.h>
#include <serialization/ReflectControlFlags.h>

namespace mira {


namespace serialization {
    typedef uint8 VersionType;
    typedef std::unordered_map<Typename, VersionType> ClassVersionMap;

    struct AcceptDesiredVersion {};
}

template <typename Derived>
class ReflectorInterface
{
public:
    struct Tag {};

    typedef boost::mpl::bool_<true> isReadOnly;

    typedef boost::mpl::bool_<true> useHumanReadableIDs;

    typedef boost::mpl::bool_<false> requireReflectBarriers;

    struct ReflectState {};

public:

    typedef serialization::VersionType VersionType;

    template <typename T>
    VersionType version(VersionType version, const T* caller = NULL)
    {
        return version;
    }

    MIRA_DEPRECATED("Please call as version<MyType>(v) or version(v, this)",
    VersionType version(VersionType version)) { return version; }

    template <typename T>
    VersionType requireVersion(VersionType version,
                               VersionType minVersion, const T* caller = NULL) { return version; }

    MIRA_DEPRECATED("Please call as requireVersion<MyType>(v, minV) or requireVersion(v, minV, this)",
    VersionType requireVersion(VersionType version, VersionType minVersion)) { return version; }

    template <typename T>
    void requireVersion(VersionType version, const T* caller = NULL) {}

    MIRA_DEPRECATED("Please call as requireVersion<MyType>(v) or requireVersion(v, this)",
    VersionType requireVersion(VersionType version)) { return version; }

    typedef serialization::ClassVersionMap ClassVersionMap;

    void desireClassVersions(const ClassVersionMap& versions) {}

    typedef serialization::AcceptDesiredVersion AcceptDesiredVersion;

    template <typename T>
    VersionType version(VersionType version, AcceptDesiredVersion, const T* caller = NULL)
    {
        return version;
    }

    template <typename T>
    VersionType requireVersion(VersionType version, VersionType minVersion,
                               AcceptDesiredVersion, const T* caller = NULL) { return version; }

    template <typename T>
    void requireVersion(VersionType version, AcceptDesiredVersion, const T* caller = NULL) {}



    template<typename T>
    void member(const char* name, T& member, const char* comment,
                ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void member(const char* name, const std::string& id, T& member,
                const char* comment, ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void member(const char* name, const T& member, Setter<T> setter,
                const char* comment, ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void member(const char* name, Getter<T> getter, Setter<T> setter,
                const char* comment, ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}


    // with default value

    template<typename T, typename U>
    void member(const char* name, T& member, const char* comment,
                const U& defaultValue, ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T, typename U>
    void member(const char* name, const T& member, Setter<T> setter,
                const char* comment, const U& defaultValue,
                ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T, typename U>
    void member(const char* name, Getter<T> getter, Setter<T> setter,
                const char* comment, const U& defaultValue,
                ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    // Properties

    template<typename T>
    void property(const char* name, T& member, const char* comment,
                  PropertyHint&& hint = PropertyHint(),
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void property(const char* name, const std::string& id, T& member,
                  const char* comment, PropertyHint&& hint = PropertyHint(),
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void property(const char* name, const T& member, Setter<T> setter,
                  const char* comment, PropertyHint&& hint = PropertyHint(),
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void property(const char* name, Getter<T> getter, Setter<T> setter,
                  const char* comment, PropertyHint&& hint = PropertyHint(),
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    // default values

    template<typename T, typename U>
    void property(const char* name, T& member, const char* comment,
                  const U& defaultValue, PropertyHint&& hint = PropertyHint(),
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T, typename U>
    void property(const char* name, const T& member, Setter<T> setter,
                  const char* comment, const U& defaultValue,
                  PropertyHint&& hint = PropertyHint(),
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T, typename U>
    void property(const char* name, Getter<T> getter, Setter<T> setter,
                  const char* comment, const U& defaultValue,
                  PropertyHint&& hint = PropertyHint(),
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}


    template<typename T>
    void roproperty(const char* name, const T& member,
                    const char* comment, PropertyHint&& hint = PropertyHint(),
                    ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void roproperty(const char* name, const std::string& id, const T& member,
                    const char* comment, PropertyHint&& hint = PropertyHint(),
                    ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void roproperty(const char* name, Getter<T> getter, const char* comment,
                    PropertyHint&& hint = PropertyHint(),
                    ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    void itemName(const std::string& name) {}

    template<typename T>
    void delegate(T& member,
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void delegate(const T& member, Setter<T> setter,
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}

    template<typename T>
    void delegate(Getter<T> getter, Setter<T> setter,
                  ReflectCtrlFlags flags = REFLECT_CTRLFLAG_NONE) {}



    void interface(const char* name) {}

    // invalid method signatures
    template<typename R, typename... Args, typename F, typename... Description>
    InvalidRPCDescription<R(Args...), Description...>
    method(const char*, F&&, Description&&...)
    {
        Private::rpc::invalidAssertion<R(Args...), Description...>();
    }

    template<typename F, typename... Description>
    InvalidRPCDescription<F, Description...>
    method(const char*, F&&, Description&&...)
    {
        Private::rpc::invalidAssertion<F, Description...>();
    }

    template<typename R, typename Class, typename... Args, typename... Description>
    InvalidRPCDescription<R (Class::*)(Args...), Description...>
    method(const char*, R (Class::*)(Args...), Class*, Description&&...)
    {
        Private::rpc::invalidAssertion<R (Class::*)(Args...), Description...>();
    }

    template<typename R, typename Class, typename... Args, typename... Description>
    InvalidRPCDescription<R (Class::*)(Args...) const, Description...>
    method(const char*, R (Class::*)(Args...) const, Class*, Description&&...)
    {
        Private::rpc::invalidAssertion<R (Class::*)(Args...) const, Description...>();
    }

    // valid method signatures
    template<typename R, typename... Args, typename F, typename... Description>
    ValidRPCDescription<R(Args...), Description...>
    method(const char*, F&&, Description&&...)
    {}

    template<typename F, typename... Description>
    ValidRPCDescription<F, Description...>
    method(const char*, F&&, Description&&...)
    {}

    template<typename R, typename Class, typename... Args, typename... Description>
    ValidRPCDescription<R (Class::*)(Args...), Description...>
    method(const char*, R (Class::*)(Args...), Class*, Description&&...)
    {}

    template<typename R, typename Class, typename... Args, typename... Description>
    ValidRPCDescription<R (Class::*)(Args...) const, Description...>
    method(const char*, R (Class::*)(Args...) const, Class*, Description&&...)
    {}

    // provide a method that causes an error at compile time if instantiated. Derived classes overriding
    // method() should call this in their implementation for wrong argument number
    template<typename R, typename ...Args>
    void invalid_method()
    { /* force this to fail whenever it is instantiated - but only then! */
        static_assert(
            sizeof(R*) == 0,
            "_____________NUMBER OR TYPES OF NAMES/DESCRIPTIONS/SAMPLEVALUES FOR PARAMETERS "
            "IN CALL TO Reflector::method() DO NOT MATCH THE PROVIDED FUNCTION'S SIGNATURE. "
            "PLEASE PROVIDE const char* NAME AND DESCRIPTION FOR EACH RPC METHOD PARAMETER, "
            "OR NAME, DESCRIPTION AND A CORRECTLY TYPED SAMPLE VALUE FOR EACH PARAMETER._____________");
    }

#ifdef DOXYGEN
    // this is a fake method to generate a doxygen documentation for the
    // methods created above

    void method(const char* name, Method method, const char* comment,
                const char* paramName, const char* paramDescription, P paramSampleValue, ...);

    void method(const char* name, Method method, Class* object, const char* comment,
                const char* paramName, const char* paramDescription, P paramSampleValue, ...);

    void method(const char* name, Method method, const char* comment,
                const char* paramName, const char* paramDescription, P paramSampleValue, ...);

#endif



    void pushObjectTrackingStore() {}

    void popObjectTrackingStore() {}


    template <typename Base>
    void reflectBase(Base& base) {}


    static bool usesHumanReadableIDs() {
        return Derived::useHumanReadableIDs::value;
    }

    ReflectState preReflect(const char* context = "")
    {
        MIRA_THROW(XNotImplemented,
                   typeName<Derived>() << "::requireReflectBarriers == true, but " <<
                   typeName<Derived>() << "::preReflect() not implemented!");
    
        return ReflectState();
    }

    void postReflect(const ReflectState&)
    {
        MIRA_THROW(XNotImplemented,
                   typeName<Derived>() << "::requireReflectBarriers == true, but " <<
                   typeName<Derived>() << "::postReflect() not implemented!");
    }

protected:

    static int checkForcedVersion(const std::string& variable)
    {
        try {
            std::stringstream ss;
            ss.str(resolveEnvironmentVariable(variable));
            int i;
            ss >> i;
            return i;
        }
        catch(XInvalidConfig&) {}

        return -1;
    }
};


#define MIRA_REFLECT_VERSION(reflector, versionNumber) reflector.version(versionNumber, this)

#define MIRA_REFLECT_REQUIRE_VERSION(reflector, versionNumber) reflector.requireVersion(versionNumber, this)

#define MIRA_REFLECT_BASE(reflector, BaseClass) reflector.template reflectBase<BaseClass>(*this)

#define MIRA_REFLECT_BASE_NONINTRUSIVE(reflector, BaseClass, object) reflector.template reflectBase<BaseClass>(object)

#define MIRA_REFLECT_BASE_IF_VERSION_ATLEAST(reflector, BaseClass, versionvar, minversion) \
    if (versionvar < minversion)                                                           \
        BaseClass::reflect(reflector);                                                     \
    else                                                                                   \
        reflector.template reflectBase<BaseClass>(*this);                                  \


#define MIRA_REFLECT_BASE_NONINTRUSIVE_IF_VERSION_ATLEAST(reflector, BaseClass, object, versionvar, minversion) \
    if (versionvar < minversion)                                                           \
        reflect(reflector, (BaseClass&)object);                                            \
    else                                                                                   \
        reflector.template reflectBase<BaseClass>(object);                                 \


#define MIRA_MEMBER_WITH_ID(reflector, name, id, var, ...) \
    if(reflector.usesHumanReadableIDs())                   \
        reflector.member(name, id, var, __VA_ARGS__);      \
    else                                                   \
        reflector.member(name, var, __VA_ARGS__);

#define MIRA_PROPERTY_WITH_ID(reflector, name, id, var, ...) \
    if(reflector.usesHumanReadableIDs())                     \
        reflector.property(name, id, var, __VA_ARGS__);      \
    else                                                     \
        reflector.property(name, var, __VA_ARGS__);


} // namespace

#endif