|< Operators||Transformers >|
Formatters are expression qualifiers that perform a text-conversion function. They generally follow the programming guidelines of the Java
java.util.Formatter type. The Java
Formatter type extends the familiar C-style
printf() format strings with some powerful features, but follows the general philosophy of that family of functions. Just as a reminder, in a
printf() method, you have a format string as the first argument, followed by zero or more arguments that replace variables in the format string. The following snippet is a simple example of a
printf( "%d. %s", 1, "Introduction" );
Java has expanded this concept with additional type specifiers, additional formatting options and the ability to reference the same argument more than once in a format string.
You can apply a terp formatter to any object by adding the format string to an object qualifier. The following example demonstrates how you can get a string representation of the current year based on the built-in
C:\terp\bin>terp -e "now['%tY']" 2013
The following example demonstrates a slightly more complex format that uses the date instance multiple times, each time with different format modifiers:
C:\terp\bin>terp -e "now['%1$tY-%1$tm-%1$td']" 2013-11-04
You can probably see that format qualifiers are extremely powerful for creating exactly the right textual representation of an object.
Formatters can be chained and we supply some built-in formatters for commonly required text manipulations. the built-in upper formatter can be used to convert the string representation of an object to uppercase; similarly a lower formatter performs a to lowercase conversion.
C:\terp\bin>terp -e "now[upper]" MON NOV 04 18:02:01 EST 2013
To get the abbreviated dayname in uppercase, you can write:
C:\terp\bin>terp -e "now['%ta'][upper]" MON
You will need to study the java.util.Formatter documentation to take full advantage of all the features and to understand the limitations of the built-in terp formatters.
As the final example, we'll show you how you can combine several terp features to create a custom file modification string.
C:\terp\bin>terp -e "^date(^file(\".\").lastmodified())['%ta']" Mon
The above example displays the name of the day on which the current directory was last modified.
Formatters are a special subgroup of transformers. Essentially, they are simply transformers that return a string. Please see the list of transformers as well. The complete list of built-in formatters follows below.
|ascii||none||Converts the object's string representation to an ASCII-only string. This is very useful when generating source code for programming languages that don't tolerate non-ASCII characters in identifiers.
Example: ^char(0xD6)[ascii] becomes OE
|base64||none||Converts a string to its Base64-encoded equivalent.|
|Typically used in the context of a C++ compiler invocation. Very useful for matching (inexactly) a library directory based on a path pattern and the formatter's context.
Example: <libpath path="bestcppdir(libDir+'/%o/%p/%c-%v')" />
|capitalize||[count]||Capitalizes the first count (default 1) characters of the object's string representation. See upper/uppercase for a complete conversion to upper case.
Example: "this"[capitalize(2)] becomes THis
|lower||none||Converts to lowercase|
|namefy||[string]||Replaces all non-word character sequences with a replacement string (default is the underscore character), yielding a string that could be used as a legal name or identifier in most contexts.
Example: 'a -- and b'[namefy] becomes a_and_b_2_
|int,[object]||Pads the item with spaces (by default) until the specified width is reached. The padding can optionally be specified as the second argument.
Example: 4[pad(3,'*')] becomes **4
|padright||int,[object]||Pads the item with spaces (by default) on the right until the specified width is reached. The padding can optionally by specified as the second argument.
Example: 4[padright(3,'_')] becomes 4__
|prefix||obj||Prefixes the specified object to each element.|
|slugify||none||Collapses multiple spaces into one and converts the resulting spaces and underscores to dashes.|
|upper||none||Converts to uppercase|
|xmlencode||none||Escapes all XML-active characters to their entity representations (for example, > becomes >|
Custom formatters tpyically implement the Formatter interface.