FreshMarker Manual

=== Log Built-In

The special built-in log can be used to inspect the current value in an expression. The built-in logs the current content of the expression to the logger builtin.logging and returns the current value.

This expression produces the following log.

=== String Built-Ins

==== upper_case Built-In

This built-in converts a text in its uppercase form.

==== lower_case Built-In

This built-in converts a text in its lowercase form.

==== capitalize Built-In

This built-in converts the first letter of each word to uppercase. A word with a first lowercase letter means \b(\p{javaLowerCase})(\p{IsAlphabetic}*)\b

==== uncapitalize Built-In

This built-in converts the first letter of each word to lowercase. A word with a first uppercase letter means \b(\p{javaUpperCase})(\p{IsAlphabetic}*)\b

==== camelCase Built-In

This built-in converts a text from snake_case, screaming_snake_case or kebab-case to camelCase. The result may look strange if the input is in some other format.

==== snake_case Built-In

This built-in converts a text from camelCase to snake_case. The result may look strange if the input is in some other format.

==== screaming_snake_case Built-In

This built-in converts a text from camelCase to screaming_snake_case. The result may look strange if the input is in some other format.

==== kebab_case Built-In

This built-in converts a text from camelCase to kebab-case. The result may look strange if the input is in some other format.

==== slugify Built-In (since 1.4.6)

This built-in converts a text to a slug.

==== strip Built-In (since 1.11.0)

This built-in removes leading and trailing Unicode whitespaces^[4] from the text. The examples use ␣ as a replacement for the whitespace.

==== strip_leading Built-In (since 1.11.0)

This built-in removes leading Unicode whitespaces^[4] from the text. The examples use ␣ as a replacement for the whitespace.

==== strip_trailing Built-In (1.11.0)

This built-in removes trailing Unicode whitespaces^[4] from the text. The examples use ␣ as a replacement for the whitespace.

==== strip_to_null Built-In (since 1.11.0)

This built-in removes leading and trailing Unicode whitespaces^[4] from the text. The examples use ␣ as a replacement for the whitespace. If the result is an empty string, NULL is returned. If the text is NULL, then NULL is returned instead of throwing an exception.^[5]

==== trim Built-In

This built-in removes leading and trailing whitespaces from the text. The examples use ␣ as a replacement for the whitespace.

==== trim_to_null Built-In (since 1.7.1)

This built-in removes leading and trailing whitespaces from the text. The examples use ␣ as a replacement for the whitespace. If the result is an empty string, NULL is returned. If the text is NULL, then NULL is returned instead of throwing an exception.^[5]

==== empty_to_null Built-In (since 1.7.1)

This built-in returns NULL if the text is empty. If the text is NULL, then NULL is returned instead of throwing an exception.^[5]

==== blank_to_null Built-In (since 1.7.1)

This built-in returns NULL if the text is blank. The examples use ␣ as a replacement for the whitespace. If the text is NULL, then NULL is returned instead of throwing an exception.^[5]

==== contains Built-In

This built-in return true if the text contains the specified parameter, otherwise false.

==== startsWith Built-In

This built-in return true if the text starts with the specified parameter, otherwise false.

==== endsWith Built-In

This built-in return true if the text ends with the specified parameter, otherwise false.

==== toBoolean Built-In

This built-in return true if the text is true and false if it is false.

==== length Built-In

This built-in return the length of the text.

==== is_empty Built-In (since 1.11.0)

This built-in return true for an empty text and false otherwise.

==== esc, escape Built-In

This built-in convert the text into markup with the specified output format. It cannot be processed further because there are no built-ins for markup.

==== noEsc, no_esc, no_escape Built-In

This built-in convert the text into markup without an output format. This can be useful if the current value should not escape with the current output format. It cannot be processed further because there are no built-ins for markup.

==== locale Built-In

This built-in converts a string value into a locale value.

==== version Built-In

This built-in converts a string value into a version value.

==== i18n Built-In (experimental, since 1.6.7)

This built-in returns a string from a resource bundle based on the key in the value.

==== left_pad Built-In (since 1.8.1)

This built-in returns a string with the minimum length that was specified as the first parameter. If the original string is already this long or longer, the return value is equal to the original string.

The string is padded on the left with whitespaces or a character from the optional padding parameter. If the padding parameter is longer than one character, then the padding is applied cyclically.

The examples use ␣ as a replacement for the whitespace.

==== right_pad Built-In (since 1.8.1)

This built-in returns a string with the minimum length that was specified as the first parameter. If the original string is already this long or longer, the return value is equal to the original string.

The string is padded on the right with whitespaces or a character from the optional padding parameter. If the padding parameter is longer than one character, then the padding is applied cyclically.

The examples use ␣ as a replacement for the whitespace.

==== center_pad Built-In (since 1.9.0)

This built-in returns a string with the minimum length that was specified as the first parameter. If the original string is already this long or longer, the return value is equal to the original string.

The string is padded on both sides with whitespaces or a character from the optional padding parameter. If the padding parameter is longer than one character, then the padding is applied cyclically.

The examples use ␣ as a replacement for the whitespace.

==== mask Built-In (since 1.9.0)

This built-in returns a masked string with the length of the original string. Every none space character is replaced by characters from the mask pattern.

If the first parameter is a string, then it is the mask pattern. Otherwise, it is the asterisk character. If the mask pattern is longer than one character, then the mask pattern is applied cyclically.

A first number parameter is the number of unmasked characters at the end of the masked string.

==== mask_full Built-In (since 1.9.0)

This built-in returns a masked string with the length of the original string. Every character is replaced by characters from the mask pattern.

If the first parameter is a string, then it is the mask pattern. Otherwise, it is the asterisk character. If the mask pattern is longer than one character, then the mask pattern is applied cyclically.

A first number parameter is the number of unmasked characters at the end of the masked string.

=== Boolean Built-Ins

==== c (computer language) Built-In

This built-in converts a boolean to the string literals true or false.

==== h (human language) Built-In (since 1.4.6)

This built-in converts a boolean to the localized string literals true or false.

==== then Built-In

This built-in returns its first parameter if the value is true or the second parameter if the value is false.

=== Number Built-Ins

==== c (computer language) Built-In

This built-in converts a number to the string using the toString() method of the corresponding base types BigDecimal, BigInteger, Double, Float, Long, AtomicLong, Integer, AtomiInteger, Byte or Short.

==== h (human language) Built-In (since 1.4.6)

This built-in formats the numbers between 1 and 9 as localized strings 'one' to 'nine'. Other numbers are returned as numbers and formatted by default.

==== format Built-In

This built-in format the number by the given format parameter and the current locale. See java.util.Formatter for details.

==== abs Built-In

This built-in return the absolute value of the number.

==== sign Built-In

This built-in return the sign of the number as an Integer.

==== min Built-In (since 1.6.0)

This built-in returns the smaller value of the variable and the specified parameter.

==== max Built-In (since 1.6.0)

This built-in returns the bigger value of the variable and the specified parameter.

==== Cast Built-Ins (since 1.0.0)

These built-ins cast the number to a TemplateNumber instance in the specified type range.

==== roman Built-In (since 1.3.5)

This built-in converts numbers between 1 and 3999 to roman numerals.

==== utf_roman Built-In (since 1.3.5)

This built-in converts numbers between 1 and 3999 to roman numerals. This built-in uses the Unicode Characters \u2160, \u2164, \u2169 and \u216C to \u216F.

==== clock_roman Built-In (since 1.3.5)

This built-in converts numbers between 1 and 12 to roman numerals. This built-in uses the Unicode Characters from \u2160 to \u216B.

==== clamp Built-In (since 1.10.0)

Clamps the value to fit between min and max. If the value is less than min, then min is returned. If the value is greater than max, then max is returned. Otherwise, the original value is returned.

==== unicode Built-In (since 1.10.0)

Convert value into the corresponding Unicode character. If the number is not an integer, it is converted appropriately. With an additional parameter, this is added to the value as an offset.

=== Character Built-Ins (since 1.10.0)

==== c (computer language) Built-In

This built-in converts a character to a string .

==== is_whitespace Built-In

This built-in returns true if the character is a whitespace and false otherwise (see java.lang.Character#isWitespace).

==== is_digit Built-In

This built-in returns true if the character is a digit and false otherwise. See java.lang.Character#isDigit).

==== is_letter Built-In

This built-in returns true if the character is a letter and false otherwise (see java.lang.Character#isLetter).

==== is_upper_case Built-In

This built-in returns true if the character is an uppercase character and false otherwise (see java.lang.Character#isUpperCase).

==== is_lower_case Built-In

This built-in returns true if the character is a lowercase character and false otherwise (see java.lang.Character#isLowerCase).

==== is_alphabetic Built-In

This built-in returns true if the character is an alphabetic character and false otherwise (see java.lang.Character#isAlphabetic).

==== is_letter Built-In

This built-in returns true if the character is a letter and false otherwise (see java.lang.Character#isLetter).

==== is_emoji Built-In (experimental)

This built-in returns true if the character is an emoji and false otherwise (see java.lang.Character#isLowerCase).

==== upper_case Built-In

This built-in converts the character to uppercase (see java.lang.Character#toUpperCase).

==== lower_case Built-In This built-in converts the character to lowercase (see java.lang.Character#toLowerCase).

==== unicode_block Built-In (experimental) This built-in returns the name of the containing unicode block.

=== Date-Time Built-Ins

The Built-Ins in the examples operate on the java.time.Instant, java.time.ZonedDateTime, java.time.OffsetDateTime,java.time.LocalDateTime respectively java.util.Date value 1968-08-24 12:34:56.

==== date Built-In

This built-in returns the date part of the value.

==== time Built-In

This built-in returns the time part of the value.

==== c (computer language) Built-In

This built-in returns a timestamp string of the value.

==== string Built-In

This built-in returns a formatted string of the value. ^[6]

==== at_zone Built-In

This built-in returns a temporal at the given time zone of the value. ^[6]

==== zone Built-In

This built-in returns a string for the current time zone of the value. It is only available for the java.time.TemplateZonedDateTime type.

==== year Built-In (since 1.7.0)

This built-in returns the year of the value.^[7]

==== month Built-In (since 1.7.0)

This built-in returns the month of the value.^[7]

==== day Built-In (since 1.7.0)

This built-in returns the day of month of the value as a number.^[7]

==== easter Built-In (since 1.8.0)

This built-in returns the date of Easter sunday in the year of the value as a date.^[6]

==== supports Built-In (since 1.8.2)

This built-in returns true for the supported temporal units, false otherwise. The currently available temporal units YEARS, MONTHS, DAYS, HOURS, MINUTES and SECONDS are all supported.

=== Date Built-Ins

The Built-Ins in the examples operate on the java.time.LocalDate respectively java.sql.Date value 1968-08-24.

==== date Built-In

This built-in returns the date part of the value.

==== c (computer language) Built-In

This built-in returns a date string of the value.

==== h (human language) Built-In (since 1.4.6)

This built-in returns a date string of the value. If the date is a maximum of two days before or after the reference date, a localized variant of the the day before yesterday, yesterday, today, tomorrow or the day after tomorrow is used. The reference date is the parameter of the built-in. If the parameter is missing, LocalDate.now() is used. ^[6]

==== string Built-In

This built-in returns a formatted string of the value. ^[6]

==== since Built-In (since 1.6.1)

This built-in returns a duration between the value and the parameter. If the parameter is missing, java.time.LocalDate.now() is used. ^[6]

==== until Built-In (since 1.6.1)

This built-in returns a duration between the value and the parameter. If the parameter is missing, java.time.LocalDate.now() is used. ^[6]

==== year Built-In (since 1.7.0)

This built-in returns the year of the value.^[6]

==== month Built-In (since 1.7.0)

This built-in returns the month of the value.^[6]

==== day Built-In (since 1.7.0)

This built-in returns the day of month of the value as a number.^[6]

==== easter Built-In (since 1.8.0)

This built-in returns the date of Easter sunday in the year of the value as a date.^[6]

==== supports Built-In (since 1.8.2)

This built-in returns true for the supported temporal units, false otherwise. From the currently available temporal units only YEARS, MONTHS and DAYS are supported.

=== Time Built-Ins

The Built-Ins in the examples operate on the java.time.LocalTime respectively java.sql.Time value 12:34:56.

==== time Built-In

This built-in returns the time part of the value.

==== c (computer language) Built-In

This built-in returns a time string of the value.

==== string Built-In

This built-in returns a formatted string of the value. ^[6]

==== supports Built-In (since 1.8.2)

This built-in returns true for the supported temporal units, false otherwise. From the currently available temporal units only HOURS, MINUTES and SECONDS are supported.

=== Year Built-Ins

The Built-Ins in the examples operate on the value 2025.

==== c (computer language) Built-In (since 1.7.0)

This built-in returns a year string of the value.

==== year Built-In (since 1.7.0)

This built-in returns the year of the value.

==== is_leap Built-In (since 1.7.0)

This built-in returns true if the year is a leap year.

==== easter Built-In (since 1.8.0)

This built-in returns the date of Easter sunday in the year of the value as a date.

==== supports Built-In (since 1.8.2)

This built-in returns true for the supported temporal units, false otherwise. From the currently available temporal units only YEARS is supported.

=== YearMonth Built-Ins

The Built-Ins in the examples operate on the value 2025-08.

==== c (computer language) Built-In (since 1.7.0)

This built-in returns a year string of the value.

==== year Built-In (since 1.7.0)

This built-in returns the year of the value.

==== month Built-In (since 1.7.0)

This built-in returns the month of the value.

==== is_leap Built-In (since 1.7.0)

This built-in returns true if the year is a leap year.

==== easter Built-In (since 1.8.0)

This built-in returns the date of Easter sunday in the year of the value as a date.

==== supports Built-In (since 1.8.2)

This built-in returns true for the supported temporal units, false otherwise. From the currently available temporal units only YEARS and MONTHS are supported.

=== MonthDay Built-Ins

The Built-Ins in the examples operate on the value 08-24.

==== c (computer language) Built-In (since 1.7.0)

This built-in returns a year string of the value.

==== month Built-In (since 1.7.0)

This built-in returns the month of the value.

==== day Built-In (since 1.7.0)

This built-in returns the day of month of the value as a number

==== supports Built-In (since 1.8.2)

This built-in returns true for the supported temporal unit, false otherwise. For this type only MONTHS and DAYS are supported.

=== Sequence Built-Ins

The Built-Ins in the examples operate on a sequence with the values 2, 3, 4, 5 and 6.

==== first Built-In

This built-in returns the first element of a sequence.

==== last Built-In

This built-in returns the last element of a sequence.

==== reverse Built-In

This built-in returns a reversed sequence of a sequence.

==== size Built-In

This built-in returns the size of a sequence as a number.

==== join Built-In (since 1.5.1)

This built-in returns the elements of a sequence as a string. The default limiter is ", " but can be changed with the first optional parameter of the built-in. The second optional parameter is an alternative parameter for the last element in the sequence.

==== size Built-In

This built-in return the size of the text.

==== is_empty Built-In (since 1.11.0)

This built-in return true for an empty sequence and false otherwise.

=== Range Built-Ins

==== lower Built-In (since 1.6.4)

This built-in returns the lower bound of a range.

==== upper Built-In (since 1.6.4)

This built-in returns the upper bound of a limited range.

==== reverse Built-In (since 1.6.4)

This built-in returns a reversed limited range.

==== size Built-In (since 1.6.4)

This built-in returns the size of a limited range as a number.

==== join Built-In (since 1.6.4)

This built-in returns the elements of a limited range as a string. The default limiter is ", " but can be changed with the first optional parameter of the built-in. The second optional parameter is an alternative parameter for the last element in the sequence.

==== size Built-In

This built-in return the size of a limited range.

==== is_empty Built-In (since 1.11.0)

This built-in return true for an empty range and false otherwise.

==== is_limited Built-In (since 2.0.0)

This built-in return true for a limited range and false otherwise.

==== is_unlimited Built-In (since 2.0.0)

This built-in return true for an unlimited range and false otherwise.

=== Looper Built-Ins

==== index Built-In

This built-in returns the index (starting with zero) of the current loop value as a number value.

==== counter Built-In

This built-in returns the counter (starting with one) of the current loop value as a number value.

==== roman Built-In (since 1.3.5)

This built-in returns the counter (starting with one) of the current loop value as a roman number value.

==== utf_roman Built-In (since 1.3.5)

This built-in returns the counter (starting with one) of the current loop value as a roman number value. This built-in uses the Unicode Characters \u2160, \u2164, \u2169 and \u216C to \u216F.

==== clock_roman Built-In (since 1.3.5)

This built-in returns the counter (starting with one up to twelve) of the current loop value as a roman number value. This built-in uses the Unicode Characters from \u2160 to \u216B.

==== is_first Built-In

This built-in returns the boolean value true, if the current loop value is the first one and false otherwise.

This built-in useful, if the first item in a sequence should look different.

==== is_last Built-In

This built-in returns the boolean value true, if the current loop value is the last one and false otherwise.

This built-in useful, if the last item in a sequence should look different.

==== item_parity Built-In

This built-in returns the string value even, if the current loop counter is even and odd otherwise. It is useful for CSS class names.

==== item_parity_cap Built-In

This built-in returns the string value Even, if the current loop counter is even and Odd otherwise. It is useful for CSS class names.

==== item_cycle Built-In

This built-in cycles throw the parameters for the current loop counter. It is useful for CSS class names.

==== has_next Built-In

This built-in returns false, if the current loop value is the last one and true otherwise.

This built-in useful, if the last item in a sequence should look different.

=== Enum Built-Ins

The Built-Ins in the examples operate on the enum value java.nio.file.StandardCopyOption.ATOMIC_MOVE.

==== ordinal Built-In

This built-in returns the ordinal of the value.

==== c (computer language) Built-In

This built-in returns the name of the value.

=== File and Path Built-Ins

The Built-Ins in the examples operate on the java.io.File respectively java.nio.file.Path value /src/main/asciidoc/manual.adoc.

==== exists Built-In

This built-in returns true, if the file/path in the value exists.

==== is_directory Built-In

This built-in returns true, if the file/path in the value is a directory.

==== is_file Built-In

This built-in returns true, if the file/path in the value is a file.

==== can_execute Built-In

This built-in returns true, if the file/path in the value can be executed.

==== can_read Built-In

This built-in returns true, if the file/path in the value can be read.

==== can_write Built-In

This built-in returns true, if the file/path in the value can be written.

==== size Built-In

This built-in returns the size of the file/path in the value.

==== name Built-In

This built-in returns the name of the file/path in the value.

==== parent Built-In

This built-in returns the parent file/path of the value.

=== Locale Built-Ins

The Built-Ins in the examples operate on the locale value Locale.GERMANY.

==== lang, language Built-In

This built-in returns the language part of the locale value.

==== language_name Built-In (since 1.7.5)

This built-in returns the language name of the locale value.

==== country Built-In

This built-in returns the country part of the locale value.

==== country_name Built-In (since 1.7.5)

This built-in returns the country name of the locale value.

=== Version Built-Ins

The Built-Ins in the examples operate on the version value 1.0.2.

==== major Built-In

This built-in returns the major part of the version value.

==== minor Built-In

This built-in returns the minor part of the version value.

==== patch Built-In

This built-in returns the patch part of the version value.

==== is_before Built-In

This built-in return true if the version is before the specified parameter, otherwise false. The type of the parameter is string or version.

==== is_equal Built-In

This built-in return true if the version is equal the specified parameter, otherwise false. The type of the parameter is string or version.

==== is_after Built-In

This built-in return true if the version is after the specified parameter, otherwise false. The type of the parameter is string or version.

=== Random Built-Ins

The examples uses the .random built-in variable containing a SecureRandom value and variable abraxas containing a Random value.

==== boolean Built-In

This built-in returns a random boolean value.

==== int Built-In

This built-in returns a random int value. If a parameter is specified, the built-in returns a number between 0 and the parameter.

==== double Built-In (since 1.2.0)

This built-in returns a random double value. If a parameter is specified, the built-in returns a number between 0 and the parameter.

==== item Built-In

This built-in returns a random item from a sequence.

==== uuid Built-In

This built-in returns a random UUID as string.

==== sentence Built-In (since 1.2.0)

This built-in returns a random sentence as string.

==== paragraph Built-In (since 1.2.0)

This built-in returns a random paragraph as string.

=== Type checking Built-Ins (since 1.8.1)

Normally, the type of a variable does not need to be checked because the data model has been modeled correctly.

Nevertheless, it may occasionally be necessary to check the type of a variable so that it receives special treatment.

==== is_null Built-In

This built-in returns the true is the variable is NULL and false otherwise.

It only exists to complete the type checks, normally you use the existence operator.

==== is_string Built-In

This built-in returns the true is the variable contains a string value and false otherwise.

==== is_character Built-In

This built-in returns the true is the variable contains a character value and false otherwise.

==== is_boolean Built-In

This built-in returns the true is the variable contains a boolean value and false otherwise.

==== is_number Built-In

This built-in returns the true is the variable contains a number value and false otherwise.

==== is_sequence Built-In

This built-in returns the true is the variable contains a sequence value and false otherwise.

==== is_hash Built-In

This built-in returns the true is the variable contains a hash value and false otherwise.

==== is_enum Built-In

This built-in returns the true is the variable contains an enum value and false otherwise.

==== is_range Built-In

This built-in returns the true is the variable contains a range value and false otherwise.

==== is_temporal Built-In (since 1.8.2)

This built-in returns the true is the variable contains a temporal value and false otherwise.

A temporal value is one of the types java.util.Date, java.sql.Time, java.sql.Date, java.time.Instant, java.time.ZonedDateTime, java.time.LocalDateTime, java.time.LocalDate, java.time.LocalTime, java.time.Year,java.time.YearMonth and java.time.MonthDay.

== Directives

=== If/ElseIf/Else Directive

This directive generates conditional output. The expression in the if and elseif statement is evaluated to a boolean value. If the value is true the corresponding block is evaluated. If the expression cannot evaluate to a boolean value an exception is thrown.

The elseif and else part are optional and can be dismissed.

=== Switch/Case/Default Directive

This directive generates conditional output. Each case statement handles a possible outcome of the evaluation. With the switch directive, the expressions of the case statements are compared one after the other with the expression in the switch statement. The first case statement that matches is used as the output. If none of the specified case statements match, then the optional default statement is used.

The case statement expressions do not have to be constants. This means that more complex expressions can also be used. If this is not desired, it can be switched off using the feature SwitchDirectiveFeature.ALLOW_ONLY_CONSTANT_CASES.^[8]

In addition, the individual case statement expressions do not have to have the same type. If this is desired, it can be activated via the SwitchDirectiveFeature.ALLOW_ONLY_EQUAL_TYPE_CASES feature. This feature is only taken into account if the feature SwitchDirectiveFeature.ALLOW_ONLY_CONSTANT_CASES is also activated.^[8]

=== Switch/On/Default Directive (since 1.7.1)

This directive generates conditional output. Each on statement handles a possible outcome of the evaluation. With the on directive, the expressions of the on statements are compared one after the other with the expression in the sitch statement. The first on statement that matches is used as the output. If none of the specified on statements match, then the optional default statement is used.

The difference between on and case statement is that an on statement can contain several comparison expressions.

The on statement expressions do not have to be constants. This means that more complex expressions can also be used. If this is not desired, it can be switched off using the feature SwitchDirectiveFeature.ALLOW_ONLY_CONSTANT_ONS.

In addition, the individual on statement expressions do not have to have the same type. If this is desired, it can be activated via the SwitchDirectiveFeature.ALLOW_ONLY_EQUAL_TYPE_ONS feature. This feature is only taken into account if the feature SwitchDirectiveFeature.ALLOW_ONLY_CONSTANT_ONS is also activated.

=== List Directive

The List Directives processes its body for each element of a sequence. The sequence can be either a list, a hash or a range. A List Directive defines the sequence and the name of the item variable in the block. In addition, an optional loop variable containing meta information of the current loop iteration can also be specified.

==== List Directive with a list

A list is a sequence of values of any model type.

In the above example, each element from the list is simply output followed by the word Marx. If the list contains Chico, Harpo, Groucho, Gummo and Zeppo then the result is a five-line listing of the Marx brothers.

The next example the interpolation ${s} is preceded by the interpolation ${l?counter}.

Because l is the name of the loop variable, the first interpolation evaluates to the counter of the current item in the list.

==== List Directive with a range

A range is defined by a lower and a non-mandatory upper numerical limit. Although FreshMarker also masters right-unlimited ranges, List Directives are not allowed to use them.

The current item in the above example is any integer value from 1 to 5 inclusive. The result is a list of square value equations.

Because the limits of a range do not have to be constants, a List Directive can also be used to mimic a for loop.

This example loops through all values between numeric variable a and numeric variable b. For the value 3 in a and 1 in b the following result is generated.

==== List Directive with a hash

A hash is a sequence of key-value pairs. The key is a string and the value is any model type. For a hash the item in the List Directive is a key-value pair.

==== List Directive with a hash and sorted keys

Normally the list iterates over the entries without a preferred order. With Java Map types this can be influenced by the use of SequencedMap implementations. However, this is not possible when using a Java Bean.

The keys of a hash can also be sorted in ascending and descending order by adding sorted asc after the key for ascending sorting and sorted desc for descending sorting.

==== List Directive with a filter (since 1.6.6)

The list directive runs over all elements of a list. An element can be omitted with an if statement. If the looper variable is also used, this can lead to jumps. There are two solutions to this problem.

The first solution is to include a filtered list in the model and to use this list in the list directive. The second solution is to use a filter expression in the list directive.

The filter expression in the list directive follows directly after the looper part.

==== List Directive with an offset (since 1.7.2)

The start offset in the list directive can be increased using an offset expression. The offset expression in the list directive follows directly after the filter part. If the list ist filtered by a filter expression, the offset is applied to the filtered and not to the original list.

==== List Directive with a limit (since 1.6.6)

The number of elements in the list directive can be reduced using a limit expression. The limit expression in the list directive follows directly after the offset part. If the list ist filtered by a filter expression, the limit is applied to the filtered and not to the original list.

=== Var/Set/Assign Directive

The Var, Set and Assign Directives are used to define local variables in the template. Unlike the model values, new values can be assigned to variables.

The first use of a variable is with the Var Directive. This defines the variables in the current context. The variable can be assigned later new values with the Set and Assign Directive. A variable only exists within its context.

The Var Directive allows the assignment of an initial value to the variable.

Instead of multiple Var Directives a single Var Directive with several variable definitions can be used. The individual definitions can be separated from each other by a space or a comma.

A new context is created within the List Directive, Macro Directive and the conditional If and Switch Directives. Therefore, variables that are created in a Macro Directive can no longer be accessed outside.

In this example the variable test cannot accessed outside of the macro. The result of the interpolation ${test!'gonzo'} is therefore gonzo.

Variables with an identical name cannot created in the same context. Variables in an outer context can be hidden by variables with an identical name.

=== Output-Format Directive

The output-format directive changes the current output format of the template. The new output format remains in place until it is changed by another output-format directive.

=== Setting Directive

The Setting Directive changes some standard values in the template. The settings remains in place until it is changed by another settings directive.

The following list of settings is supported.

=== Macro Directive

The macro directive can be used to create a macro, which can then be used as a user directive in the template.

=== User Directive

The user directive insert the output of Macro directives or UserDirective implementions in the generated content.

Some User Directives are available as standard. These are currently the compress and oneliner User Directives.

==== compress User Directive

The compress User Directive reduces whitespaces ( , \n, \r) in the output. Whitespace sequences containing newlines will be replaced by a single newline. Whitespace sequences not containing newlines will be replaced by a single space. Whitespace prefixes and suffixes not containing newlines will be removed.

==== oneliner User Directive

TBD

=== Import Directive (since 1.0.0)

Macros can be loaded by the import directive.

The file name parameter is the name of the import file and will be loaded by default relative to the template file.

=== Include Directive (experimental, since 1.7.0)

Sub-templates can be loaded by the include directive. This feature must be activated with templateBuilder.with(IncludeDirectiveFeature.ENABLED).

The file name parameter is the name of the include file and will be loaded by default relative to the template file.

If the included content does not need to be processed, this can be turned off using the parse attribute. In this case, the content of the include will be included as simple text.

If all includes do not need to be parsed, automatic parsing can be deactivated centrally using the feature IncludeDirectiveFeature.PARSE_BY_DEFAULT. In this case, the parse attribute in the directive is no longer required.

=== Brick Directive (since 1.6.6)

It is clearer if related templates are contained in the same document. The document can be evaluated as a template as a whole or the templates it contains can be evaluated individually.

A part that can be evaluated individually is contained within a brick^[9] directive.

A single brick directive is evaluated with the Template#processBrick(String, Map) method. The String parameter is the name of the directive.

== Built-In Variables

=== Now Built-In Variable

The .now built-in variable of Type TemplateZoneDateTime provides the current timestamp.

=== Locale Built-In Variable

The .locale built-in variable of Type TemplateLocale provides the current locale.

=== Country Built-In Variable

The .country built-in variable of Type TemplateString provides the current locales country code.

=== Language Built-In Variable

The .laguage built-in variable of Type TemplateString provides the current locales language code.

=== Version Built-In Variable

The .version built-in variable of Type TemplateVersion provides the current FreshMarker version.

=== Random Built-In Variable

The .random built-in variable of Type TemplateRandom can be used to generate random value via several built-ins.

== Expressions

Expressions are an important part of template evaluation. They are evaluated within Conditional Directives and Interpolations.

The expressions are based on Java expressions, but have some differences. The majority of the deviations result from the basic implementation decisions for FreshMarker as a template engine.

As far as practicable, calculations should not take place within the template engine but in the external application. Basically, expressions should be used to make decisions in the Conditional Directives and to influence the output of Interpolations.

For this reason, FreshMarker does not have any bit shift operators, for example. Variables are assigned values within the template via the Var and Set Directives, so FreshMarker does not have an assignment operator or compound operators like Java.

=== Literal Expressions

TBD

=== Inline Sequences

TBD

=== Variables

TBD

=== Method Invocation

TBD

=== Conjunctions

=== Disjunctions

=== Range Operator

TBD

=== Equality Operators

This operator works only on FreshMarkers primitive types. There is no Equality defined on Hashes, Sequences or Ranges.

=== Relational Operators

Since FreshMarker 1.6.3 model types can overload these operators. Therefore, they are not only available for numeric types, but also for Version, String, Duration, Period and the temporal types. Custom types can also overload all relational operators.

==== Numerical Comparison Operators

==== String Comparison Operators (since 2.0.0)

Two String values can be compared lexicographic with each other.

==== Temporal Comparison Operators (since 2.0.0)

Two temporal values of the same type can be compared with each other.^[6] An exception to this is the type MonthDay, as the year would be required as a context for correct comparison.

==== Duration and Period Comparison Operators (since 2.0.0)

Duration and Period can be compared with each other values of the same type.

==== Version Comparison Operators

Two versions are compared with each other according to the Semantic Versioning schema.

=== Multiplicative Operators