NAME
Locale::Unicode::RBNF::CLDR - CLDR data loader for Locale::Unicode::RBNF
SYNOPSIS
use Locale::Unicode::RBNF::CLDR;
my $st;
my $cldr = Locale::Unicode::RBNF::CLDR->new( '/path/to/cldr/common', \$st );
my( $rules, $found ) = $cldr->rbnf_rules( 'fr_CH', 'SpelloutRules' );DESCRIPTION
This module loads the data required by Locale::Unicode::RBNF from a CLDR common directory: rbnf/*.xml, main/*.xml, supplemental/supplementalData.xml, supplemental/numberingSystems.xml, supplemental/plurals.xml and supplemental/ordinals.xml.
Both the current RBNF XML format, where a rule set grouping holds the rules in ICU syntax in a rbnfRules element, and the legacy format of earlier releases (such as CLDR 44), with ruleset and rbnfrule elements, are supported.
The parsed files are cached per CLDR directory, for the duration of the process.
The methods in this class use locales as a CLDR file identifier, such as fr_CH, which is the file names format used in the CLDR data. "canonical_locale" converts a BCP 47 identifier, such as fr-CH, or a Locale::Unicode object, into that form.
CONSTRUCTOR
new
my $st;
my $cldr = Locale::Unicode::RBNF::CLDR->new( '/path/to/cldr/common', \$st );
die( $st ) if( $st );Takes the path to a CLDR common directory and a scalar reference that receives an error status, and returns a new object.
The object is always returned. If the directory does not exist or has no rbnf sub-directory, the status is set to a U_MISSING_RESOURCE_ERROR message, and the caller must check it.
METHODS
canonical_locale
my $st;
my( $file_id, $numbering_system, $locale ) = $cldr->canonical_locale( 'zh-hant-tw-u-nu-hanidec', \$st );
# zh_Hant_TW, hanidec, and the Locale::Unicode object zh-Hant-TW-u-nu-hanidec
die( $st ) if( $st );Takes a locale, as a BCP 47 identifier, such as fr-CH, as a CLDR identifier, such as fr_CH, or as a Locale::Unicode object, and an optional scalar reference that receives an error status. It can be called as a class method.
The locale is parsed and canonicalised with Locale::Unicode, and converted to the CLDR file identifier, language_Script_REGION_VARIANT, such as fr_CH, zh_Hant_TW or en_US_POSIX, which is the form the other methods of this class take. Extensions are not part of it.
It returns a list of 3 elements: the CLDR file identifier; the numbering system requested with a -u-nu- extension, or undef if there is none; and the canonical Locale::Unicode object. An undefined or empty locale, root and und all yield root, and the object is then root rather than its canonical form und.
If the locale cannot be parsed, or has no language subtag, such as x-private, it returns an empty list, and sets the status to a U_ILLEGAL_ARGUMENT_ERROR message. The ICU keyword syntax, such as fr_CH@numbers=latn, is not supported.
chain
my @chain = $cldr->chain( 'fr_CH' );
# fr_CH, fr, rootReturns the list of locales of the inheritance chain, from the locale itself up to and including root, following "parent_locale".
context_transforms
my $transforms = $cldr->context_transforms( 'fr' );Returns an array reference of 2 booleans, for the uiListOrMenu and stand-alone contexts respectively, each true when the number-spellout context transform of the locale is titlecase-firstword, that is when the first word of a spelled-out number must be titlecased in that context. The values are resolved with inheritance, and draft values that ICU ignores, unconfirmed and provisional, are ignored here too.
decimal_pattern
my $pattern = $cldr->decimal_pattern( 'hi', 'deva' );Returns the standard decimal pattern of the locale for the given numbering system, resolved with inheritance. If the numbering system has none, the pattern of latn is used, and failing that #,##0.###. Results are cached.
default_numbering_system
my $ns = $cldr->default_numbering_system( 'ar_EG' );Returns the default numbering system of the locale, resolved with inheritance, or latn if none is found.
digits
my $digits = $cldr->digits( 'arab' );Returns the ten digits of a numeric numbering system as a string, as found in supplemental/numberingSystems.xml, or undef if the numbering system is unknown or algorithmic.
dir
Returns the CLDR common directory given to "new".
parent_locale
my $parent = $cldr->parent_locale( 'en_AU' );
# en_001Returns the parent locale, as defined by the parentLocales of supplemental/supplementalData.xml that are not specific to a component, or otherwise by truncation of the last subtag. It returns root for a language-only locale, and an empty list for root.
plural_rules
my $rules = $cldr->plural_rules( 'fr', 'cardinal' );
my $rules = $cldr->plural_rules( 'fr', 'ordinal' );Returns an array reference of array references [ keyword, condition ], in the order of the CLDR data, for the cardinal rules of supplemental/plurals.xml or the ordinal rules of supplemental/ordinals.xml. This is suitable for "new" in Locale::Unicode::RBNF::PluralRules.
As ICU does, the rules are looked up by truncation of the locale, not through the parentLocales, which only apply to the main data: sr_Latn uses the rules of sr. If nothing is found, the rules of root are returned, or an empty array reference.
rbnf_groupings
my $groupings = $cldr->rbnf_groupings( 'ja' );
my $groupings = $cldr->rbnf_groupings( $xml_libxml_document );Returns an array reference of hash references, one per rulesetGrouping of an RBNF file, in document order, with the keys grouping (such as SpelloutRules), rule_sets and lenient_parse, as returned by "rule_sets_from_description" in Locale::Unicode::RBNF. There is no locale inheritance here: only the given file is read.
It accepts an XML::LibXML document, for instance one loaded and patched by a build script, or a locale.
It returns an empty array reference if the RBNF file does not exist, and dies if the rules of a grouping cannot be divided into rule sets.
rbnf_locales
my $locales = $cldr->rbnf_locales;Returns an array reference of the locales that have a file in the rbnf directory, sorted.
rbnf_rules
my( $description, $locale_found ) = $cldr->rbnf_rules( 'fr_CH', 'SpelloutRules' );Returns the rule description of a grouping, such as SpelloutRules, OrdinalRules or NumberingSystemRules, in the ICU syntax, following the locale inheritance chain, together with the locale where it was found. It returns an empty list if no locale of the chain has that grouping.
Rules provided in the legacy format, with ruleset and rbnfrule elements, are converted to the ICU syntax.
symbols
my $symbols = $cldr->symbols( 'fr', 'latn' );Returns an hash reference of the decimal format symbols of the locale for the given numbering system, resolved with inheritance, and following the aliases to other numbering systems. The keys are decimal, group, minus, plus, percent, per_mille, infinity, nan, digits (an array reference of the 10 digits of the numbering system) and numbering_system.
The values of root are used for any symbol the data does not provide. A new hash reference is returned on each call, so it can be modified freely.
AUTHOR
Jacques Deguest <jack@deguest.jp>
COPYRIGHT & LICENSE
Copyright(c) 2026 DEGUEST Pte. Ltd.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.