Formatters

< Operators

Transformers >

Formatters

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

You can probably see that format qualifiers are extremely powerful for creating exactly the right textual representation of an object.

Chaining

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]"
  THU FEB 14 14:04:39 EST 2013

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

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

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

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, [OS,ProcArch,CppExecutor]	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_
pad padleft	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.