Literals & Adjacency
Text you meant as literal stays literal, and two adjacent tokens never silently merge into a
different token when the output is read back. rosetta-date calls this guarantee round-trip
safety at the token boundary.
Literals
Literal (verbatim) text is preserved across dialects, though each
syntax family marks it differently:
- Delimited dialects (for example,
moment[...]andldml'...') wrap literal text in delimiters. Only the letter-bearing span is escaped, so separators stay clean (DD/MM↔dd/MM, notdd'/'MM). A literal apostrophe is''inldml('o''clock'→o'clock). A literal]has no in-band escape inside amoment[...]run, so it is emitted between bracketed spans (a]b→[a]][b]). - Directive dialects (for example,
strftime) treat all non-directive text as literal verbatim. They escape only the marker by doubling it (%%→%).
Adjacent tokens
When reading two adjacent output tokens would parse them as one different token, rosetta-date
separates them with the target dialect’s empty literal.
For example, date-fns PPPp (a long date next to a short time) becomes moment LL + LT. But
gluing them as LLLT would re-read as LLL (the long localized date preset) + T, a different
parse. So the converter inserts []:
import { convert } from 'rosetta-date'
import { dateFns, momentjs } from 'rosetta-date/libraries'
convert('PPPp', { from: dateFns, to: momentjs }) // 'LL[]LT'; '[]' keeps LL and LT apartWhen a dialect has no empty literal
A quote-style dialect like ldml has no empty literal because '' represents a literal apostrophe.
It cannot express such an adjacency, so the second token is routed through
onUnsupportedToken with reason unrepresentable-adjacency:
- The default literalizes and escapes the token so it cannot merge into a different token.
'throw'reports the token during validation or a mass migration.
In a quote-style target, the adjacency cannot be represented. The unsupported-token policy reports
it as unrepresentable-adjacency instead of changing the output silently.