Localize.Exception behaviour (Localize v0.38.0)

Copy Markdown View Source

Conventions and a small behaviour shared by structured Localize exceptions.

The :reason field

Exceptions that distinguish between multiple failure categories carry a :reason field whose value is a documented atom from a closed set. Callers can pattern-match on :reason to branch on category without parsing the rendered message; message/1 is the single place a user-facing sentence is assembled.

Modules that adopt this convention declare @behaviour Localize.Exception and implement reason_atoms/0, returning the exhaustive list of valid :reason values for that struct. This lets tooling — including the structural-exception test suite — iterate the documented reasons and verify that message/1 has a clause for each.

The :cause field

When a higher layer must report a lower layer's failure, the outer exception carries the inner one in a :cause field of type Exception.t() | nil. The convention is:

  • :cause is set when, and only when, the outer exception is a wrapper. A direct error sets :cause to nil.

  • The outer message/1 may delegate to the inner via Exception.message(cause), possibly with a leading context phrase.

  • Programmatic callers can pattern-match on the outer struct for the operation context, and call Exception.message/1 on :cause for the original detail.

This convention is used by Localize.FormatError, Localize.LocaleDownloadError, and Localize.ParseError.

Why no prose in structural fields

Fields like :reason, :expected, :path, and :detail must hold structured values — atoms, paths, short labels, struct references — not free-form sentences with interpolated values. Putting a sentence in a structural field defeats pattern matching, duplicates content into message/1, and prevents translation.

Summary

Callbacks

reason_atoms()

Returns the closed set of atoms permitted in this exception's :reason field.

Functions

safe_message(msgctxt, msgid, bindings \\ [])

Render an MF2-format Gettext message safely for use inside an exception's message/1 callback.

Callbacks

reason_atoms()

@callback reason_atoms() :: [atom()]

Returns the closed set of atoms permitted in this exception's :reason field.

Used by tests to verify that message/1 has a rendering clause for each documented reason atom. The list MUST be exhaustive — any atom assigned to :reason at runtime must appear here.

Functions

safe_message(msgctxt, msgid, bindings \\ [])

@spec safe_message(binary(), binary(), keyword()) :: binary()

Render an MF2-format Gettext message safely for use inside an exception's message/1 callback.

Exception.message/1 is called from raise, Exception.format/2, log handlers, and inspect paths — none of which can tolerate a raise. This helper wraps Gettext.dpgettext/5 so that any failure in the message formatter (a NIF crash, a hostile String.Chars or Inspect impl on a bound value, a future regression) falls back to the raw msgid rather than propagating.

Use this only in defexception message/1 callbacks. General MF2 formatting should call Gettext.dpgettext/5 (or the higher-level macros) directly so callers see the underlying formatter error.

Arguments

  • msgctxt is the gettext context string (e.g. "locale").

  • msgid is the source-language MF2 message string.

  • bindings is a keyword list of variable bindings for the message. The default is [].

Returns

  • The interpolated message string, or msgid unchanged if interpolation failed.