-spec cldr_rule(binary()) -> {ok, binary()} | undefined.

Looks up the CLDR canonical plural expression for Locale in the embedded table.

Returns {ok, Expr}, where Expr is the binary of the C plural expression equivalent to that locale's CLDR rule, or undefined if neither the locale nor its base language is in the table. The match is case-sensitive; region tags fall back to the base language when the region itself is not listed (e.g. fr_BE -> fr, since fr_BE has no row of its own in the table).

A lookup/observability function — NOT on the hot path (PSD-004: the .po header is the runtime source-of-truth). The embedded table (cldr_data/0) covers ~49 locales. Both _ and - separators are accepted in the fallback to the base language.

%% Direct hit: the entry exists in the table.
1> erli18n_plural:cldr_rule(<<"ru">>).
{ok,<<"n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<12 || n%100>14) ? 1 : 2">>}
%% Direct hit: `fr_CA` HAS its own row, so it resolves without falling back.
2> erli18n_plural:cldr_rule(<<"fr_CA">>).
{ok,<<"n > 1">>}
%% Fallback to the base language: `fr_BE` is not in the table, falls back to `fr`.
3> erli18n_plural:cldr_rule(<<"fr_BE">>).
{ok,<<"n > 1">>}
%% Neither the locale nor the base exists.
4> erli18n_plural:cldr_rule(<<"xx">>).
undefined

Edge cases: pt_PT (n != 1) diverges from the base pt (n > 1), so the region entry exists separately. See also validate_against_cldr/2 (compare a header against the CLDR rule) and fallback_rule/0.

-spec compile(binary()) -> {ok, plural_compiled()} | {error, compile_error()}.

Compiles a .po Plural-Forms: header expression into a plural_compiled() bundle (a nplurals/expr/raw map) reused by each evaluate/2.

Header is the header string (nplurals=N; plural=EXPR;); the fields are located in a whitespace-tolerant way. Returns {ok, Compiled} or {error, compile_error()}, always fail-closed (never raises), since it runs over untrusted .po inside the gen_server's handle_call.

Relevant structural rejections:

• {expr_too_long, Size, Max} — expression above ?PLURAL_EXPR_MAX_BYTES (2048), refused before parsing;
• {expr_too_deep, Depth, Pos} — nesting above ?PLURAL_EXPR_MAX_DEPTH (64);
• {expr_too_complex, Nodes, Max} — AST with more nodes than ?AST_MAX_NODES (256), barring wide flat chains (n*n*...*n) that would grow a bignum per lookup;
• {unsafe_plural_rule, Reason} — STATICALLY faulty rule: division/modulo by a constant divisor of 0, or a constant rule whose form falls outside [0, NPlurals). Cases that fail only for a specific N are left to the dynamic clamp of evaluate/2;
• {nplurals_too_many_digits, _, _}, {nplurals_out_of_range, _}, {missing_nplurals, _}, {missing_plural_expr, _} and {syntax_error, Reason, Pos} for the remaining header defects.

Edge cases: redundant parentheses and whitespace are absorbed by the parser; n is the ONLY allowed identifier (nx or m become a syntax_error); degenerate rules plural=0 (ja/zh/ko/vi/th) compile as an integer literal (PSD-008). A rule that fails only for a specific N (e.g. n/(n-5)) is NOT rejected here — that is left to the dynamic clamp of evaluate/2.

1> erli18n_plural:compile(<<"nplurals=2; plural=n != 1;">>).
{ok,#{raw => <<"nplurals=2; plural=n != 1;">>,expr => {binop,'!=',n,1},nplurals => 2}}
2> erli18n_plural:compile(<<"nplurals=1; plural=0;">>).
{ok,#{raw => <<"nplurals=1; plural=0;">>,expr => 0,nplurals => 1}}
3> erli18n_plural:compile(<<"nplurals=2; plural=n/0;">>).
{error,{unsafe_plural_rule,{division_by_zero,'/'}}}
4> erli18n_plural:compile(<<"nplurals=2; plural=nx;">>).
{error,{syntax_error,{unknown_identifier_after_n,$x},1}}
5> erli18n_plural:compile(<<"nplurals=2;">>).
{error,{missing_plural_expr,<<"nplurals=2;">>}}

See also evaluate/2 (consume the bundle), plural_by_po_header/2 (compile+evaluate at once) and compile_error/0.

-spec evaluate(plural_compiled(), integer()) -> non_neg_integer().

Evaluates a compiled plural rule for a given N and returns the plural form index — the TOTAL hot-path function, used by every ngettext/npgettext.

Compiled is the bundle from compile/1; N is the count (an integer, may be negative — the rule decides the semantics). The return is always a non_neg_integer() in [0, NPlurals): the rule is interpreted and the result coerced to an integer.

Never raises, even on a malformed rule (parity with GNU libintl): division/modulo by zero is coerced to 0 (eval_div/2/eval_rem/2 instead of letting div/rem raise badarith) and a form outside [0, NPlurals) is clamped to 0 (if index >= nplurals -> index = 0).

No allocations beyond the return value and no result cache: the cost is re-paying the AST interpretation on every call — which is why the compile/1 caps keep the AST small. A negative N is passed through without abs(); the rule decides the semantics (and the clamp protects the result).

1> {ok, C} = erli18n_plural:compile(<<"nplurals=2; plural=n != 1;">>).
2> erli18n_plural:evaluate(C, 1).
0
3> erli18n_plural:evaluate(C, 5).
1
%% Divisor DEPENDS on n (passes compile/1's static check),
%% but evaluates to zero at runtime for N=7: clamp to 0, no crash.
4> {ok, Bad} = erli18n_plural:compile(<<"nplurals=2; plural=1/(n-7);">>).
5> erli18n_plural:evaluate(Bad, 7).
0

Edge cases: the short-circuit of &&/|| is honoured, so a zero divisor behind a false branch is never reached. To OBSERVE the anomaly (instead of silent clamping) use evaluate_checked/2. See also compile/1 and plural_by_po_header/2.

-spec evaluate_checked(plural_compiled(), integer()) ->
                          {ok, non_neg_integer()} | {error, plural_eval_error()}.

Structured sibling of evaluate/2: instead of clamping silently, it reports a malformed rule as data so the consumer can log/alert.

Compiled and N are as in evaluate/2. Returns {ok, Form} with the form in [0, NPlurals), or {error, plural_eval_error()}: {division_by_zero, '/' | '%'} when the evaluated divisor is 0, or {form_out_of_range, Form, NPlurals} when the form leaves the range. It keeps the short-circuit of &&/|| (a zero divisor behind a false branch is not reported) and, like evaluate/2, is total — never raises.

Use this off the hot path, when you want to log/alert the malformed rule; on the hot path stay with evaluate/2, whose clamp is cheaper. Where evaluate/2 would return 0 by clamping, this function returns the corresponding {error, _}.

1> {ok, C} = erli18n_plural:compile(<<"nplurals=2; plural=n != 1;">>).
2> erli18n_plural:evaluate_checked(C, 5).
{ok,1}
%% Same rule as the evaluate/2 example (divisor depends on n).
%% Where evaluate/2 would clamp to 0, here the anomaly comes back as data.
3> {ok, Bad} = erli18n_plural:compile(<<"nplurals=2; plural=1/(n-7);">>).
4> erli18n_plural:evaluate_checked(Bad, 7).
{error,{division_by_zero,'/'}}
5> erli18n_plural:evaluate_checked(Bad, 8).
{ok,1}

Edge cases: a form outside [0, NPlurals) (where evaluate/2 would clamp) becomes {error, {form_out_of_range, Form, NPlurals}}. See also evaluate/2 (the sibling that clamps) and plural_eval_error/0.

-spec fallback_rule() -> binary().

Fallback plural rule used when a .po catalog ships no Plural-Forms: header at all (a degenerate but tolerated input).

Returns <<"nplurals=2; plural=n != 1;">> — the Germanic C/English default cited by the GNU gettext manual (§"Plural forms").

A pure constant, no side effects. The result is a raw header ready for compile/1, so the loader's fallback path reuses exactly the same pipeline as a legitimate header.

1> erli18n_plural:fallback_rule().
<<"nplurals=2; plural=n != 1;">>
2> {ok, C} = erli18n_plural:compile(erli18n_plural:fallback_rule()),
2> erli18n_plural:evaluate(C, 1).
0

See also compile/1 and cldr_rule/1.

-spec plural_by_po_header(binary(), integer()) -> {ok, non_neg_integer()} | {error, compile_error()}.

Convenience that compiles and evaluates in a single step: given the raw header Header and the count N, returns {ok, Form} or propagates the {error, compile_error()} from compile/1.

Recompiles on every call, so it is for one-off use; on the hot path, call compile/1 once at load and reuse the bundle with evaluate/2.

The internal evaluation uses evaluate/2 (total), so an {ok, _} never embeds an evaluation anomaly — the only part that can fail is compile/1, whose error is propagated as-is.

1> erli18n_plural:plural_by_po_header(<<"nplurals=2; plural=n != 1;">>, 1).
{ok,0}
2> erli18n_plural:plural_by_po_header(<<"nplurals=2; plural=n != 1;">>, 3).
{ok,1}
3> erli18n_plural:plural_by_po_header(<<"nplurals=2; plural=nx;">>, 1).
{error,{syntax_error,{unknown_identifier_after_n,$x},1}}

See also compile/1 and evaluate/2.

-spec validate_against_cldr(binary(), binary()) ->
                               ok | {warning, {plural_divergence, binary(), binary(), binary()}}.

Compares the plural expression of header HeaderRule (raw form) against the CLDR canonical rule of Locale, producing only observability — at runtime the header always wins (PSD-004).

Compiles HeaderRule ONCE and delegates to validate_against_cldr_ast/2. Returns ok when the (nplurals, expr) ASTs are structurally equal (whitespace/paren-insensitive) or when the locale has no CLDR entry; returns {warning, {plural_divergence, Locale, HeaderRule, CldrRaw}} when they diverge — including when the header is invalid but the locale is listed in CLDR.

A convenience entry point for callers that only have the raw header. The catalog loader, which already keeps the compiled bundle, should use validate_against_cldr_ast/2 to avoid recompiling the header at load.

The comparison is STRUCTURAL over the (nplurals, expr-AST) pair, so it is insensitive to whitespace and redundant parentheses: (n != 1) matches n != 1. Nothing changes at runtime — the warning exists only for telemetry.

%% Header agrees with fr's CLDR (n > 1): no warning.
1> erli18n_plural:validate_against_cldr(<<"fr">>, <<"nplurals=2; plural=(n > 1);">>).
ok
%% Header diverges from fr's CLDR: warning (but the header would win at runtime).
2> erli18n_plural:validate_against_cldr(<<"fr">>, <<"nplurals=2; plural=n != 1;">>).
{warning,{plural_divergence,<<"fr">>,<<"nplurals=2; plural=n != 1;">>,<<"n > 1">>}}
%% Locale with no CLDR entry: nothing to validate.
3> erli18n_plural:validate_against_cldr(<<"xx">>, <<"nplurals=2; plural=n != 1;">>).
ok

Edge cases: an INVALID header against a locale that IS listed in CLDR still produces {warning, _} (it cannot match the canonical rule); against a locale with no CLDR entry it becomes ok. See also validate_against_cldr_ast/2 (variant without recompiling) and cldr_rule/1.

-spec validate_against_cldr_ast(binary(), plural_compiled()) ->
                                   ok | {warning, {plural_divergence, binary(), binary(), binary()}}.

AST-based variant of validate_against_cldr/2: takes the ALREADY compiled bundle (plural_compiled()) and compares it against the CLDR rule of Locale without recompiling anything (finding #17).

Reuses the header AST as-is and takes the CLDR side from a memoised table of compiled bundles, so no rule is re-parsed at load. Returns ok if the (nplurals, expr) pairs match or if the locale has no CLDR entry; otherwise {warning, {plural_divergence, Locale, HeaderRaw, CldrRaw}}, with the raw header (the bundle's raw field) and the raw CLDR expression.

This is the PREFERRED form in the loader (finding #17): since the bundle was already compiled by compile/1 at load, it avoids the second compile/1 that validate_against_cldr/2 would do, and the CLDR side comes from the persistent_term cache (cldr_compiled_table/0), not re-synthesised per load.

1> {ok, C} = erli18n_plural:compile(<<"nplurals=2; plural=n != 1;">>).
2> erli18n_plural:validate_against_cldr_ast(<<"fr">>, C).
{warning,{plural_divergence,<<"fr">>,<<"nplurals=2; plural=n != 1;">>,<<"n > 1">>}}
3> {ok, Cde} = erli18n_plural:compile(<<"nplurals=2; plural=n != 1;">>).
4> erli18n_plural:validate_against_cldr_ast(<<"de">>, Cde).
ok

Edge cases: a locale with no CLDR entry becomes ok (nothing to log). See also validate_against_cldr/2 (from the raw header) and cldr_compiled/1 (the memoisation of the CLDR side).