Crate mf2_runtime

Expand description

mf2-runtime — the MessageFormat 2 evaluator of Rust MF2: it formats a message from a catalog, walking mf2-catalog’s views in place — resolution, declarations (lazily, each at most once), selection, fallback, the Default Bidi Strategy, format to parts, markup, the u: options — and it holds the function registry, the custom-function API and the core functions: :string, and :number, :integer, :offset with their complete semantics and neutral symbols.

Item	What
`Formatter`	the entry point: `simple`, `write`, `parts`, `*_named`
`Sink`, `PartSink`, `ErrorSink`	where output and errors go
`Arg`, `Value`, `Number`	arguments and resolved values
`Function`, `Registry`, `functions`	handlers; a registry names only the handlers its corpus uses, and no other is linked
`Host`	NFC, float text, zone offsets, a date formatter, a number formatter (`intl`) from the platform
`DateTime`, `TimeZone`, `NumberSpec`, `Digits`, `Measure`	what the function crates and custom functions build on

Client-path code: no_std + alloc, forbid(unsafe_code), no core::fmt, no panicking operation; built-in handlers never allocate.

§The user guide

The Rust MF2 book is the user guide: how the crates fit together, web and native applications, the command line, and what 2.x promises. An application reaches this crate through mf2, which re-exports it; a custom function is written against Function.

Modules§

functions: The core functions (plans/03-runtime.md §3, §5.1): statics for a crate::Registry. An application’s generated registry names only the ones its corpus uses (closed world, B13).

Structs§

Catalog: A validated .mf2b catalog (F2): the fetched buffer and the offsets new found. Share it as Rc<Catalog> / Arc<Catalog>.
Date: A civil date in the proleptic Gregorian calendar (ISO 8601).
DateStyle: The date part: dateFields / fields and dateLength / length.
DateTime: A date/time value: an application’s argument (crate::Arg::DateTime, crate::CustomValue::as_date_time), a literal a date/time function parsed, or what :datetime, :date or :time resolved — the value with its DateTimeOptions. Build it with the constructors.
DateTimeOptions: What :datetime, :date or :time resolved (datetime.md). The override options (time_zone, hour12, calendar) travel with the value into a later date/time expression that takes it as its operand.
DateTimeRequest: What a host’s date formatter receives (Host::format_date_time, datetime-intl): an instant and how to show it.
DigitOptions: ECMA-402’s digit options as SetNumberFormatDigitOptions resolved them for MF2 — so never a set Intl rejects: where it would throw, the numeric function reported Bad Option and dropped or replaced the option (plans/03-runtime.md §5.3).
Digits: Digits to show (plans/03-runtime.md §2.7): a resolved number’s rounded display digits (Number::digits), or a number’s exact value (Number::exact_digits) — what mf2-fn-number localizes.
ExpressionPart: A formatted placeholder: its resolved value and how it formats.
FnContext: What a handler may see of the formatting context: read-only and minimal (formatting.md, “Function Handler”).
FormatContext: What formatting needs beyond the catalog and the registry; build it with FormatContext::new.
Formatter: Formats messages of one catalog.
MarkupOptions: The options of a MarkupPart: (name, value) in source order.
MarkupPart: A markup placeholder.
Measure: A number with a currency or a unit, and the options its function added.
MsgId: A message id: which message of a build’s catalogs. tr! and the generated module make them; an application compares, hashes and passes them, and never builds one from a number.
NoErrors: Discards errors: the release client’s policy (plans/03-runtime.md §8).
Number: An exact decimal and, once a numeric handler resolved it, its resolved options and its display form. Opaque: the digit backend is internal (owner decision 1).
NumberRequest: A number for a NumberFormatter (the host’s, Host::numbers). Built by the runtime; a host reads it.
NumberSpec: How one numeric function resolves (plans/03-runtime.md §2.7): which options it reads, its fraction-digit defaults, whether it rounds to an integer, whether it selects, and the power of ten it applies. Closed world: a handler is a spec.
Operands: The UTS #35 operands of a non-negative decimal (Part 3 §5.1.1): the formatter’s side of the contract of plans/02-catalog-format.md §4.1. n is integral iff t == 0, and then equals i.
OptionValue: A resolved option value.
Options: The resolved options passed to Function::resolve. Their order is not significant; a repeated name (a Duplicate Option Name, which the build rejects) resolves to the last.
Registry: The function handlers an application links: closed world (B13). Build code generates it from exactly the functions the corpus uses, e.g. static REGISTRY: Registry = Registry::new(&[("integer", &mf2_runtime::functions::INTEGER)]); — an unused handler is never referenced, so never linked.
Time: A wall-clock time, to the millisecond (a date/time literal has at most three fraction digits).
TimeZone: The formatting context’s time zone: the default of timeZone (plans/03-runtime.md §6). Owned — a per-request zone need not be 'static.

Enums§

Arg: A positional argument: slot i of the call site is args[i] (the manifest’s slot order). Small on purpose: every variant is a code path in the wasm. Non-exhaustive, so variants can be added.
BidiStrategy: A bidirectional isolation strategy (formatting.md, “Handling Bidirectional Text”).
Category: A CLDR plural category.
CurrencyDisplay: :currency’s currencyDisplay.
DateFields: dateFields / fields.
DateLength: dateLength / length.
Dir: Text direction.
FallbackSource: What a fallback value shows (formatting.md, “Fallback Resolution”).
FormatError: An error reported while formatting. Formatting still produces output.
Grouping: useGrouping. Core output never groups; mf2-fn-number honours it.
Isolation: A bidi isolation control.
MarkupKind: The three forms of markup.
MeasureUnit: What a Measure measures.
NumberOut: Where NumberFormatter::format writes: text, or sub-parts (formatToParts: integer, group, decimal, fraction, minusSign, plusSign, percentSign, currency, unit, literal, …).
NumberStyle: How a NumberRequest is shown.
Part: A part of a formatted message. Concatenated, the parts are the string output.
RoundingMode: roundingMode (ECMA-402’s names and meanings).
RoundingPriority: roundingPriority.
Sign: The sign a formatted number shows, after signDisplay.
SignDisplay: signDisplay.
TimePrecision: timePrecision / precision.
UnitDisplay: :unit’s unitDisplay.
Value: A resolved value’s data. The handler that resolved it decides how it formats and selects; a value no handler resolved (a literal, an argument) is unannotated (plans/03-runtime.md §2.6).
ZoneOption: A time zone as an option value (timeZone) or a formatting target.
ZoneStyle: timeZoneStyle.

Traits§

CustomValue: An application’s own argument type: what it converts to.
ErrorSink: An error sink.
Function: A function handler. :string, :number, :integer, :offset are in crate::functions; custom functions implement the same trait (the suite’s :test:* functions are written against it).
Host: The platform services the runtime needs.
NumberFormatter: A number formatter for the intl option (Host::numbers; plans/03-runtime.md §2.7, §5.3): the final “value + resolved options → text” step and the plural category, where the numeric functions keep MF2’s semantics in Rust. mf2-host-web implements it with Intl.
PartSink: Receives the parts of a formatted message, in order.
Sink: A text sink.
SubPartSink: Receives the sub-parts of a formatted expression (a number’s minusSign, integer, decimal, fraction, …).

Functions§

is_zone_name: Whether s is a well-formed RFC 9557 time-zone-name: parts separated by /, each starting with a letter, . or _, then letters, digits, ., _, - or +, and neither . nor ...