serialization.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header file is part of module \alib_enums of the \aliblong.
///
/// \emoji :copyright: 2013-2024 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
#ifndef HPP_ALIB_ENUMS_SERIALIZATION
#define HPP_ALIB_ENUMS_SERIALIZATION 1
#pragma once
#include "alib/enums/records.hpp"
 
ALIB_ASSERT_MODULE(STRINGS)
 
#if ALIB_CAMP
#   include "alib/lang/resources/resources.hpp"
#endif
#include "alib/enums/bitwise.hpp"
#include "alib/strings/localstring.hpp"
 
#include "alib/lang/callerinfo_functions.hpp"
 
namespace alib {  namespace enums {
 
// #################################################################################################
// Parsing (Consume)
// #################################################################################################
 
 
#if DOXYGEN
//==================================================================================================
/// Consumes an element value of a C++ enumeration that is equipped with
/// \ref alib_enums_records "ALib Enum Records" of type \alib{enums;ERSerializable} (or of a derived
/// type) from a given \alib{strings;TSubstring;Substring}.
///
/// In debug-builds, the method asserts that at least one record is defined for \p{TEnum}.
///
/// For more information consult chapter
/// \ref alib_enums_records_details_serialization "4.3.1 Serialization/Deserialization" of the
/// Programmer's Manual of module \alib_enums.
///
/// \note
///   This namespace function is applicable to \alib{enums;T_EnumIsBitwise;bitwise enums} as well.
///   However, only one element name is parsed.
///   To parse multiple elements (ored to one resulting enum value), use sibling function
///   \alib{enums;ParseBitwise}.
///
/// @tparam TEnum              The enumeration type equipped with <b>ALib Enum Recorss</b>
///                            of type \alib{enums;ERSerializable}.
/// @tparam TChar              The character type of the \p{input} substring.
///                            Deduced by the compiler.
/// @tparam TSensitivity       The sensitivity of the comparison.
///                            Defaults to \b Case::Sensitive.
/// @tparam TTrimBeforeConsume Determines if the sub string should be (left-) trimmed before the
///                            consume operation. If so, in case of parsing failure, trimming is
///                            \b not restored.<br>
///                            Defaults to \b Whitespaces::Trim.
/// @param[in,out] input       The substring to parse. Passed as reference. On success, the
///                            substring will be shortened by the characters consumed. On failure
///                            only trimmed characters are consumed.
/// @param[out]    result      The result enum element given as reference.
/// @return \c true if an enum element was successfuly recognized, \c false otherwise.
///
/// ### Module Dependencies ###
///   This method is only available if \alib_strings is included in the \alibdist.
//==================================================================================================
template<typename    TEnum,
         typename    TChar,
         Case        TSensitivity        = Case::Ignore,
         Whitespaces TTrimBeforeConsume  = Whitespaces::Trim>
inline
bool    Parse(  strings::TSubstring<TChar>& input, TEnum&  result );
#else
#if defined(_MSC_VER)
#pragma warning( push )
#pragma warning( disable : 4127 )
#endif
 
template<typename    TEnum,
         typename    TChar,
         lang::Case        TSensitivity        = lang::Case::Ignore,
         lang::Whitespaces TTrimBeforeConsume  = lang::Whitespaces::Trim >
ATMP_T_IF(bool, EnumRecords<TEnum>::template AreOfType<ERSerializable>() )
Parse( strings::TSubstring<TChar>& input,  TEnum&  result )
{
    ALIB_ASSERT_ERROR( EnumRecords<TEnum>().begin() != EnumRecords<TEnum>().end(), "ENUMS",
                          NString128() << "No Enum Records for type <"
                                       << lang::DbgTypeDemangler( typeid(TEnum)).Get() << "> found." )
    if constexpr ( TTrimBeforeConsume == lang::Whitespaces::Trim )
        input.TrimStart();
 
    for( auto recordIt=   EnumRecords<TEnum>().begin() ;
              recordIt != EnumRecords<TEnum>().end()   ; ++recordIt  )
        if ( input.template ConsumePartOf<TSensitivity>( recordIt->EnumElementName,
                                                         recordIt->MinimumRecognitionLength ) > 0 )
        {
            result= recordIt.Enum();
            return true;
        }
    return false;
}
#endif
 
#if DOXYGEN
//==================================================================================================
/// Repeatedly invokes sibling function \alib{enums;Parse} until \p{delim} is not found.
/// The enum element values are or'ed in \p{result}.
///
/// In debug-builds, the method asserts that at least one record is defined for \p{TEnum}.
///
/// \note
///   This method is applicable only to \alib{enums;T_EnumIsBitwise;bitwise enums} that likewise
///   are equipped with \ref alib_enums_records "ALib Enum Records" of (derived) type
///   \alib{enums;ERSerializable}.
///
///
/// @tparam TEnum              The enumeration type equipped with <b>ALib Enum Records</b>
///                            of (derived) type \alib{enums;ERSerializable} and furthermore with a
///                            specialization of \alib{enums;T_EnumIsBitwise}.
/// @tparam TChar              The character type of the \p{input} substring.
///                            Deduced by the compiler.
/// @tparam TSensitivity       The sensitivity of the comparison.
///                            Defaults to \b Case::Ignore.
/// @tparam TTrimBeforeConsume Determines if the substring should be (left-) trimmed before and
///                            after each consume operation. If so, in case of parsing failure,
///                            trimming is \b not restored.<br>
///                            Defaults to \b Whitespaces::Trim.
/// @tparam delimiter          The delimiter character of the enum elements.<br>
///                            Defaults to <c>','</c>.
/// @tparam keepLastDelim      If \c true , the delimiter will be kept in this substring, if
///                            after the delimiter no further enum element was found.
///                            If \c false, the delimiter will be kept.<br>
///                            Defaults to \c true.
/// @param[in,out] input       The substring to parse. Passed as reference. On success, the
///                            substring will be shortened by the characters consumed. On failure
///                            only trimmed characters are consumed.
/// @param[out] result         The result enum element given as reference.
/// @return \c true if an enum element was successfuly recognized, \c false otherwise.
///
/// ### Module Dependencies ###
///   This method is only available if \alib_strings is included in the \alibdist.
//==================================================================================================
template<typename    TEnum,
         typename    TChar,
         Case        TSensitivity       = Case::Ignore,
         Whitespaces TTrimBeforeConsume = Whitespaces::Trim,
         TChar       delimiter          = ',',
         bool        keepLastDelim      = true                  >
inline
bool    ParseBitwise( strings::TSubstring<TChar>& input, TEnum&  result );
#else
template<typename          TEnum,
         typename          TChar,
         lang::Case        TSensitivity       = lang::Case::Ignore,
         lang::Whitespaces TTrimBeforeConsume = lang::Whitespaces::Trim,
         TChar             delimiter          = ',',
         bool              keepLastDelim      = true                  >
ATMP_T_IF(bool,      EnumRecords<TEnum>::template AreOfType<ERSerializable>()
                && T_EnumIsBitwise<TEnum>::value)
ParseBitwise( strings::TSubstring<TChar>& input, TEnum&  result )
{
    bool mResult= false;
    result= TEnum(0);
    strings::TSubstring<TChar> restoreBeforeDelim;
    if constexpr ( keepLastDelim )
        restoreBeforeDelim= input;
    for(;;)
    {
        if constexpr ( TTrimBeforeConsume == lang::Whitespaces::Trim )
            input.TrimStart();
        TEnum actEnum;
        if ( !Parse<TEnum, TChar, TSensitivity, TTrimBeforeConsume>( input, actEnum ) )
        {
            if constexpr ( keepLastDelim )
                input= restoreBeforeDelim;
            return mResult;
        }
        result|=  actEnum;
        mResult=  true;
        if constexpr ( TTrimBeforeConsume == lang::Whitespaces::Trim )
            input.TrimStart();
        if constexpr ( keepLastDelim )
            restoreBeforeDelim=  input;
 
        if( !input.template ConsumeChar<TSensitivity, TTrimBeforeConsume>( delimiter ) )
            return mResult;
 
    }
}
#if defined(_MSC_VER)
#pragma warning( pop )
#endif
 
#endif
 
#if DOXYGEN
//==================================================================================================
/// Convenience method that first uses \alib{enums;Parse} to try and read an element of a C++
/// enum. If this is not successful, an enum of type \alib{lang;Bool} is tried to be read.
/// If this is successful, depending on the value read, the \p{TEnum} values given
/// as parameters \p{falseValue} and \p{trueValue} are assigned.
/// Otherwise false is returned.
///
/// In debug-builds, the method asserts that at least one record is defined for \p{TEnum}.
///
/// \see
///   For more information consult chapter
///   \ref alib_enums_records_details_serialization of the
///   Programmer's Manual of module \alib_basecamp.
///
/// @tparam TEnum              The enumeration type equipped with <b>ALib Enum Records</b>
///                            of (derived) type \alib{enums;ERSerializable}.
/// @tparam TChar              The character type of the \p{input} substring.
///                            Deduced by the compiler.
/// @tparam TSensitivity       The sensitivity of the comparison.
///                            Defaults to \b Case::Ignore.
/// @tparam TTrimBeforeConsume Determines if the substring should be (left-) trimmed before and
///                            after each consume operation. If so, in case of parsing failure,
///                            trimming is \b not restored.<br>
///                            Defaults to \b Whitespaces::Trim.
/// @param  trueValue          The \p{TEnum} value to use in case of \c Bool::True was read.
/// @param  falseValue         The \p{TEnum} value to use in case of \c Bool::False was read.
/// @param[in,out] input       The substring to parse. Passed as reference. On success, the
///                            substring will be shortened by the characters consumed. On failure
///                            only trimmed characters are consumed.
/// @param[out] result         The result enum element given as reference.
/// @return \c true if an element of \p{TEnum} or \alib{lang;Bool} could be read,
///         \c false otherwise.
//==================================================================================================
template<typename    TEnum,
         typename    TChar,
         Case        TSensitivity       = Case::Ignore,
         Whitespaces TTrimBeforeConsume = Whitespaces::Trim >
inline
bool    ParseEnumOrTypeBool( strings::TSubstring<TChar>&   input,
                             TEnum&                        result,
                             TEnum                         falseValue,
                             TEnum                         trueValue         );
#else
template<typename          TEnum,
         typename          TChar,
         lang::Case        TSensitivity       = lang::Case::Ignore,
         lang::Whitespaces TTrimBeforeConsume = lang::Whitespaces::Trim >
ATMP_T_IF(bool, EnumRecords<TEnum>::template AreOfType<ERSerializable>() )
ParseEnumOrTypeBool( strings::TSubstring<TChar>&   input,
                     TEnum&                        result,
                     TEnum                         falseValue,
                     TEnum                         trueValue         )
{
    // first try to read a TEnum
    if( Parse<TEnum, TChar, TSensitivity, TTrimBeforeConsume>( input, result ) )
        return true;
 
    // if failed, read boolean
    lang::Bool boolEnum;
    if( enums::Parse<lang::Bool, TChar, TSensitivity, lang::Whitespaces::Keep>( input, boolEnum ) )
    {
        result= (boolEnum == lang::Bool::True) ? trueValue : falseValue;
        return true;
    }
 
    // failed
    return false;
}
#endif
 
}} // namespace [alib::enums]
 
 
 
// #################################################################################################
// Writing (T_Append<Enum>)
// #################################################################################################
 
namespace alib {  namespace strings {
 
// Faking specializations of T_Append for doxygen into namespace alib::strings::APPENDABLES
#if DOXYGEN
    namespace APPENDABLES {
#endif
 
 
#if DOXYGEN
/// Templated specialization of functor \alib{strings;T_Append} makes elements of C++ enumeration
/// type \p{TEnum} appendable to \alib{strings;TAString;AString} instances, if:
/// - Type \p{TEnum} is equipped with \ref alib_enums_records "ALib Enum Records" of type
///   \alib{enums;ERSerializable} (or a derived type ), and if:
/// - \b No specialization of TMP struct \alib{enums;T_EnumIsBitwise} exists for \p{TEnum}.
///   (For those, a different implementation of this functor is given.)
///
/// \note
///    The conditions are evaluated by the compiler using \c std::enable_if on optional template
///    parameter \p{TEnableIf} of unspecialized \alib{strings;T_Append}.
///
/// Member \b operator() writes the name of the given enumeration value to \p{target}.
/// As with all specializations of functor \b %T_Append, the use of it is done implicitly
/// with various interface method of class \alib{strings;TAString;AString}.
///
/// If furthermore TMP struct \alib{lang::resources;T_Resourced} is specialized for type \p{TEnum}
/// and an externalizd resouce string exists according to the specification described with
/// methods \alib{lang::resources;ResourcedType::TypeNamePrefix} and
/// \alib{lang::resources;ResourcedType::TypeNamePostfix} then these resourced strings are written
/// prior and after the enumeration element's name.
///
/// \see
///   - Sibling specialization
///     \alib{strings::APPENDABLES;T_Append<TEnumBitwise,TChar,TAllocator>}
///   - \ref alib_enums_records "ALib Enum Records".
///   - TMP struct \alib{lang::resources;T_Resourced}.
///   - Corresponding convenience type  \alib{lang::resources;ResourcedType}.
///   - Some sample code is given with documentation \ref alib_enums_records "ALib Enum Records".
///
/// @tparam TEnum      The enumeration type of the element that is to be appended to an \b %AString.
/// @tparam TChar      The character type of the target \b %AString.
/// @tparam TAllocator The allocator type of the target \b %AString, as prototyped with
///                    \alib{lang;Allocator}.
template<typename TEnum, typename TChar, typename TAllocator>
struct  T_Append<TEnum, TChar, TAllocator>
#else
template<typename TEnum, typename TChar, typename TAllocator>
struct  T_Append<TEnum, TChar,TAllocator,
                 ATMP_VOID_IF(    ATMP_ISOF( typename T_EnumRecords<TEnum>::Type, enums::ERSerializable )
                              && !T_EnumIsBitwise<TEnum>::value )  >
#endif
{
    //==============================================================================================
    /// Writes the name of the given enumeration \p{element} it to \p{target}.
    ///
    /// If available for \p{TEnum}, the resourced name
    /// \alib{lang::resources;ResourcedType::TypeNamePrefix;prefix} and
    /// \alib{lang::resources;ResourcedType::TypeNamePostfix;postfix} are written before and after the
    /// element's name.
    ///
    /// If no record exists for \p{element}, its underlying integral value is written.
    /// In debug-builds, the method asserts that at least one record is defined for \p{TEnum}.
    ///
    ///
    /// @param target    The \b AString that \p{element} is to be appended to.
    /// @param element   The enumeration element to append to \p{target}.
    //==============================================================================================
    void operator()( TAString<TChar,TAllocator>& target, TEnum element )
    {
        ALIB_ASSERT_ERROR( EnumRecords<TEnum>().begin() != EnumRecords<TEnum>().end(), "ENUMS",
                           NString128() << "No Enum Records for type <"
                                        << lang::DbgTypeDemangler( typeid(TEnum)).Get() << "> found." )
 
        IF_ALIB_CAMP( target << ResourcedType<TEnum>::TypeNamePrefix(); )
        auto* record= enums::TryRecord( element );
        if( record != nullptr )
            target << record->EnumElementName;
        else
            target << UnderlyingIntegral( element );
        IF_ALIB_CAMP( target << ResourcedType<TEnum>::TypeNamePostfix(); )
    }
};
 
 
#if DOXYGEN
/// Templated specialization of functor \alib{strings;T_Append} makes elements of C++ enumeration
/// type \p{TEnum} appendable to \alib{strings;TAString;AString} instances, if
/// - Type \p{TEnum} is equipped with \ref alib_enums_records "ALib Enum Records" of type
///   \alib{enums;ERSerializable} (or a derived type derived from \b ERSerializable), and
/// - \b A specialization of TMP struct \alib{enums;T_EnumIsBitwise} exists for \p{TEnum}.
///   (For non-bitwise types, a different implementation of this functor is given.)
///
/// \note
///    The conditions are evaluated by the compiler using \c std::enable_if on optional template
///    parameter \p{TEnableIf} of unspecialized \alib{strings;T_Append}.
///
/// Member \b operator() writes all value names corresponding to the bits set in \p{src},
/// separated by delimiter character <c>','</c>.
/// \note
///    For technical reasons, the delimiter is not adjustable. In cases a different delimter
///    is to be used, it needs to be replaced in the string after the value is written.
///
/// If the underlying integral value of a given enum element may be become \c 0, a corresponding
/// enum record associated to such non-bit value will be used if existent.
///
/// Furthermore, with bitwise type enums, the defined enum records may contain entries that
/// represent combinations of more than one integral bit. Such combination entries are supported
/// but have to be registered with class \alib{enums;EnumRecords} \b before the
/// standard single bit entries!
/// If combined bit values are matched, the corresponding element names that represent the
/// single bit values will not be written.
///
/// As a sample, lets consider a window manager software which has a scoped enum type representing
/// window states. Because a window might have more than one state, macro
/// \ref ALIB_ENUMS_MAKE_BITWISE is used to specialize TMP struct \alib{enums;T_EnumIsBitwise}.
/// Next, macro \ref ALIB_ENUMS_ASSIGN_RECORD used to associate the type with enum record type
/// \alib{enums;ERSerializable}:
///
///  \snippet "DOX_ENUMS.cpp"     DOX_ENUMS_BITWISE_DECLARATION
///
/// A window that is both, vertically and horizontally maximized, is considered to be "just"
/// \e maximized. Therefore, during bootstrap of the software, enum records that fetch that the
/// combination of states are defined \b before the single-state records:
///
///  \snippet "DOX_ENUMS.cpp"     DOX_ENUMS_BITWISE_DEFINITION
///
/// That is all that is needed! With this setup, the following code:
///  \snippet "DOX_ENUMS.cpp"     DOX_ENUMS_BITWISE_SAMPLE
///
/// produces this output:
///  \snippet "DOX_ENUMS_BITWISE_OUTPUT.txt"     OUTPUT
///
/// If furthermore TMP struct \alib{lang::resources;T_Resourced} is specialized for type \p{TEnum}
/// and an externalizd resouce string exists according to the specification described with
/// methods \alib{lang::resources;ResourcedType::TypeNamePrefix} and
/// \alib{lang::resources;ResourcedType::TypeNamePostfix} then these resourced strings are written
/// prior and after the enumeration element name(s).
///
/// \see
///   - Sibling specialization
///     \alib{strings::APPENDABLES;T_Append<TEnum,TChar,TAllocator>;T_Append<TEnum,TChar,TAllocator>}
///   - TMP struct \alib{lang::resources;T_Resourced}.
///   - Corresponding convenience type  \alib{lang::resources;ResourcedType}.
///   - Some sample code is given with documentation \ref alib_enums_records "ALib Enum Records".
///
/// # Reference Documentation #
/// @tparam TEnumBitwise  The bitwise defined enumeration type.
/// @tparam TChar         The character type of the target \b %AString.
/// @tparam TAllocator    The allocator type of the target \b %AString, as prototyped with
///                       \alib{lang;Allocator}.
template<typename TEnumBitwise, typename TChar>
struct  T_Append<TEnumBitwise, TChar,TAllocator>
#else
template<typename TEnum, typename TChar, typename TAllocator>
struct  T_Append<TEnum, TChar,TAllocator,
                 ATMP_VOID_IF(   ATMP_ISOF( typename T_EnumRecords<TEnum>::Type, enums::ERSerializable )
                              && T_EnumIsBitwise<TEnum>::value  )>
#endif
{
    //==============================================================================================
    /// Writes a comma-separated list of element names of the bitwise defined enumeration \p{TEnum}
    /// to \p{target}.
    ///
    /// In debug-builds, the method asserts that at least one record is defined for \p{TEnum}.
    /// It is furthermore asserted that all bits contained in \p{elements} have been "covered"
    /// by corresponding names.
    ///
    /// The enum records defined may aggregate several bits. Aggregations have to be defined
    /// before records that represent the corresponding single bits (or another subset of those).
    ///
    /// \see
    ///   This struct's documentation for more information and a sample.
    ///
    /// @param target    The \b AString that \p{elements} is to be appended to.
    /// @param elements  The enumeration element to append to \p{target}.
    //==============================================================================================
    void operator()( TAString<TChar,TAllocator>& target, TEnum elements )
    {
        ALIB_ASSERT_ERROR( EnumRecords<TEnum>().begin() != EnumRecords<TEnum>().end(), "ENUMS",
                           NString128() << "No Enum Records for type <"
                                        << lang::DbgTypeDemangler( typeid(TEnum)).Get() << "> found." )
 
        IF_ALIB_CAMP( target << ResourcedType<TEnum>::TypeNamePrefix(); )
 
        // check what has been covered and omit double entries
        TEnum covered= TEnum(0);
 
        // loop over entry 2 to end, check bit
        integer len= target.Length();
 
        for( auto recordIt=   EnumRecords<TEnum>().begin() ;
                  recordIt != EnumRecords<TEnum>().end()   ; ++recordIt  )
        {
            // no bits are set and this entry does not contain bits, then stop here
            if( recordIt.Integral() == 0 )
            {
                if( elements == TEnum(0) )
                {
                    target << recordIt->EnumElementName;
                    IF_ALIB_CAMP( target << ResourcedType<TEnum>::TypeNamePostfix(); )
                    return;
                }
            }
            else if(     HasBits( elements, recordIt.Enum() )
                     && !HasBits( covered , recordIt.Enum() )  )
            {
                covered|= recordIt.Enum();
                target << recordIt->EnumElementName << ',';
            }
        }
        len= target.Length() - len;
 
        // remove the last comma
        if( len != 0 )
            target.DeleteEnd( 1 );
 
        ALIB_ASSERT_ERROR( covered == elements, "ENUMS",
           NString128() << "Not all bits have been covered while writing bitset '"
                        << NFormat::Bin( elements ) << "' of enumeration type <"
                        << lang::DbgTypeDemangler( typeid(TEnum)).Get() << ">. Remaining bits are '"
                        << NFormat::Bin( covered & elements )  << "'."                        )
 
        IF_ALIB_CAMP( target << ResourcedType<TEnum>::TypeNamePostfix(); )
    }
};
 
 
#if DOXYGEN
} // namespace alib::strings[::appendables]
#endif
}} // namespace [alib::strings]
 
#include "alib/lang/callerinfo_methods.hpp"
 
#endif // HPP_ALIB_ENUMS_SERIALIZATION