Skip to Content
GuidesLiterals & Adjacency

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 [...] and ldml '...') wrap literal text in delimiters. Only the letter-bearing span is escaped, so separators stay clean (DD/MM ↔ dd/MM, not dd'/'MM). A literal apostrophe is '' in ldml ('o''clock' → o'clock). A literal ] has no in-band escape inside a moment [...] 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 apart

When 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.

Last updated on