Pure, total, fail-soft substituter for named %{name} placeholders.

This is the Phase 1 interpolation engine that backs the f-suffix family on erli18n (gettextf, ngettextf, pgettextf, npgettextf and their d/dc aliases). It takes a resolved translation msgstr plus a map of Bindings and produces the final binary with each %{name} replaced by its bound value.

The problem it solves

A translated string frequently needs runtime values spliced in (<<"Hello, %{name}!">>). gettext itself has no interpolation; consumers usually hand-roll io_lib:format/2 with positional ~s, which couples the translation to argument ORDER and breaks the moment a translator reorders words. Named placeholders (%{name}) decouple the wording from the call site: the translator can move %{name} anywhere in the sentence and the binding still resolves by name.

Mental model — totality on the hot path

format/2 runs on EVERY gettextf/ngettextf lookup, so it carries the SAME totality bar as erli18n_plural:evaluate/2: it is TOTAL and fail-soft — for ANY msgstr bytes and ANY Bindings map it NEVER raises and ALWAYS returns a binary. There is exactly one opt-in path allowed to raise: format/3 with #{on_missing => strict}, used when a caller wants a missing binding to be a hard error rather than a silently-retained literal.

The substitution is a single left-to-right pass over the input:

• "%%" collapses to a literal "%" (both bytes consumed).
• "%{<name>}", where <name> matches [A-Za-z_][A-Za-z0-9_]*, is replaced by the bound value, or handled per the on_missing policy if the name is unbound.
• To emit a literal "%{name}" un-substituted, author "%%{name}": the "%%" collapses to "%", leaving the following "{name}" untouched.
• A lone "%" that begins neither "%%" nor a valid "%{name}", and a "%{" that never closes into a valid placeholder, are emitted literally. Nothing crashes.

Binding values and atom safety

Binding keys are atoms (#{name => <<"World">>}). Values may be a binary, an iolist/string, an integer, a float, or an atom; every value is coerced to UTF-8 text TOTALLY — an unknown or malformed term renders via a bounded safe fallback rather than raising.

A placeholder name is resolved with binary_to_existing_atom/2 wrapped in try: a name that is not an already-existing atom is treated as a MISSING binding and NEVER creates a new atom. This closes the atom-table-exhaustion DoS that binary_to_atom/2 would open on untrusted msgstr.

Anti-DoS

Consistent with the project's plural caps (see erli18n_plural and include/erli18n.hrl), the work is bounded fail-closed. Because format/2 must stay total, the lenient path CLAMPS rather than raises:

• ?MAX_OUTPUT_BYTES (65536) — the accumulated output is truncated once it would exceed this size; the remaining input is dropped.
• ?MAX_EXPANSIONS (1024) — once this many placeholders have been expanded, further %{name} references are emitted literally instead of substituted.
• ?MAX_NAME_BYTES (256) — a %{ whose name run exceeds this many bytes before the closing } is treated as a malformed reference and emitted literally (this also bounds the binary_to_existing_atom/2 probe).

Bidi (RTL) hazard

v1 does NOT auto-insert Unicode bidi isolation marks (U+2066..U+2069) around interpolated values. Splicing an RTL value (Arabic/Hebrew) into an LTR sentence — or vice versa — can therefore reorder neighbouring punctuation under the Unicode Bidirectional Algorithm. Callers that mix directions should isolate values themselves until a future version offers opt-in isolation.

Quickstart

1> erli18n_interp:format(<<"Hello, %{name}!">>, #{name => <<"World">>}).
<<"Hello, World!">>
2> erli18n_interp:format(<<"%{a} then %{b}">>, #{a => 1, b => two}).
<<"1 then two">>
3> erli18n_interp:format(<<"100%% sure about %{x}">>, #{}).
<<"100% sure about %{x}">>
4> erli18n_interp:format(<<"need %{x}">>, #{}, #{on_missing => strict}).
** exception error: {erli18n_interp,{missing_binding,x}}