MF2: first-class function namespaces and the l:quantify function

Author: kipcole9

guides/conformance.md

@@ -475,6 +475,19 @@ Two areas are explicitly out of scope:
 | Function | Notes |
 |----------|-------|
 | `:list` | Formats a list operand by delegating to `Localize.List.to_string/2`. Each element is itself formatted via `Localize.Chars`, so a list of dates, numbers, units, etc. picks up the message's locale and forwarded options. Supports a `style` (or `type`) option whose values map to CLDR list styles: `"and"`, `"and-short"`, `"and-narrow"`, `"or"`, `"or-short"`, `"or-narrow"`, `"unit"`, `"unit-short"`, `"unit-narrow"`. Default is `"and"`. |
+| `:l:inflect` | Inflects a phrase operand for the grammatical constraints in its options (`grammaticalCase`, `grammaticalGender`, `grammaticalNumber`, `grammaticalDefiniteness`, `grammaticalPerson`), delegating to `Localize.Inflection.inflect/3`. Requires the locale's inflection data; a missing locale or absent data is a clean error, never a crash. |
+| `:l:pronoun` | Selects a pronoun, or re-inflects the operand pronoun, via `Localize.Inflection.pronoun/2,3`. |
+| `:l:quantify` | Joins a `count` option with the noun operand so the noun agrees with the number (Slavic numeral government, the Arabic counted-noun cases, per-language number agreement), delegating to `Localize.Inflection.quantify/4`. |
+
+These live in the reserved single-letter `l:` namespace; see *MF2 function namespaces* below.
+
+### MF2 function namespaces
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Namespaced function names (`:ns:name`) | Implemented | The parser accepts `namespace:name`; the interpreter resolves the namespace after the built-in functions. |
+| Reserved namespaces (`l`, `u`) | Implemented | `l` is Localize's own (`:l:inflect` / `:l:pronoun` / `:l:quantify`); `u` is the CLDR-managed namespace the spec reserves for options. Neither routes to a user handler, and an unhandled `l:` / `u:` function is an Unknown Function error — which the spec permits, since implementations are not required to support every namespace. |
+| Custom namespace handlers | Implemented | Register a `Localize.Message.Namespace` handler for a namespace via `config :localize, :mf2_namespaces` or the per-call `:namespaces` option; one handler dispatches every function in its namespace by local name. The flat-string `:mf2_functions` custom registry continues to work for back-compat. Built-in functions are authoritative and cannot be shadowed by a custom function or namespace. |
 
 ### MF2 Error Handling
 

guides/inflection.md

@@ -279,17 +279,20 @@ iex> Localize.Unit.to_string(unit, locale: :ru, grammatical_case: :prepositional
 
 ## In MessageFormat 2 messages
 
-Inflection is available inside MF2 messages through the `l:` namespace: `:l:inflect` inflects its operand phrase, and `:l:pronoun` selects or re-inflects a pronoun. Grammatical constraints are passed as `grammatical*` options — `grammaticalCase`, `grammaticalGender`, `grammaticalNumber`, `grammaticalDefiniteness`, `grammaticalPerson` — mirroring the `:unit` function's naming:
+Inflection is available inside MF2 messages through the `l:` namespace: `:l:inflect` inflects its operand phrase, `:l:pronoun` selects or re-inflects a pronoun, and `:l:quantify` joins a `count` with a noun operand so the noun agrees with the number. Grammatical constraints are passed as `grammatical*` options — `grammaticalCase`, `grammaticalGender`, `grammaticalNumber`, `grammaticalDefiniteness`, `grammaticalPerson` — mirroring the `:unit` function's naming:
 
 ```elixir
 iex> Localize.Message.format("{$w :l:inflect grammaticalNumber=plural}", %{w: "light on the patio"}, locale: :en)
 {:ok, "lights on the patio"}
 
 iex> Localize.Message.format("{|he| :l:pronoun grammaticalCase=accusative}", %{}, locale: :en)
 {:ok, "him"}
+
+iex> Localize.Message.format("{$noun :l:quantify count=5}", %{noun: "час"}, locale: :ru)
+{:ok, "5 часов"}
 ```
 
-The functions need the locale's inflection data present; a missing locale or absent data resolves to an error rather than crashing the format. `:l:quantify` is not yet available.
+The functions need the locale's inflection data present; a missing locale or absent data resolves to an error rather than crashing the format.
 
 ## Error handling
 

guides/message_formatting.md

@@ -291,6 +291,26 @@ Selects or re-inflects a pronoun for the locale. Given a pronoun operand, it re-
 
 Takes the same `grammatical*` options as `:l:inflect`, and likewise requires the locale's inflection data, degrading to an error when the data or locale is unavailable.
 
+### `:l:quantify`
+
+Joins a number with a noun so the noun agrees with it grammatically — the count-and-noun phrase that languages build differently (Slavic numeral government, the Arabic counted-noun cases, the Finnish partitive, and so on). The operand is the noun; the number is the required `count` option.
+
+```
+{$item :l:quantify count=$n}
+{|kilometer| :l:quantify count=2}
+```
+
+The `count` drives both the number joined to the noun (formatted with the message's locale) and the plural category the noun agrees with, so one template produces the right form across categories:
+
+| Locale | Template | Result |
+|--------|----------|--------|
+| `en` | `{|kilometer| :l:quantify count=2}` | `2 kilometers` |
+| `ru` | `{|час| :l:quantify count=2}` | `2 часа` |
+| `ru` | `{|час| :l:quantify count=5}` | `5 часов` |
+| `fi` | `{|talo| :l:quantify count=3}` | `3 taloa` |
+
+It also accepts the same `grammatical*` options as `:l:inflect`, to fix a case or gender the surrounding sentence requires. Like the other `l:` functions it needs the locale's inflection data; a missing or non-numeric `count`, a non-string operand, or absent data all resolve to a clean error, never a crash.
+
 ## Declarations
 
 Declarations appear at the start of a complex message, before the body.
@@ -585,6 +605,7 @@ The Localize MF2 implementation targets the [Unicode MessageFormat 2.0 specifica
 | `:list` | Localize | Locale-aware list join via `Localize.List` |
 | `:l:inflect` | Localize | Grammatical inflection via `Localize.Inflection` |
 | `:l:pronoun` | Localize | Pronoun selection via `Localize.Inflection` |
+| `:l:quantify` | Localize | Number-and-noun agreement via `Localize.Inflection` |
 
 ### `:list` — locale-aware list formatting
 
@@ -664,7 +685,7 @@ config :localize, :mf2_functions, %{
 }
 ```
 
-Per-call functions take precedence over application-level functions, which take precedence over built-in functions. A function name with no built-in implementation and no registry entry is an unknown-function error, per the MF2 specification: `format/3` returns `{:error, %Localize.FormatError{reason: :unknown_function}}`.
+Per-call functions take precedence over application-level functions. Both registries are consulted only for a function name that no built-in already handles — the built-in functions are authoritative and cannot be shadowed. A function name with no built-in implementation and no registry entry is an unknown-function error, per the MF2 specification: `format/3` returns `{:error, %Localize.FormatError{reason: :unknown_function}}`.
 
 **Implementing a custom function:**
 
@@ -686,6 +707,38 @@ end
 
 See `Localize.Message.Function` for the full callback specification.
 
+### Function namespaces
+
+A function name may carry a namespace — `:acme:price`. Namespaced functions resolve after the built-ins, so one handler can own an entire namespace rather than registering each function by its flattened name. Register a `Localize.Message.Namespace` handler per namespace, application-wide or per call:
+
+```elixir
+# config/config.exs
+config :localize, :mf2_namespaces, %{"acme" => MyApp.AcmeFunctions}
+
+# or per call
+Localize.Message.format(message, bindings, locale: :en, namespaces: %{"acme" => MyApp.AcmeFunctions})
+```
+
+The handler dispatches every function in its namespace by local name:
+
+```elixir
+defmodule MyApp.AcmeFunctions do
+  @behaviour Localize.Message.Namespace
+
+  @impl true
+  def format("price", value, func_opts, options) do
+    locale = Keyword.get(options, :locale)
+    MyApp.Price.to_string(value, locale: locale, currency: func_opts["currency"])
+  end
+
+  def format(name, _value, _func_opts, _options) do
+    {:error, {:unknown_function, ":acme:" <> name}}
+  end
+end
+```
+
+The single-letter namespaces `l` (Localize's own `:l:inflect` / `:l:pronoun` / `:l:quantify`) and `u` (CLDR-managed) are reserved: registering a handler for them has no effect, and an `l:` or `u:` function that no built-in handles is an unknown-function error. See `Localize.Message.Namespace` for the full callback specification.
+
 ## Syntax highlighting
 
 For docs, playgrounds, editor tooling, or error reporting, Localize can render an MF2 message as a *classified token stream* and format it as HTML (with CSS classes) or ANSI-coloured terminal output. Highlighting runs after parsing, so only valid MF2 input is highlighted — parse errors surface the same `{:error, %ParseError{}}` tuple as elsewhere.

lib/localize/message/function.ex

@@ -28,8 +28,14 @@ defmodule Localize.Message.Function do
   Application-level functions are available to all
   `Localize.Message.format/3` calls without passing `:functions`
   on every call. Per-call functions take precedence over
-  application-level functions of the same name, which in turn
-  take precedence over built-in functions.
+  application-level functions of the same name.
+
+  Built-in functions are authoritative: both registries are
+  consulted only for a function name that no built-in already
+  handles, so a custom function cannot shadow `:number`, `:date`,
+  `:l:inflect`, or any other built-in. To own a whole custom
+  namespace with a single handler rather than one registration per
+  name, implement `Localize.Message.Namespace` instead.
 
   ## Implementing a custom function
 
@@ -62,7 +68,8 @@ defmodule Localize.Message.Function do
 
   * `func_opts` — a map of MF2 function options parsed from the
     expression (e.g. `%{"format" => "long", "formality" => "formal"}`).
-    Keys and values are strings.
+    Keys are strings. Values are strings, except an option written as
+    a number literal (e.g. `digits=2`) which arrives as a number.
 
   * `options` — the interpreter's keyword list, which includes at
     least `:locale` and `:bindings`.
@@ -77,8 +84,9 @@ defmodule Localize.Message.Function do
 
   * `value` is the resolved operand from the MF2 expression.
 
-  * `func_opts` is a map of string key/value pairs from the MF2
-    function options (e.g. `%{"format" => "long"}`).
+  * `func_opts` is a map of the MF2 function options with string
+    keys (e.g. `%{"format" => "long"}`); values are strings unless
+    written as a number literal.
 
   * `options` is the interpreter's keyword list (contains at least
     `:locale`).

lib/localize/message/interpreter.ex

@@ -1047,11 +1047,12 @@ defmodule Localize.Message.Interpreter do
   #
   # `:l:inflect` inflects its phrase operand for the grammatical
   # constraints given in its options; `:l:pronoun` selects a pronoun
-  # (or re-inflects the operand pronoun). Both wrap the in-tree
-  # `Localize.Inflection` engine and need the locale's inflection data
-  # present — a missing locale or absent data resolves to a clean
-  # error tuple, never a crash. `:l:quantify` is deferred until the
-  # engine ships the concept/quantity primitives it needs.
+  # (or re-inflects the operand pronoun); `:l:quantify` joins a
+  # `count` with the noun operand so the noun agrees with the number
+  # (Slavic numeral government, the Arabic counted-noun cases, and so
+  # on). All three wrap the in-tree `Localize.Inflection` engine and
+  # need the locale's inflection data present — a missing locale or
+  # absent data resolves to a clean error tuple, never a crash.
 
   defp format_with_function("l:inflect", value, func_opts, options) when is_binary(value) do
     locale = Keyword.get(options, :locale, Localize.get_locale())
@@ -1082,6 +1083,25 @@ defmodule Localize.Message.Interpreter do
     end
   end
 
+  defp format_with_function("l:quantify", value, func_opts, options) when is_binary(value) do
+    locale = Keyword.get(options, :locale, Localize.get_locale())
+
+    # The count formats through Localize's own number formatter (so
+    # the joined number is locale-aware) and is also passed as
+    # `:number` so the engine selects the plural category from it.
+    with {:ok, count} <- quantify_count(func_opts),
+         {:ok, formatted} <- Localize.Number.to_string(count, locale: locale) do
+      Localize.Inflection.quantify(formatted, value, locale,
+        number: count,
+        constraints: map_inflect_constraints(func_opts)
+      )
+    end
+  end
+
+  defp format_with_function("l:quantify", value, _func_opts, _options) do
+    {:error, "the :l:quantify function requires a string (noun) operand, got #{inspect(value)}"}
+  end
+
   # ── Custom function registry ─────────────────────────────────────
   #
   # When a function name is not matched by any built-in clause
@@ -1096,18 +1116,37 @@ defmodule Localize.Message.Interpreter do
   # Function resolution error per TR35.
 
   defp format_with_function(name, value, func_opts, options) do
+    # Custom function and namespace handlers receive option keys as
+    # strings — the documented contract — even though the built-in
+    # clauses above read them as atoms. (Option names are atomized
+    # only when a matching atom already exists, so the raw map mixes
+    # atom and string keys.)
+    string_opts = stringify_option_keys(func_opts)
+
     case resolve_custom_function(name, options) do
       {:ok, module} ->
-        module.format(value, func_opts, options)
+        module.format(value, string_opts, options)
 
       :not_found ->
-        # TR35 resolution error: a function that cannot be resolved
-        # is an Unknown Function error, not a pass-through format of
-        # the operand.
-        {:error, {:unknown_function, ":" <> name}}
+        case resolve_namespace_handler(name, options) do
+          {:ok, module, local_name} ->
+            module.format(local_name, value, string_opts, options)
+
+          :not_found ->
+            # TR35 resolution error: a function that cannot be
+            # resolved is an Unknown Function error, not a
+            # pass-through format of the operand.
+            {:error, {:unknown_function, ":" <> name}}
+        end
     end
   end
 
+  # Values are left as-is: a number-literal option is a number, not
+  # a string.
+  defp stringify_option_keys(func_opts) do
+    Map.new(func_opts, fn {key, value} -> {to_string(key), value} end)
+  end
+
   # Maps MF2 grammatical option names to the inflection engine's bare
   # constraint names. Values stay as strings; the engine normalizes
   # both names and values (`Localize.Inflection.Feature`).
@@ -1127,6 +1166,16 @@ defmodule Localize.Message.Interpreter do
     end)
   end
 
+  # The `count` option of `:l:quantify` is required and must be
+  # numeric: it is both the number joined to the noun and the value
+  # the plural category is selected from.
+  defp quantify_count(func_opts) do
+    case Map.get(func_opts, :count) do
+      nil -> {:error, "the :l:quantify function requires a `count` option"}
+      value -> ensure_number(value)
+    end
+  end
+
   defp format_number_as_unit(_number, nil, _func_opts, _options) do
     {:error, "the :unit function requires a `unit` option"}
   end
@@ -1288,6 +1337,48 @@ defmodule Localize.Message.Interpreter do
     end
   end
 
+  # Routes a namespaced function name (`ns:local`) to a registered
+  # namespace handler (`Localize.Message.Namespace`). The reserved
+  # single-letter namespaces `l` (Localize's own, handled by the
+  # built-in clauses above) and `u` (CLDR-managed) never route to a
+  # user handler, so an unhandled `l:`/`u:` function falls through to
+  # an Unknown Function error. The parsed `{:namespace, ns, name}` is
+  # recovered by splitting the flattened name on its single colon —
+  # MF2 identifiers contain none.
+  defp resolve_namespace_handler(name, options) do
+    case String.split(name, ":", parts: 2) do
+      [namespace, local_name]
+      when namespace not in ["l", "u"] and local_name != "" ->
+        case lookup_namespace(namespace, options) do
+          {:ok, module} -> {:ok, module, local_name}
+          :not_found -> :not_found
+        end
+
+      _other ->
+        :not_found
+    end
+  end
+
+  # Per-call `:namespaces` handlers take precedence over the
+  # application-level `:mf2_namespaces` config, mirroring the custom
+  # function registry.
+  defp lookup_namespace(namespace, options) do
+    per_call = Keyword.get(options, :namespaces, %{})
+
+    case Map.get(per_call, namespace) do
+      nil ->
+        app_namespaces = Application.get_env(:localize, :mf2_namespaces, %{})
+
+        case Map.get(app_namespaces, namespace) do
+          nil -> :not_found
+          module -> {:ok, module}
+        end
+
+      module ->
+        {:ok, module}
+    end
+  end
+
   # ── Match evaluation ───────────────────────────────────────────
 
   # MF2 match evaluation: per-selector formatted/original/function