Formatting for humans, or for computers - Apache FreeMarker Manual

Unsupported web browser - Use a modern browser to view this website!

- Home
- Manual
- Java API

- Contribute
- Report a Bug
- Download

Manual
Previous Next

# Formatting for humans, or for computers

By default `${someValue}` outputs numbers, date/time/date-time and boolean values in a format that targets normal users ("humans"). You have various settings to specify how that format looks, like `number_format`, `date_format`, `time_format`, `datetime_format`, `boolan_format`. The output also often depends on the `locale` setting (i.e., on the language, and country of the user). So 3000000 is possibly printed as `3,000,000` (i.e., with grouping separators), or `3.14` is possibly printed as `3,14` (i.e., with a different decimal separator).

At some places you need to output values that will be read (parsed) by some program, in which case always use the `c` built-in, as in `${someValue?c}` (the "c" stands for Computer). Then the formatting depends on the `c_format` setting, which usually refers to a computer language, like `"JSON"`. The output of `?c` is not influenced by `locale`, `number_format`, etc.

The `c` built-in will format string values to string literals. Like if the `c_format` setting is `"JSON"`, then `{"fullName": ${fullName?c}}` will output something like `{"fullName": "John Doe"}`, where the quotation marks (and `\` escaping if needed) were added by `?c`.

Note:

At least as of 2.3.32, the `c` built-in doesn't support date/time/datetime values, only numbers, booleans, and strings.

When formatting for computers, at some places you want to output a `null` (or its equivalent in the target language) if the value you print is missing/`null`. The convenient shortcut for that is using the `cn` built-in (the "n" stands for Nullable), as in `${someValue?cn}`. It behaves like the `c` built-in, except that if `someValue` evaluates to `null`/missing, it outputs the `null` literal in the syntax that the `c_format` setting specifies, instead of stopping with missing value error.

For the templates where the output is obviously only for computer consumption, some prefers setting the `number_format`, and `boolean_format` settings to `"c"`. (Before 2.3.32, for `number_format` you have to use `"computer"` instead.) Then `${someValue}`, for number, and boolean values will format like `?c` does. To output string literals (i.e, to add quotation and escaping), you will still need an explicit `?c`. Also if you need to output `null` literals, you still have to use `?cn`.

These are the table of supported `c_format` setting values (as of FreeMarker 2.3.32), and their intended use:

- `"JSON"`: JSON generation. Generally, `"JavaScript or JSON"` (see later) is recommended over this.

- `"JavaScript"`: JavaScript generation. Generally, `"JavaScript or JSON"` (see later) is recommended over this.

- `"Java"`: Java source code generation

- `"XS"`: XML Schema compliant XML generation

- `"JavaScript or JSON"`: For generating output that's compatible with both JSON and JavaScript. This setup is therefore resilient against configuration mistakes, where we generate output in one language, but use the `c_format` for the other. The small price to pay is that we can't utilize some language-specific opportunities to make the output a bit shorter, but that hardly matters in practice. This is the default if if the `incompatible_improvements` setting is at least 2.3.32.

- `"legacy"`: Default for backward compatibility when the `incompatible_improvements` setting is less than 2.3.32. Avoid! Can have rounding losses, and formatting glitches for infinity and NaN.

The behaviour of these is documented at the `c` built-in: for numbers, for boolean, for strings, for null-s.

Previous Next