vmeta.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header file is part of module \alib_config of the \aliblong.
///
/// \emoji :copyright: 2013-2024 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
#ifndef HPP_ALIB_CONFIG_VMETA
#define HPP_ALIB_CONFIG_VMETA 1
#pragma once
#include "alib/strings/util/escaper.hpp"
#include "alib/config/priority.hpp"
#include "alib/monomem/aliases/astringpa.hpp"
#include "alib/monomem/aliases/stringvector.hpp"
 
// forward declarations
namespace alib::config
{
    class Configuration;
    class ConfigurationPlugin;
    class Declaration;
    class Variable;
}
 
namespace alib::config::detail {
 
/// This struct is used as the reinterpretation type of generic pointers to ones reflecting
/// the effective  custom type of a configuration variable. While reinterpretation casts do not
/// need such templated model, its use increases readability of the code.
/// @tparam T The variable's data type.
template<typename T>    struct VData
{
    T               custom;   ///< The custom data that this object stores.
 
    /// Reinterprets the <c>this</c>-pointer to a <c>VData<TReinterpret>*</c> and returns
    /// member #custom.
    /// @tparam TReinterpret The type to reinterpret to.
    /// @return A reference to the custom data.
    template<typename TReinterpret> inline        TReinterpret&  As()
    { return reinterpret_cast<      VData<TReinterpret>*>(this)->custom;  }
 
    /// Reinterprets the <c>this</c>-pointer to a <c>const VData<TReinterpret>*</c> and returns
    /// member #custom.
    /// @tparam TReinterpret The type to reinterpret to.
    /// @return A const reference to the custom data.
    template<typename TReinterpret> inline  const TReinterpret&  As()      const
    { return reinterpret_cast<const VData<TReinterpret>*>(this)->custom;  }
};
 
/// Convenience definition for "invalid" data element which is used everywhere as a generic
/// pointer type, which is reinterpreted when to the target type, when needed.
using VDATA     =       VData<void*>;
 
} //namespace [alib::config::detail]
namespace alib::config {
 
/// Abstract, virtual struct which provides meta-information about types storable in the
/// \b StringTree nodes of class \alib{config;Configuration}. A pointer to a singleton of this
/// type is stored together with a reinterpreted pointer to the custom data record.
///
/// To register a custom data type with the configuration system, this type has to inherited and
/// all methods implemented. It is recommended to define custom derived types using macro
/// \ref ALIB_CONFIG_VARIABLE_DEFINE_TYPE.
/// Derived types are to be registered with the configuration instance by invoking
/// \alib{config;Configuration::RegisterType}.
///
/// @see Chapter \ref alib_config_types_custom of the Programmer's Manual of camp \alib_config.
struct VMeta
{
    /// Virtual empty destructor.
    virtual         ~VMeta() {}
 
    /// Abstract virtual method. Descendants need to return the type name they care of.<br>
    /// Types declared with macro \ref ALIB_CONFIG_VARIABLE_DEFINE_TYPE implement this method
    /// rightfully.
    /// @return The type's name.
    virtual String   typeName()                                                           const = 0;
 
    #if ALIB_DEBUG
    /// Abstract virtual method. Descendants need to return the <c>std::type_info&</c> received with
    /// <c>typeid()</c>. This method is available only in debug-compilations and is used to assert
    /// that the correct types are read from declared variables.<br>
    /// Types declared with macro \ref ALIB_CONFIG_VARIABLE_DEFINE_TYPE implement this method
    /// rightfully.
    /// @return The C++ type ID.
        virtual const std::type_info&   dbgTypeID()                                             = 0;
    #endif
 
    /// Abstract virtual method. Descendants need to return '<c>sizeof(T)</c>', with \p{T} being
    /// the custom type. Types declared with macro \ref ALIB_CONFIG_VARIABLE_DEFINE_TYPE implement
    /// this method rightfully. With that, it is also asserted that the alignment of the custom
    /// type is not greater than '<c>alignof(uint64_t)</c>', respectively not greater than
    /// what is specified with compiler symbol \ref ALIB_MONOMEM_POOLALLOCATOR_DEFAULT_ALIGNMENT.
    /// @return The size of the variable's content type.
    virtual size_t  size()                                                                      = 0;
 
    /// Abstract virtual method.  Descendants need to construct a custom instance at the given
    /// \p{memory}. This is done using a "placement-new" as follows:
    ///
    ///             new (memory) MyType();
    ///
    /// The pool allocator is \b not provided to allocate the custom type itself (this was already
    /// done before calling this method). Instead, it may be used to allocate members
    /// in the custom type. It may also be passed to the instance for further use during it's
    /// lifecycle. However, in this case chapter \ref alib_config_multithreading of the
    /// Programmer's Manual has to be considered.
    ///  @param memory  The pointer to the object of custom type.
    ///  @param pool    The object pool of the configuration. May be used to dispose pool objects.
    virtual void    construct(void* memory, PoolAllocator& pool)                                = 0;
 
    /// Abstract virtual method. Descendants need to destruct a custom instance at the given
    /// \p{memory}. This is done by calling the destructor as follows:
    ///
    ///             reinterpret_cast<MyTypeName*>(memory)->~MyTypeName();
    ///
    /// The pool allocator is \b not provided to free the custom type itself (this will be done
    /// automatically right after the call to this method). Instead, it may be used to free
    /// members of the type, which had been allocated during construction or during the use.
    ///
    /// \note
    ///   However, for most types included with \alib, for example \alib{AStringPA}, if used as a
    ///   member of the custom type, no special action need to be taken and it is sufficient to call
    ///   the destructor of the custom type. This is because these types take a copy of the pool on
    ///   construction and thus their destructor disposes allocated pool objects autonomously.
    ///   In other words, if only such members are used, then method \c construct has to be
    ///   implemented to pass the pool object to the members, but this method simply invokes the
    ///   destructor of the custom type as shown above.
    ///
    ///  @param memory  The place to construct the custom type at.
    ///  @param pool    The object pool of the configuration. May be used to allocate pool objects.
    virtual void    destruct(void* memory, PoolAllocator& pool)                                 = 0;
 
 
    /// Abstract virtual method. Descendants need to implement this method and de-serialize
    /// (aka parse) the custom type from the given string value.
    /// \attention
    ///   Types declared with macro \ref ALIB_CONFIG_VARIABLE_DEFINE_TYPE only declare this method.
    ///   An implementation needs to be provided in a compilation unit.
    ///
    /// @param data    A pointer to the user type which is to be initialized.
    /// @param cfg     The configuration that holds the variable.
    /// @param escaper An escaper to be used to convert external strings to C++ native strings.
    /// @param src     The source string to parse. This may be assigned to a value of type
    ///                \alib{strings;TSubstring} which already provides simple parser mechanics.
    ///                Likewise, \alib{strings::util;TTokenizer} might be an easy helper to be
    ///                used for parsing.
    virtual void    imPort( detail::VDATA*  data, Configuration& cfg, const StringEscaper& escaper,
                            const String&   src    )                                             =0;
 
    /// Abstract virtual method. Descendants need to implement this method. It is invoked when a
    /// variable is written into an external configuration source (in this case 'drain') or
    /// otherwise needs to be serialized.
    ///
    /// Note that export functions are allowed to add \alib{NEW_LINE} codes into the export string.
    /// This allows external configuration systems to nicely format their entries, in case those
    /// are human-readable. See chapter \ref alib_config_external_custom of the Programmer's
    /// Manual for more information.
    ///
    /// \attention
    ///   Types declared with macro \ref ALIB_CONFIG_VARIABLE_DEFINE_TYPE only declare this method.
    ///   An implementation needs to be provided in a compilation unit. Otherwise linking a software
    ///   fails.
    ///
    ///  @param data    A pointer to the user type which is to be serialized.
    ///  @param cfg     The configuration that holds the variable.
    ///  @param escaper An escaper to be used to escape strings.
    ///  @param dest    The destination string. Must not be reset prior writing, but appended.
    ///
    virtual void    exPort( detail::VDATA*   data, Configuration& cfg, const StringEscaper& escaper,
                            AString& dest )                                                      =0;
};
 
#define ALIB_CONFIG_VARIABLE_DEFINE_TYPE( Namespace, CPPName,CfgTypeString)                        \
namespace alib::config::detail {                                                                   \
struct VMeta_ ## CPPName : public VMeta                                                            \
{                                                                                                  \
         ALIB_API String                typeName ()                                                     const  override { return CfgTypeString; }      \
ALIB_DBG(ALIB_API const std::type_info& dbgTypeID()                                                            override { return typeid(Namespace  CPPName); }  )  \
         ALIB_API void                  construct(void* obj, PoolAllocator&)                                   override { new (obj) Namespace  CPPName(); }        \
         ALIB_API void                  destruct (void* obj, PoolAllocator&)                                   override { reinterpret_cast<Namespace  CPPName*>(obj)->~CPPName(); } \
         ALIB_API size_t                size     ()                                                            override { static_assert(alignof(Namespace CPPName) <= alib::PoolAllocator::MAX_ALIGNMENT); return (std::max)( sizeof(Namespace CPPName), sizeof(void*) ); } \
         ALIB_API void                  imPort   (VDATA*, Configuration&, const StringEscaper&, const String&) override;\
         ALIB_API void                  exPort   (VDATA*, Configuration&, const StringEscaper&,      AString&) override;\
};}
 
#define ALIB_CONFIG_VARIABLE_DEFINE_TYPE_WITH_POOL_CONSTRUCTOR( Namespace, CPPName,CfgTypeString)  \
namespace alib::config::detail {                                                                   \
struct VMeta_ ## CPPName : public VMeta                                                            \
{                                                                                                  \
         ALIB_API String                typeName ()                                                     const  override { return CfgTypeString; }      \
ALIB_DBG(ALIB_API const std::type_info& dbgTypeID()                                                            override { return typeid(Namespace  CPPName); }  )  \
         ALIB_API void                  construct(void* obj, PoolAllocator& pool)                              override { new (obj) Namespace  CPPName(pool); }        \
         ALIB_API void                  destruct (void* obj, PoolAllocator&)                                   override { reinterpret_cast<Namespace  CPPName*>(obj)->~CPPName(); } \
         ALIB_API size_t                size     ()                                                            override { static_assert(alignof(Namespace CPPName) <= alib::PoolAllocator::MAX_ALIGNMENT); return (std::max)( sizeof(Namespace CPPName), sizeof(void*) ); } \
         ALIB_API void                  imPort   (VDATA*, Configuration&, const StringEscaper&, const String&) override;\
         ALIB_API void                  exPort   (VDATA*, Configuration&, const StringEscaper&,      AString&) override;\
};}
 
 
#define ALIB_CONFIG_VARIABLE_REGISTER_TYPE(CPPName)                                                \
     GetConfig().RegisterType<alib::config::detail::VMeta_ ## CPPName>();
 
 
 
} // namespace [alib::config]
 
// =================================================================================================
// ==== Built-in Types
// =================================================================================================
 
namespace alib::config
{
    /// Variable content type used with boolean type <c>"B"</c>. When this type is imported,
    /// the value is tried to be parsed with the tokens in
    /// \alib{config;Configuration::BooleanTokens}. If successful, the index of the pair of
    /// <c>true/false</c>-tokens is stored in field #TokenIndex. When exported back to
    /// a configuration file or otherwise serialized or printed, then the right human-readable
    /// term, corresponding to the potentially now different #Value is used.
    struct Bool
    {
        /// The boolean value. Defaults to \c false.
        bool        Value      = false;
 
        /// The index in the \alib{config;Configuration::BooleanTokens;list of tokens} found when
        /// imported from a string. Can also be set programmatically to force a certain output
        /// "format". Defaults to \c -1 which indicates that the value was not parsed.
        /// On exporting, when \c -1, index \c 0 is used.
        int8_t      TokenIndex = -1;
 
        /// Assignment operator.
        /// @param newValue The value to set.
        /// @return The new value.
        bool operator=(bool newValue)                                    { return Value= newValue; }
 
        /// Implicit cast operator to \c bool.
        /// @return Returns the stored value.
        operator bool()                                                        const {return Value;}
    };
 
 
    /// Type definition used with configuration variables of type <c>"SV,"</c>, which stores a
    /// string array, imported by parsing a comma-separated string list.
    ///
    /// \attention
    ///   When exported, \alib{NEW_LINE} codes are added after each comma. This allows external
    ///   configuration systems to smoothly format longer lists of values. However, the
    ///   new line codes usually have to be detected with writing and eliminated on import.
    ///   Built-in type \alib{config;IniFile} processes such codes correctly.
    using StringVectorComma      = alib::StringVectorPA;
 
    /// Type definition used with configuration variables of type <c>"SV;"</c>, which stores a
    /// string array, imported by parsing a string list separated by character <c>';'</c>.
    ///
    /// \attention
    ///   When exported, \alib{NEW_LINE} codes are added after each semicolon. This allows external
    ///   configuration systems to smoothly format longer lists of values. However, the
    ///   new line codes usually have to be detected with writing and eliminated on import.
    ///   Built-in type \alib{config;IniFile} processes such codes correctly.
    using StringVectorSemicolon  = alib::StringVectorPA;
 
}  // namespace [alib::config]
 
 
 
 
#if !DOXYGEN
namespace alib::config::detail {
 
 
struct VMeta_integer : public VMeta
{
    ALIB_API String                 typeName()      const  override          { return A_CHAR("I"); }
ALIB_DBG(
    ALIB_API const std::type_info&  dbgTypeID()            override      { return typeid(integer); }
)
    ALIB_API void   construct(void* dest, PoolAllocator&)  override        { new (dest) integer(); }
    ALIB_API void   destruct (void*     , PoolAllocator&)  override                               {}
    ALIB_API size_t size()                                 override      { return sizeof(integer); }
    ALIB_API void   imPort( VDATA*, Configuration&, const StringEscaper&, const String& )  override;
    ALIB_API void   exPort( VDATA*, Configuration&, const StringEscaper&,      AString& )  override;
};
 
struct VMeta_float : public VMeta
{
    ALIB_API String                 typeName()      const  override          { return A_CHAR("F"); }
ALIB_DBG(
    ALIB_API const std::type_info&  dbgTypeID()            override       { return typeid(double); }
)
    ALIB_API void   construct(void* dest, PoolAllocator&)  override         { new (dest) double(); }
    ALIB_API void   destruct (void*     , PoolAllocator&)  override                               {}
    ALIB_API size_t size()                                 override       { return sizeof(double); }
    ALIB_API void   imPort( VDATA*, Configuration&, const StringEscaper&, const String& )  override;
    ALIB_API void   exPort( VDATA*, Configuration&, const StringEscaper&,      AString& )  override;
};
 
struct VMeta_String : public VMeta
{
    ALIB_API String                 typeName()      const  override          { return A_CHAR("S"); }
ALIB_DBG(
    ALIB_API const std::type_info&  dbgTypeID()            override    { return typeid(AStringPA); }
)
    ALIB_API void   construct(void* dest, PoolAllocator& pool)  override
    { new (dest) AStringPA(pool); }
    ALIB_API void   destruct (void* dest, PoolAllocator&)       override
    { reinterpret_cast<AStringPA*>(dest)->~AStringPA();  }
    ALIB_API size_t size()                                 override    { return sizeof(AStringPA); }
    ALIB_API void   imPort( VDATA*, Configuration&, const StringEscaper&, const String& )  override;
    ALIB_API void   exPort( VDATA*, Configuration&, const StringEscaper&,      AString& )  override;
};
 
} //namespace [alib::config::detail]
 
 
ALIB_CONFIG_VARIABLE_DEFINE_TYPE(                       alib::config::, Bool                 , A_CHAR("B"  ) )
ALIB_CONFIG_VARIABLE_DEFINE_TYPE(                       alib::boxing::, Box                  , A_CHAR("BOX") )
ALIB_CONFIG_VARIABLE_DEFINE_TYPE_WITH_POOL_CONSTRUCTOR( alib::        , AStringPA            , A_CHAR("S"  ) )
ALIB_CONFIG_VARIABLE_DEFINE_TYPE_WITH_POOL_CONSTRUCTOR( alib::config::, StringVectorComma    , A_CHAR("SV,") )
ALIB_CONFIG_VARIABLE_DEFINE_TYPE_WITH_POOL_CONSTRUCTOR( alib::config::, StringVectorSemicolon, A_CHAR("SV;") )
 
 
#endif // ALIB_DOX
#endif // HPP_ALIB_CONFIG_VMETA