formatter.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_format of the \aliblong.
///
/// Copyright 2013-2026 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
ALIB_EXPORT namespace alib { namespace  format {
 
//==================================================================================================
/// This struct declares the signature of the #"alib_boxing_functions;box-function"
/// #"%FFormat". It can be implemented to write the contents of a boxed type the given
/// #"%AString" instance, in accordance with a custom format specification.
///
/// \see
///   For more information about this class see chapter
///   #"alib_format_custom_types" of the Programmer's Manual of module \alib_format_nl.
//==================================================================================================
struct FFormat {
    /// Signature of the invokable function.<br>
    /// Implementations write the content of \p{box} to the given #"%AString" object \p{target} in
    /// accordance to the type-specific format specification \p{formatSpec}.
    ///
    /// @param self       The box that the function was invoked on.
    /// @param formatSpec The specification of the format (type specific). If empty, a default
    ///                   specification string might have to be chosen.
    /// @param nf         A copy of the number format of the formatter (allowed to be modified).
    /// @param target     The AString object receiving the formatted string.
    using Signature = void (*) ( const Box& self, const String& formatSpec, NumberFormat& nf,
                                 AString& target );
};
 
 
// forward declaration
class Formatter;
 
} // namespace alib[::format]
 
/// A shared pointer to instances of #"format::Formatter;standard formatters".
/// \see Static member #"Formatter::DEFAULT;*".
using   SPFormatter        =  containers::SharedPtr<format::Formatter>;
 
namespace  format {
 
//==================================================================================================
/// This is an abstract base class to implement an \alib string formatter. A string formatter
/// uses a "format string" to transform arguments into formatted text. The format string defines
/// how the arguments are transformed by offering a "placeholder syntax".
///
/// With this information, it becomes clear that different formatter types (derived types that offer
/// a concrete placeholder syntax) all can have the same interface methods.
/// This class defines this abstract interface.
///
/// Built-in formatters derived from this class, are
/// #"FormatterPythonStyle" and
/// #"FormatterJavaStyle".
//==================================================================================================
class Formatter
#if ALIB_DEBUG_CRITICAL_SECTIONS
                 : public lang::DbgCriticalSections
#endif
{
 
  //################################################################################################
  //  Internal fields
  //################################################################################################
  protected:
    /// This allocator is (exclusively) used for field #"Formatter::boxes".
    MonoAllocator   allocator;
 
    /// A list of boxes. This is reset with every new invocation of variadic template method
    /// #".Format"
    BoxesMA         boxes;
 
    /// A buffer used for conversion of the next argument if it is not of a string-type.
    AString         formatStringBuffer;
 
        ALIB_DBG_PREVENT_RECURSIVE_METHOD_CALLS_MEMBER_DECL
 
  //################################################################################################
  //  Protected methods
  //################################################################################################
    /// Virtual method which is invoked with each invocation of #".Format".
    /// The default implementation does nothing.
    virtual void        initializeFormat()                                                        {}
 
    /// The abstract format method that needs to be implemented by descendants.
    /// Note that parameter \p{startIdx} and the demanded return value together comprise the
    /// possibility to use more than one formatter in parallel and to perform multiple format
    /// operations on suitable argument lists. This demands the implementation of this method to
    /// \b not copy the format string to the \p{target} in the case that no 'escape sequence'
    /// was found. For further information, see the general documentation of this class.
    ///
    /// @param target        The #"%AString" that takes the result.
    /// @param formatString  The format string.
    /// @param args          The objects to be used with formatters.
    /// @param startArgument The first object in \p{args} to convert.
    ///
    /// @return The number of args consumed.
    virtual int         format( AString&         target,
                                const String&    formatString,
                                const BoxesMA&   args,
                                int              startArgument )                                 =0;
 
    /// The format loop implementation. Searches format strings in \p{args} and tests
    /// if \c this or #".Next" is capable of processing it.
    ///
    /// @param target     An AString that takes the result.
    /// @param args       The objects to be used with formatters.
    /// @return A reference to this formatter to allow concatenated operations.
    template<typename TAllocator>
    Formatter&      formatLoop( AString& target, const boxing::TBoxes<TAllocator>& args );
 
    /// Writes the given string \p{escaped} to the target, converting escaped characters to their
    /// native values.
    /// @param target     The target.
    /// @param escaped    The string to write.
    static
    void      writeStringPortion( AString& target, const String& escaped );
 
 
  //################################################################################################
  //  public fields
  //################################################################################################
  public:
    /// Stores default attributes for formatting numbers.
    /// Likewise #"AlternativeNumberFormat", it usually is not used directly for formatting by
    /// descendants.
    /// Instead, at the beginning of parsing a next placeholder field, values are copied to
    /// a local copy. During the parsing process, values are then modified only in this local
    /// copy, probably taken from #"AlternativeNumberFormat".
    ///
    /// This object is to be initialized in the constructor (of descendants) once to meet the
    /// formatting defaults of the corresponding specification.
    /// If after construction, attribute values of this object are changed, such changes are
    /// applied to all number formatting.
    NumberFormat    DefaultNumberFormat;
 
    /// This number format is used to store alternative attributes. Likewise #"DefaultNumberFormat",
    /// it is never used directly for formatting.
    /// Instead, when processing the placeholder syntax, alternatives get copied from either this
    /// object or from #"DefaultNumberFormat".
    ///
    /// This object is initialized in the constructor (of descendants) once to meet the
    /// formatting defaults of the corresponding specification.
    ///
    /// With the implementations of this class provided with \alib, not all fields in this object
    /// are used. The fields used are:
    /// <p>
    /// - Locale-specific versions of floating point separators:
    ///   - #"TNumberFormat::DecimalPointChar;NumberFormat::DecimalPointChar"
    ///   - #"TNumberFormat::ThousandsGroupChar;NumberFormat::ThousandsGroupChar"
    ///
    ///   These are retrieved according to the current locale once in the constructor. To
    ///   change the locale, these fields can be changed.
    ///
    /// - Lower case versions of floating point literals:
    ///   - #"TNumberFormat::ExponentSeparator;NumberFormat::ExponentSeparator"
    ///   - #"TNumberFormat::INFLiteral;NumberFormat::INFLiteral"
    ///   - #"TNumberFormat::NANLiteral;NumberFormat::NANLiteral"
    ///
    /// - Lower case versions of prefix literals that indicate the base of integral values:
    ///   - #"TNumberFormat::BinLiteralPrefix;BinLiteralPrefix"
    ///   - #"TNumberFormat::HexLiteralPrefix;HexLiteralPrefix"
    ///   - #"TNumberFormat::OctLiteralPrefix;OctLiteralPrefix"
    NumberFormat    AlternativeNumberFormat;
 
    /// An optional, next formatter. If set, this formatter will be invoked for a format string
    /// that does not contain recognized placeholders.
    /// \attention
    ///    This field is public and not further maintained by this class. Setting the field lies
    ///    completely in the responsibility of the user. E.g., cyclic settings must be avoided.
    ///    Also, object life-cycle management is completely up to the user.
    SharedPtr<Formatter>  Next;
 
  //################################################################################################
  //  Constructor/destructor
  //################################################################################################
  public:
    /// Default Constructor.
    Formatter()
    :
    #if ALIB_DEBUG_CRITICAL_SECTIONS
      lang::DbgCriticalSections("Formatter")
    ,
    #endif
      allocator(ALIB_DBG("Formatter",) 1)
    , boxes( allocator )                                                                          {}
        
    /// Destructs an object of this class.
    /// Note that concatenated formatters are not deleted automatically.
    virtual        ~Formatter()                                                                   {}
 
  //################################################################################################
  //  Interface
  //################################################################################################
 
    /// Variadic template method that accepts a target #"%AString" and a list of arguments.
    /// This is a convenience method to allow single-line format invocations.
    ///
    /// \note
    ///   This method uses <c>static_assert</c> to disallow the invocation with one
    ///   variadic argument of type #"TBoxes" or a derived type.
    ///   This is to ensure that for these box containers, the more efficient method
    ///   #".FormatArgs(AString&, const boxing::TBoxes<TAllocator>&)"  is used.
    ///
    /// @tparam TArgs   Variadic template type list.
    /// @param target   An AString that takes the result.
    /// @param args     The variadic list of arguments to be used with formatters.
    /// @return A reference to this formatter to allow concatenated operations.
    template <typename... TArgs>
    Formatter&          Format( AString& target, TArgs&&... args ) {
        // assert that this method is not used with Boxes containers.
        // Those are to be processed with FormatArgs
        constexpr  bool Argument_has_type_Boxes=
              (sizeof...(TArgs) == 1)
           && (   std::is_base_of_v< Boxes  , std::decay< std::tuple_element<0, std::tuple<TArgs...>>>>
               || std::is_base_of_v< BoxesMA, std::decay< std::tuple_element<0, std::tuple<TArgs...>>>>
               || std::is_base_of_v< BoxesPA, std::decay< std::tuple_element<0, std::tuple<TArgs...>>>> );
        static_assert( !Argument_has_type_Boxes,
                       "To pass a container of type Boxes to a formatter, use method FormatArgs." );
 
        // create argument objects using implicit constructor invocation
        boxes.clear();
        boxes.Add( std::forward<TArgs>( args )... );
 
        // invoke format
        formatLoop( target, boxes );
        return *this;
    }
 
    /// Formats the internal list of arguments that is returned by methods #"GetArgContainer"
    /// and #".Reset".
    ///
    /// This method may be more efficient than using inlined variadic method #"^.Format"
    /// and should be preferred if:
    /// - Format arguments cannot be collected in a single invocation, for example, if those
    ///   are to be collected in a loop.
    /// - A sequence of different format operations is to be performed.
    ///
    /// @param target     An AString that takes the result.
    /// @return A reference to this formatter to allow concatenated operations.
    inline
    Formatter&          FormatArgs( AString& target );  // implementation below
 
 
    /// Same as Format(AString&) but allows specifying an external list of arguments instead of
    /// the internally allocated object, which is returned by methods #"GetArgContainer"
    /// and #".Reset".
    ///
    /// @param args       The arguments to be used with formatters.
    /// @param target     An AString that takes the result.
    /// @return A reference to this formatter to allow concatenated operations.
    template<typename TAllocator>
    Formatter&          FormatArgs( AString& target, const boxing::TBoxes<TAllocator>& args )
    {
        ALIB_DCS
        return formatLoop( target, args );
    }
 
 
    /// Clones and returns a copy of this formatter.
    ///
    /// If a formatter is attached to field #"Formatter::Next;*", it is
    /// cloned as well (recursively).
    ///
    /// @returns An object of the same (derived) type and the same custom settings.
    virtual SPFormatter  Clone()                                                                 =0;
 
    /// Clones the settings from the given formatter.
    /// @param reference  The formatter to copy settings from.
    ALIB_DLL
    virtual void        CloneSettings( Formatter& reference );
 
    /// Virtual method used to reset internal states.
    ///
    /// It is formatter-depended, which state information is reset. As a sample, derived type
    /// #"FormatterPythonStyle" clears its auto-tab
    /// and auto-width positions.
    ///
    /// The default implementation does nothing.
    /// @return An internally allocated container of boxes that may be used to collect
    ///         formatter arguments.
    virtual BoxesMA&    Reset()                            { ALIB_DCS boxes.clear(); return boxes; }
 
    /// Returns an empty vector of arguments, which can be passed to the format interface.<br>
    /// Note: This is nothing more than a recycling strategy.
    /// @return An internally allocated container of boxes that may be used to collect
    ///         formatter arguments.
    virtual BoxesMA&    GetArgContainer()                  { ALIB_DCS boxes.clear(); return boxes; }
 
 
  //################################################################################################
  // Static Interface (default formatter)
  //################################################################################################
    /// A publicly accessible static singleton instance which is can be freely used.
    /// Racing conditions in multithreaded applications have to be avoided by locking mutex
    /// #".DEFAULT_LOCK".
    ALIB_DLL
    static SPFormatter              DEFAULT;
 
    #if !ALIB_SINGLE_THREADED
        /// The lock to be set with multithreaded use of #".DEFAULT".
        /// If the configuration macro #"ALIB_DEBUG_CRITICAL_SECTIONS" is set, this lock will be
        /// attached to the instance of type #"lang::DbgCriticalSections" in #".DEFAULT" during
        /// bootstrap.
        /// Thus, an assertion will be raised if #".DEFAULT" is used without locking this.
        ///
        /// \par Availability
        ///   This object is available only if symbol #"ALIB_SINGLE_THREADED" is not set.
        ///
        /// @see Chapter #"alib_threads_intro_assert_locks" of the Programmer's Manual of
        ///      module \alib_threads.
        ALIB_DLL
        static threads::RecursiveLock   DEFAULT_LOCK;
    #endif
};
 
#if !DOXYGEN
template<> ALIB_DLL Formatter& Formatter::formatLoop( AString& target, const boxing::TBoxes<lang::HeapAllocator>& args );
template<> ALIB_DLL Formatter& Formatter::formatLoop( AString& target, const boxing::TBoxes<MonoAllocator>& args );
template<> ALIB_DLL Formatter& Formatter::formatLoop( AString& target, const boxing::TBoxes<PoolAllocator>& args );
#endif // !DOXYGEN
 
 
inline
Formatter&      Formatter::FormatArgs( AString& target )
{
    ALIB_DCS
    return formatLoop( target, boxes );
}
 
} // namespace alib[::format]
 
/// Type alias in namespace #"%alib".
using  Formatter           =   format::Formatter;
 
} // namespace [alib]