formatterstdimpl.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::format {
 
//==================================================================================================
/// This is a base class for \alib built-in formatters. The class implements abstract method
/// #"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 #"PlaceholderAttributes;FormatSpec" to reflect
/// a format-specific portion the placeholder string.
/// It will be checked if the argument supports box-function #"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
///   #"FormatterPythonStyle" as the
///   "Python format mini language" supports such custom format specifications. Class
///   #"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 #"%^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, the method
///    #"writeStringPortion" is invoked for the rest of the string before 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 #".parsePlaceholder" providing that index.<br>
///    If the format syntax of the formatter contains a separated format specification string
///    (a substring of the placeholder string),  then the method may store such format
///    substring in field
///    #"PlaceholderAttributes;FormatSpec".
///
/// 7. Next, it is checked if an argument was set by #"%.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
///      #"PlaceholderAttributes;Arg" and
///      #"PlaceholderAttributes;ArgIdx"
///      already in #"%.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) before 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 #"FFormat" is defined for
///    #"PlaceholderAttributes;Arg".
///    In this case, the interface is invoked and \c true returned.
///
/// 10. Again, if a format specification was stored in
///     #"PlaceholderAttributes;FormatSpec"
///     method #".parseStdFormatSpec" is invoked which needs to set further attributes
///     in the #"%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
///     #"alib_mod_assert;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
  //################################################################################################
  public: // needs to be public because it is resourced in Basecamp
    /// Denotes the type of placeholders (respectively the values they represent).
    enum class PHTypes {
        NotGiven , ///< The default
        String   , ///< The 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 #"PlaceholderAttributes;FillChar"
                   ///< x-times. Used with python-style conversion <b>{!Fill[C]}</b>.
    };
 
  protected:
 
    /// 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 #"FormatterStdImpl::parsePlaceholder;2" if explicit indexing is used.
        /// Otherwise by #"FormatterStdImpl::format;2" which in turn invokes
        /// #"FormatterStdImpl::setArgument;2" if #"%FormatterStdImpl::parsePlaceholder" did not yet
        /// set it. Set to \c nullptr in the default implementation of
        /// #"FormatterStdImpl::resetPlaceholder".
        const Box*          Arg;
 
        /// The portion of the replacement field that represents the format specification.
        /// This field might be set in the method #"FormatterStdImpl::parsePlaceholder;2" and
        /// consumed in #"FormatterStdImpl::writeCustomFormat;2" and
        /// #"FormatterStdImpl::parseStdFormatSpec;2".<br>
        /// This field is \e nulled in the default implementation of
        /// #"FormatterStdImpl::resetPlaceholder".
        Substring           FormatSpec;
 
        /// The number format object for the actual attribute. With method
        /// #"FormatterStdImpl::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 #"PHTypes::NotGiven;2" in the default implementation of
        /// #"FormatterStdImpl::resetPlaceholder".
        PHTypes             Type;
 
        /// The alignment of the contents within a field.
        /// This is set to #"Alignment::Left" in the default implementation of
        /// #"FormatterStdImpl::resetPlaceholder".
        lang::Alignment     ValueAlignment;
 
        /// The positional index of the current
        /// #"Placeholder Arg;argument".
        /// This is set by #"FormatterStdImpl::parsePlaceholder;2" if explicit indexing is used.
        /// Otherwise by #"FormatterStdImpl::format" which in turn invokes
        /// #"FormatterStdImpl::setArgument" if #"%FormatterStdImpl::parsePlaceholder" did not
        /// yet set it.
        /// Set to \c -1 in the default implementation of #"FormatterStdImpl::resetPlaceholder".
        int                 ArgIdx;
 
        /// The index of the previous argument. Used when addressing the previous argument number
        /// (eg. in Java formatting style this could be "%<$...").
        /// This is set to #"PlaceholderAttributes;ArgIdx" in the default implementation of
        /// #"FormatterStdImpl::resetPlaceholder".
        int                 PreviousArgIdx;
 
        /// The (minimum) width of the output.
        /// This is set to \c 0 in the default implementation of
        /// #"FormatterStdImpl::resetPlaceholder".
        int                 Width;
 
 
        /// If not negative, the string representation of the argument is cut before
        /// 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 the default implementation of
        /// #"FormatterStdImpl::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 the default implementation of
        /// #"FormatterStdImpl::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 the default implementation of
        /// #"FormatterStdImpl::resetPlaceholder".
        bool                SignPaddingMode;
 
        /// Used with binary, octal, or hexadecimal output. Specifies that the output will be
        /// prefixed by strings found in fields
        /// #"TNumberFormat::BinLiteralPrefix",
        /// #"TNumberFormat::HexLiteralPrefix" or
        /// #"TNumberFormat::OctLiteralPrefix" which
        /// default to \c "0b", \c "0o" and \c "0x".
        /// Set to \c false in the default implementation of
        /// #"FormatterStdImpl::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 the default implementation of
        /// #"FormatterStdImpl::resetPlaceholder".
        bool                IsPercentage;
 
        /// The filling character for fields that are larger than their content.
        /// Method #"FormatterStdImpl::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 the default implementation of #"FormatterStdImpl::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 #"Formatter::Format".
    String                  formatString;
 
    /// The current (remaining) format string.
    Substring               parser;
 
    /// The target string as provided with method #"Formatter::Format".
    AString*                targetString;
 
    /// The list of arguments provided with method #"Formatter::Format".
    const BoxesMA*          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 #"Formatter::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_DLL
    virtual int             format( AString&        targetString,
                                    const String&   formatString,
                                    const BoxesMA&  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
    /// substring (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) before 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 #"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
    /// #"PlaceholderAttributes;Arg" supports an own format specifier
    /// by disposing about box-function #"FFormat".
    /// If so, the function is invoked with passing
    /// #"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 #"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 #"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
    ///   #"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
    /// #"PlaceholderAttributes;Arg" and
    /// #"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 #"%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::format]
 
ALIB_ENUMS_ASSIGN_RECORD(  alib::format::FormatterStdImpl::PHTypes, alib::enumrecords::ERSerializable )