formatterstdimpl.hpp

Go to the documentation of this file.

/** ************************************************************************************************
 * \file
 * This header file is part of sub-namespace #alib::lang::format of module \alib_basecamp of
 * the \aliblong.
 *
 * \emoji :copyright: 2013-2024 A-Worx GmbH, Germany.
 * Published under \ref mainpage_license "Boost Software License".
 **************************************************************************************************/
#ifndef HPP_ALIB_LANG_FORMAT_FORMATTER_STD
#define HPP_ALIB_LANG_FORMAT_FORMATTER_STD 1
 
#if !defined (HPP_ALIB_LANG_FORMAT_FORMATTER)
    #include "alib/lang/format/formatter.hpp"
#endif
 
 
namespace alib::lang::format {
 
/** ************************************************************************************************
 * This is a base class for \alib built-in formatters. The class implements abstract method
 * \alib{lang::format;Formatter::format} and introduces a set of
 * new abstract methods that have to be implemented by descendants.
 *
 * Derived types need to set default values for attributes in fields
 * #DefaultNumberFormat and #AlternativeNumberFormat within their constructor once - according
 * to defaults specified by the formatting syntax.
 * This should not be repeated per format operation. This way users of the type are allowed
 * to change such default setting (even if they this may the formatter deviates from the standard
 * it implements).
 *
 * All values aggregated in member #placeholder, together comprise the set of formatting attributes
 * which can be modified by placeholder semantics of the format string.
 * Derived types might use extended attributes.
 * Implementations provided with \alib define such extended attributes using a corresponding
 * additional inner type.
 *
 * When parsing a placeholder of a format string, abstract method #parsePlaceholder
 * may set field \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;FormatSpec} to reflect
 * a format-specific portion the placeholder string.
 * It will be checked if the argument supports box-function \alib{lang::format;FFormat},
 * and if so, this string is passed to the box-function.
 * If the argument does not support the interface, method #parseStdFormatSpec is invoked to
 * now parse this portion of the placeholder string in a default way.<br>
 * This concept allows customized format specifications for custom argument types! As an example,
 * a format specification for date/time argument types may support a custom format string
 * like \c "yyyy-MM-dd HH:mm:ss".
 * \note
 *   This concept is implemented with class
 *   \alib{lang::format;FormatterPythonStyle;FormatterPythonStyle} as the
 *   "Python format mini language" supports such custom format specifications. Class
 *   \alib{lang::format;FormatterJavaStyle;FormatterJavaStyle} does \b not support
 *   this mechanism.
 *
 * The following describes the formatting process in detail (the implementation of method #format)
 * and this way helps to understand what is required from the implementation of the abstract methods:
 *
 * 1.  Method parameters are stored in fields #targetString, #formatString, #arguments and
 *     #argOffset. This way, the parameters can be accessed from any implemented method without
 *     the need of passing them as parameters once more.<br>
 *     In addition, field #parser is initialized. This \b Substring is used to parse
 *     the format string. Parsed portions will be consumed from the front of the string.
 *     Finally fields #argsConsumed and #nextAutoIdx are initialized to value \c 0.
 *
 * 2.  <b>Start of the loop</b> to find and process placeholders in the format string.
 *
 * 3.  Abstract method #findPlaceholder is invoked. If this fails (no further placeholder was found)
 *     parsing stops. If, and only if, a placeholder was found before, method #writeStringPortion is
 *     invoked for the rest of the string prior to exiting the function.
 *
 * 4.  Method #writeStringPortion is invoked to write the current parser contents up to the
 *     placeholder position.
 *
 * 5.  Method #resetPlaceholder is invoked, to reset the attributes that will be parsed in the next
 *     step. The values that are set are implementation specific and need to reflect the
 *     default formatting options if no specific options are given in the format string.
 *
 * 6.  Abstract Method #parsePlaceholder is invoked to parse and consume tokens from string #parser
 *     and while doing this, to store the parsed format attributes in the fields with
 *     name prefix \c pha (or extended attributes of a derived formatter type).<br>
 *     If an argument (positional) index is found during parsing, then method
 *     #setArgument is to be invoked by abstract method \b %parsePlaceholder providing that index.<br>
 *     If the format syntax of the formatter contains a separated format specification string
 *     (a sub-string of the placeholder string),  then the method may store such format
 *     sub-string in field
 *     \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;FormatSpec}.
 *
 * 7.  Next, it is checked if an argument was set by \b %parsePlaceholder. If not, #setArgument
 *     is invoked providing \c -1 for the index to indicate auto-indexing.
 *     \note
 *       If auto-indexing should be implemented differently than done with default method
 *       #setArgument, then a custom formatter might either override the method or,
 *       in the case no index is given in the format string, just
 *       set fields
 *       \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;Arg} and
 *       \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;ArgIdx}
 *       already in \b %parsePlaceholder according to its own strategy
 *
 * 9.  Method #preAndPostProcess is invoked with parameter \p{startIdx} equalling \c -1
 *     (indicating pre-processing). This allows for example to insert tab fill-characters
 *     (tab stops) prior to writing the contents of the field.
 *
 * 9.  Method  #writeCustomFormat is invoked. This allows derived formatters to write arguments in a
 *     custom way. If the method returns \c true, the loop is continued ( &rarr; Step 4.). <br>
 *     The default implementation checks whether  box-function \alib{lang::format;FFormat} is defined for
 *     \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;Arg}.
 *     In this case, the interface is invoked and \c true returned.
 *
 * 10. Again, if a format specification was stored in
 *     \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;FormatSpec}
 *     method #parseStdFormatSpec is invoked which needs to set further attributes
 *     in the \b %Placeholder object according to the standard format specification of the formatter.
 *
 * 11. Now, as all fields that represent formatting attributes are well set (or kept with their
 *     defaulted value), method #checkStdFieldAgainstArgument is invoked.
 *     This method is virtual but not abstract. Its default implementation checks the
 *     placeholder attributes against the provided argument type and raises an error if the
 *     argument does not fit to the placeholder format specification.
 *
 * 12. Method #writeStdArgument is invoked. This method is virtual but not abstract.
 *     Its default implementation writes the argument value formatted according to the attribute
 *     fields.
 *
 * 13. Finally #preAndPostProcess is invoked with parameter \p{startIdx} pointing to the first
 *     character in #targetString of the argument written.
 *     Here, actions like case conversion might be done on the field written.
 *
 * 14. End of loop ( &rarr; Step 4.)
 **************************************************************************************************/
class FormatterStdImpl : public Formatter
{
    // #############################################################################################
    //  Placeholder types and attributes
    // #############################################################################################
    protected:
        /** Denotes the type of placeholders (respectively the values they represent). */
        enum class PHTypes
        {
            NotGiven , ///< The default
            String   , ///< %String type requested.
 
            Character, ///< Converts a given character or integer number to the corresponding
                       ///< unicode character before printing.
 
            IntBase10, ///< Outputs a given number in base 10. The default.
            IntBinary, ///< Outputs a given number in base 2.
            IntOctal , ///< Outputs a given number in base 8.
            IntHex   , ///< Outputs a given number in base 16.
 
            Float    , ///< Outputs a number in floating point format.
 
            Bool     , ///< Writes "true" or "false".
            HashCode , ///< Writes raw box data as hex.
 
            Fill     , ///< Writes \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;FillChar}
                       ///< x-times. Used with python-style conversion <b>{!Fill[C]}</b>.
        };
 
 
        /**
         * Collection of attributes related to the current placeholder processed.
         * \note
         *   The members of this inner class could as well be rightful members of the outer class.
         *   One object of this inner type is created as a normal member. Hence, the only
         *   reason for gathering the fields in this inner type is readability. (It has no influence
         *   on the compilation result.)
         *
         */
        struct PlaceholderAttributes
        {
            /** The current Box.
             *  This is set by #parsePlaceholder if explicit indexing is used. Otherwise by #format
             *  which invokes #setArgument if #parsePlaceholder did not set it yet.
             *  Set to \c nullptr in default implementation of #resetPlaceholder. */
            const Box*          Arg;
 
            /** The portion of the replacement field that represents the format specification.
             *  This field might be set in method #parsePlaceholder and consumed in methods
             *  #writeCustomFormat and #parseStdFormatSpec.<br>
             *  This field is \e nulled in default implementation of #resetPlaceholder. */
            Substring           FormatSpec;
 
            /** The number format object for the actual attribute. With method #resetPlaceholder values
             *  found in object #DefaultNumberFormat will be copied into this. */
            NumberFormat        NF;
 
            /** The type of the attribute as specified in the placeholder.
             *  This is set to
             *  \ref alib::lang::format::FormatterStdImpl::PHTypes::NotGiven "PHTypes::NotGiven"
             *  in default implementation of #resetPlaceholder. */
            PHTypes             Type;
 
            /** The alignment of the contents within a field.
             *  This is set to \alib{lang;Alignment;Alignment} in default
             *  implementation of #resetPlaceholder. */
            lang::Alignment     ValueAlignment;
 
            /** The positional index of the current
             *  \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;Arg;argument}.
             *  This is set by #parsePlaceholder if explicit indexing is used. Otherwise by #format
             *  which invokes #setArgument if #parsePlaceholder did not set it yet.
             *  Set to \c -1 in default implementation of #resetPlaceholder. */
            int                 ArgIdx;
 
            /** The index of the previous argument. Used when addressing previous argument
             *  number (eg. in Java formatting style this could be "%<$...").
             *  This is set to \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;ArgIdx}
             *  in default implementation of #resetPlaceholder. */
            int                 PreviousArgIdx;
 
            /** The (minimum) width of the output.
             *  This is set to \c 0 in default implementation of #resetPlaceholder. */
            int                 Width;
 
 
            /** If not negative, the string representation of the argument is cut prior to
             *  applying any field operation. It could be also named "precision", hence
             *  the number of characters to show - even if the field will be wider.
             *  This is set to \c -1 in default implementation of #resetPlaceholder. */
            int                 CutContent;
 
            /** This is the position in the format string where the actual type code was read from.
             *  Used for exception argument generation (FMTExceptions::IncompatibleTypeCode).
             *  If -1, the actual parse position is used.  */
            int                 TypeCodePosition;
 
            /** If true, an alignment was explicitly specified.
             *  This is set to \c false in default implementation of #resetPlaceholder. */
            bool                AlignmentSpecified;
 
            /** Forces the padding to be placed after the sign (if any) but before the digits.
             *  This is used for printing fields in the form ‘+000000120'.
             *  This alignment option is only valid for numeric types.
             *  Set to \c false in default implementation of #resetPlaceholder. */
            bool                SignPaddingMode;
 
            /** Used with binary, octal, or hexadecimal output. Specifies that the output will be
             *  prefixed by strings found in fields
             *  \alib{strings;TNumberFormat::BinLiteralPrefix;BinLiteralPrefix},
             *  \alib{strings;TNumberFormat::HexLiteralPrefix;HexLiteralPrefix} or
             *  \alib{strings;TNumberFormat::OctLiteralPrefix;OctLiteralPrefix} which
             *  default to  \c "0b", \c "0o" and \c "0x".
             *  Set to \c false in default implementation of #resetPlaceholder. */
            bool                WriteBinOctHexPrefix;
 
            /** Can be \c true for float-types. If \c true, the value is multiplied with 100 and
             *  a percentage symbol \c '\%' is printed after the value.
             *  Set to \c false in default implementation of #resetPlaceholder. */
            bool                IsPercentage;
 
            /** The filling character for fields that are larger than their content.
             *  Method #resetPlaceholder will set this to <c>' '</c>. */
            character           FillChar;
 
            /** This is the (format specific) type code of the current format operation.
             *  Used only to display error messages. May be used differently in derived classes.
             *  Is \e nulled in default implementation of #resetPlaceholder. */
            character           TypeCode;
        };
 
    // #############################################################################################
    //  protected fields
    // #############################################################################################
    protected:
        /** A string buffer, used for example, when writing aligned fields. */
        AString                 fieldBuffer;
 
        /** The name of the formatter as provided in the constructor. Used for generating
         *  error messages. */
        const String            formatterName;
 
        /** The format string as provided with method #Format. */
        String                  formatString;
 
        /** The current (remaining) format string. */
        Substring               parser;
 
        /** The target string as provided with method #Format. */
        AString*                targetString;
 
        /** The list of arguments provided with method #Format. */
        const Boxes*            arguments;
 
        /** The length of the target string before adding the formatted contents. */
        integer                 targetStringStartLength;
 
        /** The offset of the first argument to use. Provided with method #Format. */
        int                     argOffset;
 
        /** The number of arguments consumed by the current format string. */
        int                     argsConsumed;
 
        /** Counter for auto-indexed arguments. */
        int                     nextAutoIdx;
 
        /** If \c false the formatters specification expects argument to be numbered from
         * <c>0..N</c>. If \c true from <c>1..N</c>.                                      */
        bool                    argumentCountStartsWith1;
 
        /** If \c false the formatters specification expects argument to be numbered from
         * <c>0..N</c>. If \c true from <c>1..N</c>.                                     */
        PlaceholderAttributes   placeholder;
 
 
    // #############################################################################################
    //  Constructor/destructor
    // #############################################################################################
    public:
        /** ****************************************************************************************
         * Constructor.
         * @param formatterClassName The name of the derived class. Used to generate error messages
         *              including a link into the online documentation. (Therefore
         *              has to be the exact name.
         ******************************************************************************************/
                                FormatterStdImpl( const String& formatterClassName );
 
 
    // #############################################################################################
    //  Implementation of abstract interface of parent class Formatter
    // #############################################################################################
    protected:
 
        /** ****************************************************************************************
         * Implemented abstract format method which invokes a set of new abstract methods
         * as described in the main documentation of this class.
         *
         * @param targetString  An AString that takes the result.
         * @param formatString  The format string.
         * @param arguments     The objects to convert.
         * @param argOffset     The first object in \p{arguments} to use.
         *
         * @return The number of args consumed.
         ******************************************************************************************/
        ALIB_API
        virtual int             format( AString&        targetString,
                                        const String&   formatString,
                                        const Boxes&                        arguments,
                                        int                                 argOffset )    override;
 
 
    // #############################################################################################
    //  Introduction of new, partly abstract methods to be implemented (or optionally overwritten)
    //  by descendents.
    // #############################################################################################
    protected:
 
        /** ****************************************************************************************
         * Abstract method to search the next index of an argument placeholder in the remaining
         * sub-string (field #parser) of the format string.
         *
         * @return The index found, \c -1 if not found.
         ******************************************************************************************/
        virtual integer        findPlaceholder()                                                = 0;
 
        /** ****************************************************************************************
         * Overridable method to clean and reset the fields representing the current placeholder
         * attributes (those with name prefix \c pha) prior to parsing them.
         *
         * The default implementation sets all pha-fields as documented per field.
         * \note
         *   Derived classes (aka the specific formatter classes) are to invoke this (parent)
         *   implementation first and then to make some own adjustments to meet the defaults that
         *   apply to the formatting specification implemented by the derived class and - if this
         *   applies - also to reset extended attributes of the derived formatter type.
         ******************************************************************************************/
        virtual void            resetPlaceholder();
 
 
        /** ****************************************************************************************
         * Abstract method to parse the format definition at the start of string
         * #parser and set the placeholder attributes accordingly.<br>
         * Field \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;FormatSpec}
         * might be set by this method to portion of the placeholder format string.
         * If so, methods #writeCustomFormat and #parseStdFormatSpec are used to then parse
         * this portion of the placeholder string.
         *
         * @return \c true on success, \c false on errors.
         ******************************************************************************************/
        virtual bool            parsePlaceholder()                                              = 0;
 
        /** ****************************************************************************************
         * Virtual method that may write an argument using a custom method/format.
         * The default implementation checks if object
         * \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;Arg} supports an own format specifier
         * by disposing about box-function \alib{lang::format;FFormat}.
         * If so, the function is invoked with passing
         * \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;FormatSpec}, the result of the
         * formatting is written directly into the #targetString and \c true is returned.
         * The latter causes method #format (which invokes this method) to continue with the next
         * replacement field.<br>
         * If \c false is returned, method #format continues the field processing by invoking
         * #parseStdFormatSpec, #checkStdFieldAgainstArgument and #writeStdArgument.
         *
         * @return \c true if \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;Arg}
         *         was written, \c false otherwise.
         ******************************************************************************************/
        virtual bool            writeCustomFormat();
 
        /** ****************************************************************************************
         * Abstract method to parse the format specification for standard types (those that
         * are not processed by #writeCustomFormat). This method may be left empty
         * (just return constant \c true) if method #parsePlaceholder will never sets
         * field \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;FormatSpec}.
         *
         * @return \c true on success, \c false on errors.
         ******************************************************************************************/
        virtual bool            parseStdFormatSpec()                                            = 0;
 
        /** ****************************************************************************************
         * Virtual method invoked after #parseStdFormatSpec and before #writeStdArgument().
         * The default implementation checks the settings of placeholder attribute values
         * (fields with prefix \c pha), which were set by #parsePlaceholder and optionally by
         * #parseStdFormatSpec, against the type of the argument given.
         *
         * If type and format information is missing in the format string, reasonable default
         * values are set depending on the type of the argument.
         *
         * @throws
         *   If the argument type contradicts the replacement field type, exception
         *   \alib{lang::format::FMTExceptions;IncompatibleTypeCode} is thrown.
         *
         * @return \c true if OK, \c false if replacement should be aborted.
         ******************************************************************************************/
        virtual bool            checkStdFieldAgainstArgument();
 
        /** ****************************************************************************************
         * Virtual method to write the argument. The default implementation should be sufficient
         * for most derived formatter implementations, but of-course can be overridden and extended.
         ******************************************************************************************/
        virtual void            writeStdArgument();
 
        /** ****************************************************************************************
         * Virtual method to do pre- and post- processing of the field written.
         * Pre-processing could for example be adding tabulator spaces, letter case conversions,
         *
         * A negative given index \p{startIdx} indicates the pre-processing phase.
         * If \p{target} is given, this indicates an "intermediate phase": The argument has been
         * written, but no alignment or cutting has been done, yet. This phase should usually
         * be ignored, but is for example important for search and replacement actions.
         * If a field has a custom format implementation (e.g. time and date values), then
         * the intermediate phase is never called.
         *
         * \note
         *   The reason why this method is \b not implemented as two different ones is that
         *   derived classes might do some more complicated parsing of parts of the placeholder
         *   string in this method. In this case, the parsing is needed to be implemented only
         *   once, while the finally parsed commands are only conditionally executed depending
         *   if executed as pre or post phase.
         *
         * @param startIdx  If \c -1 pre-processing is indicated, otherwise post-processing and
         *                  the index of the start of the field written in #targetString is given.
         * @param target    The target string, only if different from field #targetString, which
         *                  indicates intermediate phase.
         * @return \c false, if the placeholder should be skipped (nothing is written for it).
         *         \c true otherwise.
         ******************************************************************************************/
        virtual bool           preAndPostProcess( integer   startIdx,
                                                  AString*  target  = nullptr )
        {
            (void) startIdx;
            (void) target;
            return true;
        }
 
        /** ****************************************************************************************
         * Helper method (overridable) that usually is invoked by the implementation of
         * #parsePlaceholder when an argument index is read from the format string,
         *
         * If this does not happen, method #format will invoke this method providing \c -1 for
         * value of parameter \p{pos} to automatically choose the next argument.
         *
         * Consequently, this method sets the fields
         * \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;Arg} and
         * \alib{lang::format::FormatterStdImpl::PlaceholderAttributes;ArgIdx}.
         * For auto-values, it increments #nextAutoIdx.
         * Finally, this method is responsible for the correct book-keeping of #argsConsumed.
         *
         * @param pos   The index of the argument.
         *              If \c -1 is given, the index is auto-incremented using field #nextAutoIdx.
         * @return \c true on success, \c false on errors.
         ******************************************************************************************/
        virtual bool            setArgument( int pos );
 
        /** ****************************************************************************************
         * Implementations of this abstract virtual method need to copy the given amount of
         * characters from sting #parser to \b AString #targetString. With that
         * "escaped" placeholder field characters (for example these are \c "{{" in python style
         * or \c "%%" in JAVA style) as well as other escape sequences defined with the format are
         * to be replaced with this method.
         *
         * @param length The number of characters to write.
         ******************************************************************************************/
        virtual void            writeStringPortion( integer length )                            = 0;
};
 
} // namespace [alib::lang::format]
 
#endif // HPP_ALIB_LANG_FORMAT_FORMATTER_STD