< 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() invocation.

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 now variable:

  C:\terp\bin>terp -e "now['%tY']"

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']"

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 MAY 23 14:35:31 EDT 2016

To get the abbreviated dayname in uppercase, you can write:

  C:\terp\bin>terp -e "now['%ta'][upper]"

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']"

The above example displays the name of the day on which the current directory was last modified.

Built-in Formatters

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.

Built-in formatters
Name Arguments Comments
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.
bestcppdir String,
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[2]'[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 &gt;

API representation

Custom formatters tpyically implement the Formatter interface.


Copyright 2006-2016 by Codemesh, Inc., ALL RIGHTS RESERVED

terp expressions home expressions templates ant about us contact us download