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.

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.