Description:

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 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.
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 "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 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:

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.
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 0.
Start of the loop to find and process placeholders in the format string.
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.
Method writeStringPortion is invoked to write the current parser contents up to the placeholder position.
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.
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 pha (or extended attributes of a derived formatter type).
If an argument (positional) index is found during parsing, then method setArgument is to be invoked by abstract method parsePlaceholder providing that index.
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 FormatSpec .
Next, it is checked if an argument was set by parsePlaceholder. If not, setArgument is invoked providing -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 Arg and ArgIdx already in parsePlaceholder according to its own strategy
Method preAndPostProcess is invoked with parameter startIdx equalling -1 (indicating pre-processing). This allows for example to insert tab fill-characters (tab stops) prior to writing the contents of the field.

Method writeCustomFormat is invoked. This allows derived formatters to write arguments in a custom way. If the method returns true, the loop is continued ( → Step 4.).
The default implementation checks whether box-function FFormat is defined for Arg . In this case, the interface is invoked and true returned.
Again, if a format specification was stored in FormatSpec method parseStdFormatSpec is invoked which needs to set further attributes in the Placeholder object according to the standard format specification of the formatter.
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.
Method writeStdArgument is invoked. This method is virtual but not abstract. Its default implementation writes the argument value formatted according to the attribute fields.
Finally preAndPostProcess is invoked with parameter startIdx pointing to the first character in targetString of the argument written. Here, actions like case conversion might be done on the field written.
End of loop ( → Step 4.)

Definition at line 129 of file formatterstdimpl.hpp.

#include <formatterstdimpl.hpp>

Inheritance diagram for FormatterStdImpl:

[legend]

Collaboration diagram for FormatterStdImpl:

[legend]

Inner Type Index:
struct	PlaceholderAttributes

Public Method Index:
	FormatterStdImpl (const String &formatterClassName)

Public Method Index: inherited from Formatter
virtual	~Formatter ()

ALIB_API Boxes &	Acquire (const NCString &dbgFile, int dbgLine, const NCString &dbgFunc)

virtual Formatter *	Clone ()=0

virtual ALIB_API void	CloneSettings (Formatter &reference)

int	CountAcquirements () const

template<typename... TArgs>
Formatter &	Format (AString &target, TArgs &&... args)
	ALIB_THREADS.

ALIB_API Formatter &	FormatArgs (AString &target)

Formatter &	FormatArgs (AString &target, const Boxes &args)

ALIB_API void	Release ()
	defined(ALIB_DOX)

ALIB_API void	ReplaceDefault (Formatter *newFormatter)

Public Method Index: inherited from ThreadLock
ALIB_API	ThreadLock (lang::Safeness safeness=lang::Safeness::Safe)

ALIB_API	~ThreadLock ()

ALIB_API void	Acquire (const NCString &dbgFile, int dbgLine, const NCString &dbgFunc)

int	CountAcquirements () const

Thread *	GetOwner () const

lang::Safeness	GetSafeness () const

bool	IsOwnedByCurrentThread () const

ALIB_API void	Release ()
	defined(ALIB_DOX)

ALIB_API void	SetSafeness (lang::Safeness safeness)

bool	WillRelease () const

Additional Inherited Members
Public Static Method Index: inherited from Formatter
static SPFormatter	AcquireDefault (const NCString &dbgFile, int dbgLine, const NCString &dbgFunc)

static SPFormatter	GetDefault ()

Public Field Index: inherited from Formatter
NumberFormat	AlternativeNumberFormat

NumberFormat	DefaultNumberFormat

std::shared_ptr< Formatter >	Next

Public Field Index: inherited from ThreadLock
NCString	DbgOwnerFile =nullptr

NCString	DbgOwnerFunc =nullptr

int	DbgOwnerLine

uint16_t	DbgRecursionWarningThreshold =10

integer	DbgWarningAfterWaitTimeInMillis =2000L

Enumeration Details:

◆ PHTypes

enum class PHTypes

strongprotected

Denotes the type of placeholders (respectively the values they represent).

Enumerator
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 FillChar x-times. Used with python-style conversion {!Fill[C]}.

Definition at line 136 of file formatterstdimpl.hpp.

Field Details:

◆ argOffset

int argOffset

protected

The offset of the first argument to use. Provided with method Format.

Definition at line 287 of file formatterstdimpl.hpp.

◆ argsConsumed

int argsConsumed

protected

The number of arguments consumed by the current format string.

Definition at line 290 of file formatterstdimpl.hpp.

◆ argumentCountStartsWith1

bool argumentCountStartsWith1

protected

If false the formatters specification expects argument to be numbered from 0..N. If true from 1..N.

Definition at line 297 of file formatterstdimpl.hpp.

◆ arguments

const Boxes* arguments

protected

The list of arguments provided with method Format.

Definition at line 281 of file formatterstdimpl.hpp.

◆ fieldBuffer

AString fieldBuffer

protected

A string buffer, used for example, when writing aligned fields.

Definition at line 265 of file formatterstdimpl.hpp.

◆ formatString

String formatString

protected

The format string as provided with method Format.

Definition at line 272 of file formatterstdimpl.hpp.

◆ formatterName

const String formatterName

protected

The name of the formatter as provided in the constructor. Used for generating error messages.

Definition at line 269 of file formatterstdimpl.hpp.

◆ nextAutoIdx

int nextAutoIdx

protected

Counter for auto-indexed arguments.

Definition at line 293 of file formatterstdimpl.hpp.

◆ parser

Substring parser

protected

The current (remaining) format string.

Definition at line 275 of file formatterstdimpl.hpp.

◆ placeholder

PlaceholderAttributes placeholder

protected

If false the formatters specification expects argument to be numbered from 0..N. If true from 1..N.

Definition at line 301 of file formatterstdimpl.hpp.

◆ targetString

AString* targetString

protected

The target string as provided with method Format.

Definition at line 278 of file formatterstdimpl.hpp.

◆ targetStringStartLength

integer targetStringStartLength

protected

The length of the target string before adding the formatted contents.

Definition at line 284 of file formatterstdimpl.hpp.

Constructor(s) / Destructor Details::

◆ FormatterStdImpl()

FormatterStdImpl ( const String & formatterClassName )

Constructor.

Parameters

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.

Definition at line 43 of file formatterstdimpl.cpp.

Here is the call graph for this function:

Method Details:

◆ checkStdFieldAgainstArgument()

bool checkStdFieldAgainstArgument ( )

protectedvirtual

Virtual method invoked after parseStdFormatSpec and before writeStdArgument(). The default implementation checks the settings of placeholder attribute values (fields with prefix 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.

Exceptions

If	the argument type contradicts the replacement field type, exception IncompatibleTypeCode is thrown.

Returns: true if OK, false if replacement should be aborted.

Reimplemented in FormatterJavaStyle, and FormatterPythonStyle.

Definition at line 181 of file formatterstdimpl.cpp.

Here is the call graph for this function:

◆ findPlaceholder()

virtual integer findPlaceholder ( )

protectedpure virtual

Abstract method to search the next index of an argument placeholder in the remaining sub-string (field parser) of the format string.

Returns: The index found, -1 if not found.

Implemented in FormatterJavaStyle, and FormatterPythonStyle.

◆ format()

int format	(	AString &	targetString,
		const String &	formatString,
		const Boxes &	arguments,
		int	argOffset )

overrideprotectedvirtual

Implemented abstract format method which invokes a set of new abstract methods as described in the main documentation of this class.

Parameters

targetString	An AString that takes the result.
formatString	The format string.
arguments	The objects to convert.
argOffset	The first object in arguments to use.

Returns: The number of args consumed.

Implements Formatter.

Definition at line 55 of file formatterstdimpl.cpp.

Here is the call graph for this function:

◆ parsePlaceholder()

virtual bool parsePlaceholder ( )

protectedpure virtual

Abstract method to parse the format definition at the start of string parser and set the placeholder attributes accordingly.
Field 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.

Returns: true on success, false on errors.

Implemented in FormatterJavaStyle, and FormatterPythonStyle.

◆ parseStdFormatSpec()

virtual bool parseStdFormatSpec ( )

protectedpure virtual

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 true) if method parsePlaceholder will never sets field FormatSpec .

Returns: true on success, false on errors.

Implemented in FormatterJavaStyle, and FormatterPythonStyle.

◆ preAndPostProcess()

virtual bool preAndPostProcess	(	integer	startIdx,
		AString *	target = nullptr )

inlineprotectedvirtual

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 startIdx indicates the pre-processing phase. If 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 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.

Parameters

startIdx	If `-1` pre-processing is indicated, otherwise post-processing and the index of the start of the field written in targetString is given.
target	The target string, only if different from field targetString, which indicates intermediate phase.

Returns: false, if the placeholder should be skipped (nothing is written for it). true otherwise.

Reimplemented in FormatterJavaStyle, and FormatterPythonStyle.

Definition at line 456 of file formatterstdimpl.hpp.

◆ resetPlaceholder()

void resetPlaceholder ( )

protectedvirtual

Overridable method to clean and reset the fields representing the current placeholder attributes (those with name prefix 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.

Reimplemented in FormatterJavaStyle, and FormatterPythonStyle.

Definition at line 124 of file formatterstdimpl.cpp.

Here is the call graph for this function:

◆ setArgument()

bool setArgument ( int pos )

protectedvirtual

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 -1 for value of parameter pos to automatically choose the next argument.

Consequently, this method sets the fields Arg and ArgIdx . For auto-values, it increments nextAutoIdx. Finally, this method is responsible for the correct book-keeping of argsConsumed.

Parameters

pos	The index of the argument. If `-1` is given, the index is auto-incremented using field nextAutoIdx.

Returns: true on success, false on errors.

Definition at line 147 of file formatterstdimpl.cpp.

Here is the call graph for this function:

◆ writeCustomFormat()

bool writeCustomFormat ( )

protectedvirtual

Virtual method that may write an argument using a custom method/format. The default implementation checks if object Arg supports an own format specifier by disposing about box-function FFormat . If so, the function is invoked with passing FormatSpec , the result of the formatting is written directly into the targetString and true is returned. The latter causes method format (which invokes this method) to continue with the next replacement field.
If false is returned, method format continues the field processing by invoking parseStdFormatSpec, checkStdFieldAgainstArgument and writeStdArgument.

Returns: true if Arg was written, false otherwise.

Definition at line 517 of file formatterstdimpl.cpp.

Here is the call graph for this function:

◆ writeStdArgument()

void writeStdArgument ( )

protectedvirtual

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.

Definition at line 258 of file formatterstdimpl.cpp.

Here is the call graph for this function:

◆ writeStringPortion()

virtual void writeStringPortion ( integer length )

protectedpure virtual

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 "{{" in python style or "%%" in JAVA style) as well as other escape sequences defined with the format are to be replaced with this method.

Parameters

length The number of characters to write.

Implemented in FormatterJavaStyle, and FormatterPythonStyle.

The documentation for this class was generated from the following files:

Description:

Inner Type Index:

Public Method Index:

Additional Inherited Members

Enumeration Details:

◆ PHTypes

Field Details:

◆ argOffset

◆ argsConsumed

◆ argumentCountStartsWith1

◆ arguments

◆ fieldBuffer

◆ formatString

◆ formatterName

◆ nextAutoIdx

◆ parser

◆ placeholder

◆ targetString

◆ targetStringStartLength

Constructor(s) / Destructor Details::

◆ FormatterStdImpl()

Method Details:

◆ checkStdFieldAgainstArgument()

◆ findPlaceholder()

◆ format()

◆ parsePlaceholder()

◆ parseStdFormatSpec()

◆ preAndPostProcess()

◆ resetPlaceholder()

◆ setArgument()

◆ writeCustomFormat()

◆ writeStdArgument()

◆ writeStringPortion()