FormatterPythonStyle Class Reference

Inheritance diagram for FormatterPythonStyle:

Collaboration diagram for FormatterPythonStyle:

Class Description

---

Implements a Formatter according to the formatting standards of the Python language.

Note

Inherited, public fields of parent class FormatterStdImpl provide important possibilities for changing the formatting behavior of instances of this class. Therefore, do not forget to consult the parent classes documentation.

In general, the original Python specification is covered quite well. However, there are some differences, some things are not possible (considering python being a scripting language) but then there are also found some very helpful extensions to that standard. Instead of repeating a complete documentation, please refer to the Python Documentation as the foundation and then take note of the following list of differences, extensions and general hints:

• General Notes: Python defines a placeholder field as follows

     "{" [field_name] ["!" conversion] [":" format_spec] "}"
  

  • By the nature of the implementation language of this class, field_name can not be the name of an identifier, an attribute name or an array element index. It can only be a positional argument index.
  • Python formatter does not allow to switch from automatic field indexing to explicit indexing. This implementation does allow it. The automatic index always starts with index 0 and is incremented each time automatic indexing is used. Occurrences of explict indexing have no influence on the automatic indexing.
  • This formatter is less strict in respect to the order of the format symbols. E.g. it allows {:11.5,} where Python allows only {:11,.5}
  • With this class being derived from FormatterStdImpl, features of the parent are available to this formatter as well. This is especially true and sometimes useful in respect to setting default values number formatting. For example, this allows to modify all number output without explicitly repeating the settings in each placeholder of format strings. Other options for example the grouping characters used with hexadecimal numbers, can not be even changed with the Python Style formatting options. The only way of doing so is modifying the properties of the formatter object prior to the format operation.
  • Nested replacements in format specification fields are (by nature of this implementation language) not supported.

• Binary, Hexadecimal and Octal Numbers: Binary, hexadecimal and octal output is cut in size (!) when a field width is given that is smaller than the resulting amount of digits of the number arguments provided.

  Note

  This implies that a value written might not be equal to the value given. This is not a bug but a design decision. The rational behind this is that with this behavior, there is no need to mask lower digits when passing the arguments to the format invocation. In other words, the formatter "assumes" that the given field width indicates that only a corresponding number of lower digits are of interest.

• The number grouping option (',') can also be used with binary, hexadecimal and octal output. The types support different grouping separators for nibbles, bytes, 16-bit and 32-bit words. Changing the separator symbols, is not possible with the format fields of the format strings (if it was, this would become very incompatible to Python standards). Changes have to be made prior to the format operation by modifying field alternativeNumberFormat which is provided through parent class FormatterStdImpl.

• Alternative form ('#') adds prefixes as specified in members

  • binLiteralPrefix,
  • hexLiteralPrefix and
  • octLiteralPrefix.

  For upper case formats, those are taken from field defaultNumberFormat, for lower case formats from alternativeNumberFormat. However, in alignment with the Python specification, both default to lower case literals "0b", "0o" and "0x". All defaults may be changed by the user.

• Floating point values:
  • If floating point values are provided without a type specification in the format string, then all values of defaultNumberFormat are used to format the number
  • For lower case floating point format types ('f' and 'e'), the values specified in attributes ExponentSeparator, NANLiteral and INFLiteral of object alternativeNumberFormat are used. For upper case types ('F' and 'E') the corresponding attributes in defaultNumberFormat apply.
  • Fixed point formats ('f' and 'F' types) are not supported to use arbitrary length. See class NumberFormat for the limits. Also, very high values and values close to zero may be converted to scientific format. Finally, if flag forceScientific of field defaultNumberFormat is true, types 'f' and 'F' behave like types 'e' and 'E'.
  • When both, a width and a precision is given, then the precision determines the fractional part, even if the type is 'g' or 'G'. This is different than specified with Python formatter, which uses precision as the overall width in case of types 'g' or 'G'.
  • Python specifies the formatting option '#' ("alternate form") for floating point values to not omit trailing zeros of the fractional part even if a fractional width was given. However, in scientific notation and in percentage output (type code '%'), python never omits trailing zeros.
    This implementation omits trailing zeros also in scientific notation and percentage output. Therefore, when defining fields with dedicated fractional part width, it is recommended to use the alternate form by adding '#' the the format specification. This way, all numbers written have the same size, independent of the value of their fractional part.
  • The 'general format' type for floats, specified with 'g' or 'G' in the python implementation limits the precision of the fractional part, even if precision is not further specified. This implementation does limit the precision only if type is 'f' or 'F'.

• String Conversion:
  If type 's' (or no type) is given in the format_spec of the replacement field, a string representation of the given argument is used. In Java and C# such representation is received by invoking Object.[t|T]oString(). Consequently, to support string representations of custom types, in these languages the corresponding [t|T]oString() methods of the type have to be implemented.

  In this C# implmentation, for the string representation the formatter invokes method Object.ToString. To support string representations for custom types, this method needs to be implemented for the type in question.

• Boolean output:
  In extension (and deviation) of the Python specification, format specification type 'B' is implemented. The word "true" is written if the given value represents a boolean true value, "false" otherwise.

  In the C# language implementation of ALib, in the case the argument is of type boolean, the its value is used. If the argument is an integral type, it is true if the value is not equal to 0. Otherwise, the value is true if the argument is not null.

• Hash-Value Output:
  In extension (and deviation) of the Python specification, format specification type 'h' and its upper case version 'H' is implemented. The hash-values of the argument object is written in hexadecimal format. Options of the type are identical to those of 'x', respectively 'X'.

• Custom Format Specifications:
  With Python formatting syntax, placeholders have the the following syntax:

     "{" [field_name] ["!" conversion] [":" format_spec] "}"
  

  The part that follows the colon is called format_spec. Python passes this portion of the placeholder to a built-in function format(). Now, each type may interpret this string in a type specific way. But most built-in Python types do it along what they call the "Format Specification Mini Language".

  With this implementation, the approach is very similar. The only difference is that the "Format Specification Mini Language" is implemented for standard types right within this class. But before processing format_spec, this class will check if an argument provides a custom implementation for formatting.

  In C++ and C# this is done by checking if the provided argument implements a specific interface used for formatting values with custom format strings. As such method is not available in Java, no similar concept is implemented here. Instead, only date/time formats are "hardcoded" within method FormatterStdImpl.writeCustomFormat. This is a little unfortunate: To customize the formatting of custom types, a dedicated wrapper class has to be written which implements method toString and writes the wrapped custom object. Then, when formatting, the custom types have to passed wrapped in such wrapper class dedicated to formatting.

• Conversions:
  In the Python placeholder syntax specification:

     "{" [field_name] ["!" conversion] [":" format_spec] "}"
  

  symbol '!' if used prior to the colon ':' defines what is called the conversion. With Python, three options are given: '!s' which calls str() on the value, '!r' which calls repr() and '!a' which calls ascii(). This is of-course not applicable to this formatter. As a replacement, this class extends the original specification of that conversion using '!'. The following provides a list of conversions supported. The names given can be abbreviated at any point and ignore letter case, e.g. !Upper can be !UP or just !u. In addition, multiple conversions can be given by concatenating them, each repeating character '!'.
  The conversions supported are:

  • !Upper
    Converts the contents of the field to upper case.
  • !Lower
    Converts the contents of the field to lower case.
  • !Quote
    Puts quote characters '"' around the field. Note that these characters are not respecting any optional given field width but instead are added to such.
    An alias name for !Quote is given with !Str. As the alias can be abbreviated to !s, this provides compatibility with the Python specification.
  • !ESC[<|>]
    In its default behavior or if '<' is specified, certain characters are converted to escape sequences. If '>' is given, escape sequences are converted to their (ascii) value. See AString.escape for details about the conversion that is performed.
    An alias name for !ESC< is given with !a which provides compatibility with the Python specification.

    Note

    If !ESC< is used in combination with !Quote, then !ESC< should be the first conversion specifier. Otherwise, the quotes inserted might be escaped as well.

  • !Fill[Cc]
    Inserts as many characters as denoted by the integer type argument. By default the fill character is space ' '. It can be changed with optional character 'C' plus the character wanted.
  • !Tab[Cc][NNN]
    Inserts fill characters to extend the length of the string to be a multiple of a tab width. By default the fill character is space ' '. It can be changed with optional character 'C' plus the character wanted. The tab width defaults to 8. It can be changed by adding an unsigned decimal number.

  • !ATab[[Cc][NNN]|Reset]
    Inserts an "automatic tabulator stop". These are tabulator positions that are stored internally and are automatically extended in the moment the actual contents exceeds the currently stored tab-position. An arbitrary amount of auto tab stop and field width (see !AWith below) values is maintained by the formatter.

    Which each new invocation of Formatter.format, the first auto value is chosen and with each use of !ATab or !AWidth, the next value is used.
    By default, the fill character is space ' '. It can be changed with optional character 'C' plus the character wanted. The optional number provided gives the growth value by which the tab will grow if its position is exceeded. This value defaults to 3. The positions currently stored with the formatter can be reset with providing argument Reset. Alternatively to this, outside of a formatting process, the tab stops can be reset by invoking method Formatter.reset.

    Both, auto tab and auto width conversions may be used to increase readability of multiple output lines. Of-course, output is not completely tabular, only if those values that result in the biggest sizes are formatted first. If a perfect tabular output is desired, the data to be formatted may be processed twice: Once to temporary buffer which is disposed and then a second time to the desired output AString.

    Note

    Method Formatter.releaseDefault resets the auto size values in case no multiple (recursive) acquirements had been performed.

  • !AWidth[NNN|Reset]
    Increases field width with repetitive invocations of format whenever a field value did not fit to the actually stored width. Optional decimal number NNN is added as a padding value. for more information, see !ATab above.
  • !Xtinguish
    Does not print anything. This is useful if format strings are externalized. Modifications of such resources might use this conversion to suppress the display of arguments (which usually are hard-coded).
  • !Replace<search><replace>
    Searches string search and replaces with replace. Both values have to be given enclosed by characters '<' and '>'. In the special case that search is empty (<>), string replace will be inserted if the field argument is an empty string.

Public Fields
AutoSizes	sizes = new AutoSizes()
Public Fields inherited from FormatterStdImpl
NumberFormat	alternativeNumberFormat = new NumberFormat()
SimpleDateFormat	dateTimeFormat = new SimpleDateFormat("", Locale.ROOT)
NumberFormat	defaultNumberFormat = new NumberFormat()
boolean	writeALibErrorReports = true
boolean	writeErrorsToTargetString = true
Public Fields inherited from Formatter
Formatter	next

Public Methods
	FormatterPythonStyle ()
void	reset ()
Public Methods inherited from FormatterStdImpl
	FormatterStdImpl (String formatterClassName)
void	cloneSettings (FormatterStdImpl reference)
Public Methods inherited from Formatter
void	format (AString target, ArrayList< Object > args)
void	format (AString target, Object[] args)

Protected Static Fields
static char[]	constColonAndClosingBracket = ":}".toCharArray()
Protected Static Fields inherited from Formatter
static Formatter	defaultFormatter = null
static ThreadLock	defaultFormatterLock = new ThreadLock()

Protected Fields
Substring	conversion = new Substring()
Substring	phaExtConversion = new Substring()
int	phaExtDefaultPrecision
int	phaExtPrecision
Protected Fields inherited from FormatterStdImpl
int	argsConsumed
AString	fieldBuffer = new AString()
String	formatterName
int	nextAutoIdx
int	pargOffset
ArrayList< Object >	parguments
Substring	parser = new Substring()
Substring	pformatString = new Substring()
Alignment	phaAlignment
boolean	phaAlignmentSpecified
Object	phaArgument
int	phaArgumentIdx
int	phaCutContent
char	phaFillChar
Substring	phaFormatSpec = new Substring()
boolean	phaIsPercentage
NumberFormat	phaNF = new NumberFormat()
int	phaPreviousArgumentIdx
boolean	phaSignPaddingMode
PHType	phaType
char	phaTypeCode
int	phaWidth
boolean	phaWriteBinOctHexPrefix
AString	ptargetString
int	targetStringStartLength
Protected Fields inherited from Formatter
ArrayList< Object >	boxes
Substring	lamFormatString = new Substring()

Protected Methods
boolean	checkStdFieldAgainstArgument ()
void	construct ()
int	findPlaceholder ()
void	initializeFormat ()
boolean	parsePlaceholder ()
boolean	parseStdFormatSpec ()
boolean	preAndPostProcess (int startIdx, AString target)
void	replaceEscapeSequences (int startIdx)
void	resetPHAs ()
Protected Methods inherited from FormatterStdImpl
void	errorFormatString (String msg)
int	format (AString targetString, Substring formatString, ArrayList< Object > arguments, int argOffset)
boolean	setArgument (int pos, boolean countStartsWith_1)
boolean	writeCustomFormat ()
void	writeStdArgument ()

Additional Inherited Members
Public Static Methods inherited from Formatter
static Formatter	acquireDefault ()
static void	releaseDefault ()
Package Access Fields inherited from FormatterStdImpl
Date	tmpDate = new Date()
Package Access Methods inherited from FormatterStdImpl
long	getIntegral ()
boolean	isIntegral ()

Constructor & Destructor Documentation

FormatterPythonStyle()

FormatterPythonStyle

(

)

---

Constructs this formatter. Inherited field defaultNumberFormat is initialized to meet the formatting defaults of Java.

Member Function Documentation

checkStdFieldAgainstArgument()

boolean checkStdFieldAgainstArgument ( )

protected

---

Makes some attribute adjustments and invokes standard implementation

Returns

true if OK, false if replacement should be aborted.

Reimplemented from FormatterStdImpl.

construct()

void construct ( )

protected

---

Constructor helper method.

findPlaceholder()

int findPlaceholder ( )

protected

---

Searches for '{' which is not '{{'.

Returns

The index found, -1 if not found.

Reimplemented from FormatterStdImpl.

initializeFormat()

void initializeFormat ( )

protected

---

Sets the actual auto tab stop index to 0.

Reimplemented from Formatter.

parsePlaceholder()

boolean parsePlaceholder ( )

protected

---

Parses placeholder field in python notation. The portion format_spec is not parsed but stored in member Formatter.phaFormatSpec.

Returns

true on success, false on errors.

Reimplemented from FormatterStdImpl.

parseStdFormatSpec()

boolean parseStdFormatSpec ( )

protected

---

Parses the format specification for standard types as specified in "Format Specification Mini Language".

Returns

true on success, false on errors.

Reimplemented from FormatterStdImpl.

preAndPostProcess()

boolean preAndPostProcess ( int  startIdx, AString  target  )

protected

---

Processes "conversions" which are specified with '!'.

Parameters

startIdx	The int of the start of the field written in ptargetString. -1 indicates pre-phase.
target	The target string, only if different from field ptargetString, which indicates intermediate phase.

Returns

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

Reimplemented from FormatterStdImpl.

replaceEscapeSequences()

void replaceEscapeSequences ( int  startIdx )

protected

---

Implementation of abstract method.
Replaces "{{" with "{" and "}}" with "}". In addition applies AString.escape on target which replaces standard codes like "\\n", "\\r" or "\\t" with corresponding ascii codes.

Parameters

startIdx

The start of the region to replace

Reimplemented from FormatterStdImpl.

reset()

void reset

(

)

---

Resets sizes.

Reimplemented from Formatter.

resetPHAs()

void resetPHAs ( )

protected

---

Invokes parent implementation and then applies some changes to reflect what is defined as default in the Python string format specification.

Reimplemented from FormatterStdImpl.

Member Data Documentation

constColonAndClosingBracket

char [] constColonAndClosingBracket = ":}".toCharArray()

staticprotected

Constant string array

conversion

Substring conversion = new Substring()

protected

Reused object used to parse phaExtConversion in method preAndPostProcess.

phaExtConversion

Substring phaExtConversion = new Substring()

protected

The portion of the replacement field that represents the conversion specification. This specification is given at the beginning of the replacement field, starting with '!'.

phaExtDefaultPrecision

int phaExtDefaultPrecision

protected

The default precision if not given. This is set to 6 in resetPHAs, but is changed when specific.

phaExtPrecision

int phaExtPrecision

protected

The value read from the precision field. This is set to -1 in resetPHAs.

sizes

AutoSizes sizes = new AutoSizes()

Storage of sizes for auto-tabulator feature {!ATab} and auto field width feature {!AWidth}

---

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

• FormatterPythonStyle.java