propertyformatters.mpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of the \aliblong.
/// With supporting legacy or module builds, .mpp-files are either recognized by the build-system
/// as C++20 Module interface files, or are included by the
/// \ref alib_manual_modules_impludes "import/include headers".
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
#if !defined(ALIB_C20_MODULES) || ((ALIB_C20_MODULES != 0) && (ALIB_C20_MODULES != 1))
#   error "Symbol ALIB_C20_MODULES has to be given to the compiler as either 0 or 1"
#endif
#if ALIB_C20_MODULES
    module;
#endif
//========================================= Global Fragment ========================================
#include "alib/alib.inl"
#if ALIB_VARIABLES
#   include <unordered_map>
#endif
//============================================== Module ============================================
#if ALIB_C20_MODULES
    /// This is a <em><b>C++ Module</b></em> of the \aliblong.
    /// Due to the dual-compile option (either as C++20 Modules or using legacy C++ inclusion),
    /// the C++20 Module names are not of further interest or use.<br>
    /// In general, the names equal the names of the header files listed in the chapter
    /// \ref alib_manual_modules_impludes of the \alib User Manual.
    ///
    /// @see The documentation of the <em><b>"ALib Module"</b></em> given with the corresponding
    ///      Programmer's Manual \alib_format.
    export module ALib.Format.PropertyFormatters;
    #if ALIB_VARIABLES
        import    ALib.Lang;
        import    ALib.Strings;
        import    ALib.EnumRecords;
        import    ALib.Exceptions;
        import    ALib.Format;
        import    ALib.Format.PropertyFormatter;
        import    ALib.Variables;
    #endif
#else
#   if ALIB_VARIABLES
       #include  "ALib.Lang.H"
       #include  "ALib.Strings.H"
       #include  "ALib.EnumRecords.H"
       #include  "ALib.Exceptions.H"
       #include  "ALib.Format.H"
       #include  "ALib.Format.PropertyFormatter.H"
       #include  "ALib.Variables.H"
#   endif
#endif
 
//============================================= Exports ============================================
#if ALIB_VARIABLES
ALIB_EXPORT namespace alib { namespace  format {
 
//==================================================================================================
/// # Introduction # {#alib_ns_strings_propertyformatter_map_overview}
///
/// This template class provides a map of \alib{format;PropertyFormatter} objects that use
/// format strings which are defined by variables of a \alib{variables;Configuration}.
///
/// The use case is about having different versions of how an object is formatted and
/// to have these versions configurable to end users through the \alib variable system.
///
///\I{##############################################################################################}
/// # Sample # {#alib_ns_strings_propertyformatter_map_sample}
/// The concept is best explained by a code sample. From the documentation of class
/// \alib{format;PropertyFormatter}, we are using the sample setup:
///
/// \snippet "DOX_STRINGS.cpp"     DOX_STRINGS_PROPERTY_FORMATTER_1
/// \snippet "DOX_STRINGS.cpp"     DOX_STRINGS_PROPERTY_FORMATTER_2
/// \snippet "DOX_STRINGS.cpp"     DOX_STRINGS_PROPERTY_FORMATTER_3
///
/// Three different output formats, \e Short, \e Default and \e All should be supported
/// We define an enumeration type for this purpose and use macro \ref ALIB_ENUMS_ASSIGN_RECORD
/// to equip the enumeration with \ref alib_enums_records "ALib Enum Records" of type
/// \alib{variables;Declaration}.
/// In addition, macro \ref ALIB_RESOURCED is used to announce that the record data is defined using
/// resourced string data.
///
/// \snippet "DOX_STRINGS.cpp"     DOX_STRINGS_PROPERTY_FORMATTER_MAP_1
///
/// The following piece of code is to be performed during
/// \ref alib_mod_bs "bootstrapping".
/// We take the freedom to use the resource pool of camp \alib{camp;Basecamp}:
/// \snippet "DOX_STRINGS.cpp"     DOX_STRINGS_PROPERTY_FORMATTER_MAP_2
///
/// \note
///   The default value and variable comment string can be saved when we write back the variables
///   to a configuration file. This hints users to the fact that the output format is changeable,
///   i.e., when they open an INI-file. See chapter \ref alib_variables_external_ini of the Programmer's
///   Manual of camp \alib_variables for information about how to write built-in default variables like
///   this to an external configuration file.
///
/// In the next phase of bootstrapping, our enumeration records have to be initialized from the
/// resource pool:
///
/// \snippet "DOX_STRINGS.cpp"     DOX_STRINGS_PROPERTY_FORMATTER_MAP_22
///
/// With this in place, the \b %PropertyFormatters can be created and method
/// #Format can be used:
///
/// \snippet "DOX_STRINGS.cpp"     DOX_STRINGS_PROPERTY_FORMATTER_MAP_31
///
/// But we're still not fully done yet: The next goal is to have a lightweight object that is
/// \"\alib{strings;AppendableTraits;appendable}\" to objects of class
/// \alib{strings;TAString;AString}.
/// Such object is given with template type \alib{format;PropertyFormatterMapAppendable}.
/// It is a simple helper-struct that holds a reference to the formatter map, the format enumeration
/// value and the object to format.<br>
/// We define  a shortcut to the type with the right template arguments in place:
/// \snippet "DOX_STRINGS.cpp"     DOX_STRINGS_PROPERTY_FORMATTER_MAP_32
///
/// Now, we are set and can start using the formatter:
/// \snippet "DOX_STRINGS.cpp"     DOX_STRINGS_PROPERTY_FORMATTER_MAP_4
///
/// Running the code above produces the following output:
/// \verbinclude "DOX_STRINGS_PROPERTY_FORMATTER_MAP.txt"
///
/// To make the code even shorter, macros may be used:
/// \snippet "DOX_STRINGS.cpp"     DOX_STRINGS_PROPERTY_FORMATTER_MAP_5
///
/// The output is:
/// \verbinclude "DOX_STRINGS_PROPERTY_FORMATTER_MAP_2.txt"
///
///\I{#############################################################################################}
/// # Using The Appendable With Formatters # {#alib_ns_strings_propertyformatter_map_usingwithfmts}
/// The sample above showcased how to \ref alib_strings_assembly_ttostring "append" a lightweight
/// object of helper-class \alib{format;PropertyFormatterMapAppendable} to objects of class
/// \alib{strings;TAString;AString}.
/// A final step is to define the \ref alib::boxing "boxing" interface
/// \alib{boxing;FAppend} to make boxed objects of our helper-type applicable. As the type
/// itself is already appendable, we can use a built-in simple macro for that:
///
/// \snippet "DOX_STRINGS.cpp"     DOX_STRINGS_PROPERTY_FORMATTER_MAP_6
///
/// As described in the Programmer's Manual of module \alib_boxing, such interface definition
/// should be done only once and be placed in the bootstrap section of a process.
///
/// With this, using formatters in combination with our helper-struct works fine:
/// \snippet "DOX_STRINGS.cpp"     DOX_STRINGS_PROPERTY_FORMATTER_MAP_7
///
/// This code produces the following output.
/// \verbinclude "DOX_STRINGS_PROPERTY_FORMATTER_MAP_3.txt"
///
///\I{#############################################################################################}
/// # Module Dependencies #
/// This class is only available if module \alib_variables is included in the \alibbuild.
///
///\I{#############################################################################################}
/// # Reference Documentation #
/// @throws alib::format::FMTExceptions::MissingConfigurationVariable   \I{CLANGDUMMY}
///
/// @tparam  TFormattable  The type that is formatted.
/// @tparam  TVariables    The enumeration of variables which defines the format strings.
//==================================================================================================
template<typename TFormattable, typename TVariables >
class PropertyFormatters
{
    protected:
        /// The callback table for the property formatters (as given in the constructor).
        typename PropertyFormatter::TCallbackTable&         callbacks;
 
        /// The configuration used to load (and store the default) format strings from.
        variables::Configuration&                              config;
 
        /// The map of formatters
        std::unordered_map<TVariables, PropertyFormatter*>   formatters;
 
    public:
        /// The formatter (as given in the constructor).
        SPFormatter                                         Formatter;
 
    public:
        /// Constructor storing arguments in fields.
        /// All variables are declared within the given \p{configuration} and defined with their
        /// default values given with their declaration records (associated with \p{TVariables})
        /// and thus - if exported to a write-enabled external configuration source like,
        /// for example, \alib{variables;IniFileFeeder} - can be noted by the end-user to be
        /// configurable.
        ///
        /// Parameter \p{formatter} defaults to \c nullptr, which causes this constructor to create
        /// a clone of the static formatter given with \alib{format;Formatter::Default}.
        /// Note, that this is in contrast to the similar parameter of class
        /// \alib{format;PropertyFormatter}, which uses the default formatter itself
        /// in the case that \c nullptr is provided. The rationale behind creating a copy is that
        /// it is quite likely that the \b %PropertyFormatter objects created here are used
        /// nested within other format operations. This is especially true with the use of helper
        /// struct \alib{format;PropertyFormatterMapAppendable}. Now, nested formatting must
        /// not be done with the same formatter object.
        ///
        ///
        /// @param callbackTable  The callback table as specified with
        ///                       \alib{format;PropertyFormatter::TCallbackTable}.
        /// @param configuration  The configuration to load the format strings from (and to store
        ///                       the default values defined by the enum record of \p{TVariables}).
        /// @param formatter      The underlying formatter. Used for construction of
        ///                       \alib{format;PropertyFormatter}s.<br>
        ///                       Defaults to \c nullptr which denotes to create a copy of the
        ///                       static formatter given with \alib{format;Formatter::Default}.
        PropertyFormatters( typename PropertyFormatter::TCallbackTable&  callbackTable,
                            variables::Configuration&                       configuration,
                            SPFormatter                                  formatter      = nullptr )
        : callbacks( callbackTable )
        , config   ( configuration )
        , Formatter( formatter )
        {
            if ( Formatter == nullptr )
                Formatter= Formatter::Default->Clone();
 
            for( auto recordIt=   EnumRecords<TVariables>().begin() ;
                      recordIt != EnumRecords<TVariables>().end()   ; ++recordIt  )
            {
                Variable var(config, recordIt.Enum() );
            }
        }
 
        /// Destructor. Deletes the \alib{format;PropertyFormatter}s which got created.
        ~PropertyFormatters()
        {
            for( auto& formatter : formatters )
                delete formatter.second;
        }
 
        /// Chooses or - if not yet available - creates the right \alib{format;PropertyFormatter}
        /// and invokes its method \alib{format;PropertyFormatter::Format;Format}.
        ///
        /// @param target       The target string to write into.
        /// @param option       The user-defined formatting option.
        /// @param formattable  The custom object which is passed to the callback methods to collect
        ///                     the formatter arguments.
        void Format( AString& target, TVariables option, TFormattable& formattable )
        {
            auto formatter=  formatters.find( option );
            if( formatter == formatters.end() )
            {
                // find option in the table
                for( auto varEntryIt=  EnumRecords<TVariables>().begin() ;
                     varEntryIt     != EnumRecords<TVariables>().end()   ; ++varEntryIt  )
                    if( varEntryIt.Enum() == option )
                    {
                        Variable  vc(config, varEntryIt.Enum() );
                        if(    vc.GetPriority() == Priority::NONE
                            || vc.GetString().IsEmpty() )
                        {
                            throw Exception(ALIB_CALLER_NULLED, FMTExceptions::MissingConfigurationVariable,
                                            String256(vc) );
                        }
                        formatter= formatters.emplace(
                               std::make_pair( option,
                                               new PropertyFormatter( vc, callbacks, Formatter  ) )
                                                     ).first;
                        break;
                    }
 
                ALIB_ASSERT_ERROR( formatter != formatters.end(), "FORMAT",
                   "No entry for option {!Q<>} found in option table of PropertyFormatters.",
                   static_cast<std::underlying_type_t<TVariables>>(option) )
            }
 
            formatter->second->Format( target, formattable );
        }
 
}; // class PropertyFormatters
 
/// Helper-struct for users of class \alib{format;PropertyFormatters}.
/// Objects of this type are \alib{strings;AppendableTraits;appendable} to \b %AStrings.
///
/// A custom using statement should be used to access this type in a very short fashion,
/// to make "applications" to \b %AStrings a short call. Alternatively one ore more preprocessor
/// macros might even lead to shorter invocations. (See sample in class description).
 
template<typename TFormattable, typename TOptionEnum >
struct PropertyFormatterMapAppendable
{
    PropertyFormatters<TFormattable, TOptionEnum>&   FormatterMap; ///< The formatter map to use.
    TOptionEnum        Option;      ///< The format option defining the
                                    ///< \alib{format;PropertyFormatter} used.
    TFormattable&  Formattable;     ///< The object to be formatted.
 
 
    /// Constructor. Just saves the given parameters.
    /// @param pFormatterMap The \alib{format;PropertyFormatters} to use.
    /// @param pOption       The format option defining the
    ///                      \alib{format;PropertyFormatter} used.
    /// @param pFormattable  The object to be formatted.
    PropertyFormatterMapAppendable( PropertyFormatters<TFormattable, TOptionEnum>&  pFormatterMap,
                                    TOptionEnum                                        pOption,
                                    TFormattable&                                  pFormattable )
    : FormatterMap(pFormatterMap)
    , Option(pOption)
    , Formattable(pFormattable)
    {}
}; // struct PropertyFormatterMapAppendable
 
 
//##################################################################################################
// ##### AppendableTraits specialization
//##################################################################################################
 
} namespace strings {
 
#if DOXYGEN
    namespace APPENDABLES { // Documentation fake namespace
#endif
 
/// Specialization of functor \alib{strings;AppendableTraits} for helper-struct
/// \b %PropertyFormatterMapAppendable used to format objects with
/// \alib{format;PropertyFormatters}.
/// @tparam TFormattable The formattable object type.
/// @tparam TOptionEnum      The format option enumeration type.
template<typename TFormattable, typename TOptionEnum >
struct       AppendableTraits<typename  format::PropertyFormatterMapAppendable<TFormattable,TOptionEnum>, character, lang::HeapAllocator>
{
    /// Invokes the \alib{format;PropertyFormatters::Format} of the formatter map
    /// encapsulated in \p{src}.
    /// @param target  The target string.
    /// @param src     The helper-struct object.
    void operator()( TAString<character, lang::HeapAllocator>& target, const typename  format::PropertyFormatterMapAppendable<TFormattable,TOptionEnum>& src )
    {
        src.FormatterMap.Format( target, src.Option, src.Formattable );
    }
};
 
/// Specialization of functor \alib{strings;AppendableTraits} for pointers to helper-struct
/// \b %PropertyFormatterMapAppendable used to format objects with
/// \alib{format;PropertyFormatters}.
/// @tparam TFormattable The formattable object type.
/// @tparam TOptionEnum      The format option enumeration type.
template<typename TFormattable, typename TOptionEnum >
struct       AppendableTraits<typename  format::PropertyFormatterMapAppendable<TFormattable,TOptionEnum>*, character, lang::HeapAllocator>
{
    /// Invokes the \alib{format;PropertyFormatters::Format} of the formatter map
    /// encapsulated in \p{src}.
    /// @param target  The target string.
    /// @param src     Pointer to the helper-struct object.
    void operator()( TAString<character, lang::HeapAllocator>& target, const typename  format::PropertyFormatterMapAppendable<TFormattable,TOptionEnum>* src )
    {
        src->FormatterMap.Format( target, src->Option, src->Formattable );
    }
};
 
#if DOXYGEN
} // APPENDABLES documentation fake namespace
#endif
 
} // namespace alib[::strings]
 
 
/// Type alias in namespace \b alib.
template<typename TFormattable, typename TOptionEnum >
using PropertyFormatters=  format::PropertyFormatters<TFormattable, TOptionEnum>;
 
}  // namespace [alib]
 
#endif // ALIB_VARIABLES