Formats

Queues

The formatting queue applies a sophisticated algorithm to allow simple and powerful template definition. In a nutshell it first converts the value to a string. In this step it uses inheritance to support simple definition and consistent look.

Character Data

A string refers to any kind of character data here: It could be an EncodedContainer or StringBuffer, too. If we push in a Template this phase is already done. And the encoding is preserved throughout the rest of the process. And of course other conversion results may have an encoding, too.

The Process

The next step is the string adjustment. This allows ensuring a certain output length, or other string to string conversions. In this step only the attributes denoted on the actual node apply. (Syntax highlighting and links to java doc of this site are generated by the preprocessor using a format.) So it's for rather special cases, but very powerful whenever needed.

Once the value is formatted it might be escaped by the encoding facility. Even though escaping is a string to string conversion, too, it's very different to decoration. It doesn't address visual issues, but rather technical. In addition, it's typically used for huge portions of a file. Therefore, I added infrastructure to be able to use inheritance for definition.

Custom formats implement the Format interface and are registered using Format.register(). See Extending the platform for additional information. Using VoidFormats one can even have formats, that are executed if no value is provided at all and can even integrate other parameters, provided during rendering, in their result. As not value is required, the name is optional. default and property are examples how this can be used.

Formats even support a sophisticated state handling if needed. Using the SimpleFormat simple things can be done easily, while real powerful stuff is possible.

Formats provided by Snippetory

number (int / decimal)

The value of the attribute is used as pattern for java.text.DecimalFormat if it is not one of the special values:

<empty String>

A number instance is used

currency

A currency instance is used

percent

A percent instance is used

JS

A number instance with locale US is used

In some case it helps to be able to generally helps handle java that do support decimal differently to those, that don't. So int only hit java types, that don't support decimals. While decimal obviously takes over Double, Float and BigDecimal. As a rule of thumb int / decimal makes a lot of sense for general cases, like setting up a TemplateContext while on a single location number is just fine.

date

The date format can convert instances of type java.util.Date and java.util.Calendar or sub-types. It is registered The value of the attribute is used as pattern for java.text.DateFormat if it's not one of the special values:

<empty String>

This represents the default behavior of the date format with what it will be automatically registered on every template. It depends on the locale set. If no locale is

short, medium, long, full

Will convert to a date representation according to the key word

_short, _medium, _long, _full

With a preceding underline it will convert to a time representation according to the key word

<date_key_word><time_key_word>

You can use a date key word immediately followed by a time key word to get a date time value: full_short, medium_medium, ...

sql, _sql, sql_sql

The sql values follow the same principle, but must not be combined with length based keywords.
Note: sql refers to java.sql package rather than the ISO standard. I.e. the format looks like 2011-05-06 12:43:56

JS, _JS, JS_JS

This will generate JavaScript code that creates a new Date-object.

	US English	simplified Chinese	German
long	October 15, 2011	2011年10月15日	15. Oktober 2011
short_full	10/15/11 1:05:15 AM CEST	11-10-15 上午01时05分15秒 CEST	15.10.11 01:05 Uhr MESZ
_medium	1:05:15 AM	1:05:15	01:05:15
sql	2011-10-15	2011-10-15	2011-10-15
JS_JS	new Date(2011, 10, 15, 01, 05, 15)	new Date(2011, 10, 15, 01, 05, 15)	new Date(2011, 10, 15, 01, 05, 15)

pad

Ensures a minimum length.
Via the pad attribute it's possible to define a minimum length of an output string. The length will be enforced by appending additional spaces. In addition, there are the sub-attributes pad.align to determine whether the value should be aligned right or left and pad.fill to overwrite the fill character.

Attributes value	Input	Output	Effect
pad='2'	xxx	xxx	Nothing happens
pad="3" pad.align="right"	xx	xx	One space prepended
pad="7" pad.fill=". "	xx	xx. . . .	fill characters are appended to achieve the required length

crop

Ensures a maximum length.
This is defined by an integer number immediately followed by a abbreviation marker of arbitrary length. This means that the abbreviation marker can't start with a number character, but in most cases either 3 dots or nothing might be used.

Attribute value	Input	Output	Effect
crop="35" crop.mark="..."	This is a long text (35 characters)	This is a long text (35 characters)	Nothing happens
crop="40"	This is a long text (35 characters)	This is a long text (35 characters)	Nothing happens
crop="20" crop.mark="..."	This is a long text (35 characters)	This is a long te...	Only the first 17 characters and three dots are appended
crop="20"	This is a long text (35 characters)	This is a long text	The first 20 characters are used

default

Declares how a value is rendered if no value is set. The value will not be escaped, but it's formatted by string formatters. Without additional definition a location mark will be rendered as its markup while a region will be rendered by an empty string.

null

A null will mostly be handled like an empty string in Snippetory. At least for formatting. This format allows to override this with a fixed value.

toggle

Toggles over a semicolon separated list of values.
The toggling may be triggered simply by rendering the value similar to a default value or may be controlled by explicitly setting a number. In this case a modulo operation is applied to that number with the number of available values as second argument and the value is selected according to the result.

property

Read a System.getProperty or System.getenv value.

case

The case format converts the character case of some input data as specified by the attribute value.
This format will apply to data that implements either java.lang.CharSequenz or EncodedData.

upper

Converts the entire text to upper case

lower

Converts the entire text to lower case

firstUpper

This will only capatilize the first character of the input data and leaves the rest unchanged. If this is not a letter or has no upper case, nothing will happen.

camelizeUpper

Converts the given term to camel case.
The first character will be in upper case. Supported word bounderies are underline `_`and dash `-`.

camelizeLower

Converts the given term to camel case.
The first character will be in lower case. Supported word bounderies are underline `_`and dash `-`.