blib/lib/AmberDB/Locale.pm untested

filter: Statementstmt 0.0% 0 / 622 Branchbran 0.0% 0 / 304 Conditioncond 0.0% 0 / 392 MC/DCmcdc 0.0% 0 / 210 Subroutinesub 0.0% 0 / 45 Podpod 0.0% 0 / 30 totaltotal 0.0% 0 / 1603 CC 153 SCAR 64.3
CC
153
Cov
0%
num2text
2352.0
normalize_word
156.0
format_number
132.0
CRAP 617.2
1 package AmberDB::Locale;
2  
3 use 5.016;
4 use warnings;
5 use utf8;
6 use Encode qw(decode encode);
7 use Carp qw(croak cluck);
8  
9 our $VERSION = '5.26.6';
10 my $CREATED = '2017-07-22';
11  
12 my %LOCALE_CACHE;
13 my %WARNED_LOCALES;
14  
15 # -------------------------------------------------------
16 # AmberDB::Locale — Locale-aware string operations
17 #
18 # Formerly a Turkish-only module; now a generic locale
19 # engine that loads per-language data from AmberDB::Locale::Lang::*
20 #
21 # USAGE:
22 # # New API (explicit language):
23 # my $lang = AmberDB::Locale->new(language => "gb");
24 # my $lang = AmberDB::Locale->new(language => "tr");
25 #
26 # # With AmberDB engine (language from cfg, defaults to "gb"):
27 # AmberDB->new(cfg => { language => "gb" });
28 # # then $self->uc($str) works on the inherited object
29 # -------------------------------------------------------
30  
31  
32 # -------------------------------------------------------
33 # Constructor
34 # -------------------------------------------------------
35 sub new {
36 my $class = shift;
37  
38 my $lang;
39  
40 # Handle calling conventions:
41 # 1. new(language => "gb") — named-param API
42 # 2. new({ language => "gb" }) — unblessed hash ref API
43 # 3. new("gb") — positional string API
44 # 4. new() — no args; use default ("gb")
45 if ( @_ ) {
46 if ( @_ == 1 && !ref( $_[0] ) ) {
47 $lang = $_[0];
48 }
49 elsif ( @_ == 1 && ref( $_[0] ) eq 'HASH' ) {
50 $lang = $_[0]->{language} || $_[0]->{lang};
51 }
52 elsif ( @_ % 2 == 0 && !ref( $_[0] ) ) {
53 my %args = @_;
54 $lang = $args{language} || $args{lang};
55 }
56 }
57  
58 my %LANG_ALIAS = (
59 'turkish' => 'tr',
60 'tr_tr' => 'tr',
61 'tr-tr' => 'tr',
62 'english' => 'en',
63 'en_us' => 'en',
64 'en_gb' => 'gb',
65 'german' => 'de',
66 'de_de' => 'de',
67 'french' => 'fr',
68 'fr_fr' => 'fr',
69 'spanish' => 'es',
70 'es_es' => 'es',
71 'russian' => 'ru',
72 'ru_ru' => 'ru',
73 'arabic' => 'ar',
74 'ar_sa' => 'ar',
75 'azerbaijani' => 'az',
76 'az_az' => 'az',
77 'japanese' => 'ja',
78 'ja_jp' => 'ja',
79 'ja-jp' => 'ja',
80 'global' => 'gb',
81 'gb' => 'gb',
82 'gl' => 'gb',
83 'universal' => 'gb',
84 'uni' => 'gb',
85 'gb_base' => 'gb',
86 );
87  
88 $lang = lc( $lang // '' );
89 $lang =~ s/[^\w-]//g;
90 my $norm_lang = $LANG_ALIAS{$lang} || ( split /[_-]/, $lang )[0] || 'gb';
91  
92 # Fast path: instance cache lookup (keyed by class + normalized language)
93 my $cache_key = "${class}::${norm_lang}";
94 return $LOCALE_CACHE{$cache_key} if $LOCALE_CACHE{$cache_key};
95  
96 my $self = bless { _lang => $norm_lang }, $class;
97 $self->_load_locale($norm_lang);
98  
99 if ( $self->{_lang} ) {
100 $LOCALE_CACHE{$cache_key} = $self;
101 $LOCALE_CACHE{"${class}::$self->{_lang}"} = $self;
102 }
103  
104 return $self;
105 }
106  
107 # -------------------------------------------------------
108 # Load locale data from AmberDB::Locale::Lang::<lang>
109 # Falls back to 'gb' if requested locale not found.
110 # -------------------------------------------------------
111 sub _load_locale {
112 my ( $self, $lang ) = @_;
113  
114 $lang ||= 'gb';
115 $self->{_lang} = $lang;
116  
117 my $locale_class = "AmberDB::Locale::Lang::$lang";
118 my $loaded = eval {
119 ( my $path = $locale_class ) =~ s|::|/|g;
120 require "$path.pm";
121 1;
122 };
123  
124 unless ($loaded) {
125 if ( $lang ne 'gb' ) {
126 unless ( $WARNED_LOCALES{$lang}++ ) {
127 cluck "AmberDB::Locale: locale '$lang' not found, falling back to 'gb'\n";
128 }
129 $locale_class = 'AmberDB::Locale::Lang::gb';
130 require AmberDB::Locale::Lang::gb;
131 $self->{_lang} = 'gb';
132 }
133 }
134  
135 $self->{_locale} = $locale_class->data();
136  
137 # Initialize Unicode::Collate::Locale for UCA standard collation
138 eval {
139 require Unicode::Collate::Locale;
140 $self->{_collator} = Unicode::Collate::Locale->new( locale => $lang );
141 1;
142 } or do {
143 # Fallback to base Unicode::Collate if locale-specific table is unavailable
144 eval {
145 require Unicode::Collate;
146 $self->{_collator} = Unicode::Collate->new();
147 1;
148 };
149 };
150  
151 $self->_compile_patterns();
152 return $self;
153 }
154  
155 # -------------------------------------------------------
156 # Pre-compile regex patterns from locale data
157 # Called once at construction time — not on each method call.
158 # -------------------------------------------------------
159 sub _compile_patterns {
160 my ($self) = @_;
161 my $loc = $self->{_locale};
162  
163 # uc_map regex — sort keys by length descending to match longer patterns first
164 if ( my %uc = %{ $loc->{uc_map} || {} } ) {
165 my @keys = sort { length($b) <=> length($a) } keys %uc;
166 my $chars = join '|', map { quotemeta $_ } @keys;
167 $self->{_uc_re} = qr/($chars)/;
168 }
169  
170 # lc_map regex — sort keys by length descending
171 if ( my %lc = %{ $loc->{lc_map} || {} } ) {
172 my @keys = sort { length($b) <=> length($a) } keys %lc;
173 my $chars = join '|', map { quotemeta $_ } @keys;
174 $self->{_lc_re} = qr/($chars)/;
175 }
176  
177 # sort_map regex
178 if ( my %sm = %{ $loc->{sort_map} || {} } ) {
179 my @keys = sort { length($b) <=> length($a) } keys %sm;
180 my $chars = join '|', map { quotemeta $_ } @keys;
181 $self->{_sort_re} = qr/($chars)/;
182 }
183  
184 # accent_map regex
185 if ( my %am = %{ $loc->{accent_map} || {} } ) {
186 my @keys = sort { length($b) <=> length($a) } keys %am;
187 my $chars = join '|', map { quotemeta $_ } @keys;
188 $self->{_accent_re} = qr/($chars)/;
189 }
190  
191 # ascii_map regex
192 if ( my %as = %{ $loc->{ascii_map} || {} } ) {
193 my @keys = sort { length($b) <=> length($a) } keys %as;
194 my $chars = join '|', map { quotemeta $_ } @keys;
195 $self->{_ascii_re} = qr/($chars)/;
196 }
197  
198 # regex_map regex for search pattern generation
199 if ( my %rm = %{ $loc->{regex_map} || {} } ) {
200 my @keys = sort { length($b) <=> length($a) } keys %rm;
201 my $chars = join '|', map { quotemeta $_ } @keys;
202 $self->{_search_re} = qr/($chars)/;
203 $self->{_search_map} = \%rm;
204 }
205  
206 # Pre-compile phonetic assimilation / final-devoicing rules
207 if ( my $pm = $loc->{phonetic_map} ) {
208 my @rules;
209 if ( ref($pm) eq 'HASH' ) {
210 foreach my $pat ( keys %$pm ) {
211 push @rules, [ qr/$pat/i, $pm->{$pat} ];
212 }
213 }
214 elsif ( ref($pm) eq 'ARRAY' ) {
215 foreach my $pair (@$pm) {
216 my ( $pat, $sub ) = @$pair;
217 push @rules, [ qr/$pat/i, $sub ];
218 }
219 }
220 $self->{_phonetic_rules} = \@rules;
221 }
222  
223 # Safe-text character class (alphabet_chars extends a-zA-Z)
224 my $extra = $loc->{alphabet_chars} || '';
225 my $safe_extra = quotemeta($extra);
226 $self->{_letter_chars} = "a-zA-Z${safe_extra}";
227 $self->{_safe_re} = qr/[^a-zA-Z${safe_extra}0-9&.,_\-;:()\s]/;
228 $self->{_letter_re} = qr/[a-zA-Z${safe_extra}]/;
229  
230 my @splitters = @{ $loc->{word_splitters} || [ "'", "\x{2019}", "\x{2018}", "\x{2032}", "\x{02BC}", "-" ] };
231 my $split_chars = join '', map { quotemeta($_) } @splitters;
232 $self->{_splitter_re} = qr/[$split_chars]/;
233  
234 # Combined html_entities: universal + locale-specific extras
235 $self->{_html_entities} = {
236 # Universal entities
237 '&amp;' => '&', '&lt;' => '<',
238 '&gt;' => '>', '&quot;' => '"',
239 '&apos;' => "'", '&nbsp;' => ' ',
240 '&euro;' => "\x{20AC}", '&laquo;' => "\x{AB}",
241 '&raquo;' => "\x{BB}", '&lsquo;' => "\x{2018}",
242 '&rsquo;' => "\x{2019}", '&ldquo;' => "\x{201C}",
243 '&rdquo;' => "\x{201D}", '&hellip;' => "\x{2026}",
244 '&ndash;' => "\x{2013}", '&mdash;' => "\x{2014}",
245 '&bull;' => "\x{2022}", '&trade;' => "\x{2122}",
246 '&copy;' => "\x{00A9}", '&reg;' => "\x{00AE}",
247 # Locale-specific extras (override/extend universals)
248 %{ $loc->{html_entities} || {} },
249 };
250  
251 return $self;
252 }
253  
254 # =======================================================
255 # PUBLIC API — UTF-8 Encoding / Decoding & String Operations
256 # =======================================================
257  
258 # -------------------------------------------------------
259 # utf_encode: Converts a Perl Unicode string into raw UTF-8 octets (bytes).
260 # my $bytes = $lang->utf_encode($string);
261 # -------------------------------------------------------
262 sub utf_encode {
263 my ( $self, $string ) = @_;
264 return unless defined $string;
265 $string =~ s/^\x{FEFF}//;
266 utf8::encode($string) if utf8::is_utf8($string);
267 $string =~ s/^\xEF\xBB\xBF//;
268 return $string;
269 }
270  
271 # -------------------------------------------------------
272 # utf_decode: Decodes raw UTF-8 bytes into a Perl Unicode character string.
273 # Strips BOM if present.
274 # my $chars = $lang->utf_decode($string);
275 # -------------------------------------------------------
276 sub utf_decode {
277 my ( $self, $string ) = @_;
278 return unless defined $string;
279 $string =~ s/^\xEF\xBB\xBF//;
280 utf8::decode($string) unless utf8::is_utf8($string);
281 $string =~ s/^\x{FEFF}//;
282 return $string;
283 }
284  
285 # -------------------------------------------------------
286 # Locale-aware uppercase.
287 # Applies uc_map substitutions before Perl's CORE::uc().
288 # my $upper = $lang->uc($string);
289 # -------------------------------------------------------
290 sub uc {
291 my ( $self, $string ) = @_;
292 return unless defined $string;
293 $string = $self->utf_decode($string);
294 if ( my $re = $self->{_uc_re} ) {
295 my $uc_map = $self->{_locale}{uc_map};
296 $string =~ s/$re/$uc_map->{$1}/ge;
297 }
298 return CORE::uc($string);
299 }
300  
301 # -------------------------------------------------------
302 # Locale-aware lowercase.
303 # Applies lc_map substitutions before Perl's CORE::lc().
304 # my $lower = $lang->lc($string);
305 # -------------------------------------------------------
306 sub lc {
307 my ( $self, $string ) = @_;
308 return unless defined $string;
309 $string = $self->utf_decode($string);
310 if ( my $re = $self->{_lc_re} ) {
311 my $lc_map = $self->{_locale}{lc_map};
312 $string =~ s/$re/$lc_map->{$1}/ge;
313 }
314 return CORE::lc($string);
315 }
316  
317 # -------------------------------------------------------
318 # Converts search query string into a locale-aware regex pattern.
319 # Replaces locale-specific casing characters with regex match patterns.
320 # my $pattern = $lang->search_pattern($query);
321 # -------------------------------------------------------
322 sub search_pattern {
323 my ( $self, $string ) = @_;
324 return '' unless defined $string;
325 $string = $self->utf_decode($string);
326 if ( my $re = $self->{_search_re} ) {
327 my $sm = $self->{_search_map};
328 $string =~ s/$re/$sm->{$1}/ge;
329 }
330 return $string;
331 }
332  
333 # -------------------------------------------------------
334 # Performs regex search matching of search pattern inside target text string.
335 # Does not re-normalize $aranan; performs matching directly.
336 # my $bool = $lang->search_regex($string, $aranan);
337 # -------------------------------------------------------
338 sub search_regex {
339 my ( $self, $string, $aranan ) = @_;
340 return 0 unless defined $string && defined $aranan && length($aranan);
341 $string = $self->utf_decode($string);
342 $aranan = $self->utf_decode($aranan);
343 return $string =~ /$aranan/i ? 1 : 0;
344 }
345  
346 # -------------------------------------------------------
347 # Normalizes a single search token/word according to locale
348 # phonetic assimilation, clitic/apostrophe stripping, and final-devoicing rules.
349 # $mode_write = 1 | "write" -> "Türkiye'de" => "turkiye turkiyede"
350 # $mode_write = 0 | "read" -> "Türkiye'de" => "turkiye"
351 # $no_ascii = 1 | "no_ascii" -> Harf tablosunu korur (ASCII/fonetik dönüştürmez)
352 # Sadece string girilirse varsayılan olarak okuma modunda (is_write = 0, no_ascii = 0) çalışır.
353 # my $norm = $lang->normalize_word($word, $mode_write, $no_ascii);
354 # -------------------------------------------------------
355 sub normalize_word {
356 my ( $self, $word, $mode_write, $no_ascii ) = @_;
357 return '' unless defined $word && length($word);
358  
359 my $is_write = ( $mode_write && $mode_write ne 'read' && $mode_write ne '0' ) ? 1 : 0;
360 $no_ascii = ( $no_ascii && $no_ascii ne 'ascii' && $no_ascii ne '0' ) ? 1 : 0;
361  
362 # Fast in-memory cache check
363 my $cache_key = ( !$is_write && !$no_ascii ) ? $word : "$word:$is_write:$no_ascii";
364 if ( defined $self->{_cache}{nw}{$cache_key} ) {
365 return $self->{_cache}{nw}{$cache_key};
366 }
367  
368 $word = $self->utf_decode($word);
369  
370 my $lc = $self->{_letter_chars} || 'a-zA-Z';
371 my $S = $self->{_splitter_re} || qr/['’‘′ʼ\-]/;
372  
373 if ($is_write) {
374 # Yazma modunda: Kök ($1) ve Birleşik ($1$2) türetilir, ek ($2) tek başına alınmaz
375 $word =~ s/([$lc]+)$S+([$lc]+)/$1 $1$2/g;
376 }
377 else {
378 # Okuma/Arama modunda: Kök ($1) yeterlidir (tek harfli ön eklerde birleşik $1$2 alınır: örn. T-Shirt -> tshirt)
379 $word =~ s/([$lc]+)$S+([$lc]+)/(length($1) > 1 ? $1 : "$1$2")/ge;
380 }
381  
382 my @parts;
383 foreach my $w ( split /\s+/, $word ) {
384 next unless length $w;
385 $w = $self->lc($w);
386  
387 if (!$no_ascii) {
388 $w = $self->to_ascii($w);
389  
390 if ( my $rules = $self->{_phonetic_rules} ) {
391 foreach my $rule (@$rules) {
392 my ( $re, $sub ) = @$rule;
393 $w =~ s/$re/$sub/g;
394 }
395 }
396 $w =~ s/^[^a-z0-9]+|[^a-z0-9]+$//g;
397 push @parts, $w if length $w;
398 }
399 else {
400 # no_ascii mode: alphabet_chars dışındakileri temizle
401 $w =~ s/[^0-9${lc}]+/ /g;
402 $w =~ s/^\s+|\s+$//g;
403 push @parts, grep { length } split /\s+/, $w if length $w;
404 }
405 }
406  
407 my $res = join( " ", @parts );
408 $self->{_cache}{nw}{$cache_key} = $res;
409 return $res;
410 }
411  
412 # -------------------------------------------------------
413 # Case-folded string normalization for search indexing / matching.
414 # Normalizes string using NFKC decomposition and locale lowercasing.
415 # my $folded = $lang->fold($string);
416 # -------------------------------------------------------
417 sub fold {
418 my ( $self, $string ) = @_;
419 return '' unless defined $string;
420 require Unicode::Normalize;
421 $string = $self->lc($string);
422 return Unicode::Normalize::NFKC($string);
423 }
424  
425 # -------------------------------------------------------
426 # Locale-aware case-insensitive equality comparison.
427 # Returns 1 if strings are equal under locale rules, 0 otherwise.
428 # my $bool = $lang->ieq($str1, $str2);
429 # -------------------------------------------------------
430 sub ieq {
431 my ( $self, $s1, $s2 ) = @_;
432 return 1 if !defined($s1) && !defined($s2);
433 return 0 if !defined($s1) || !defined($s2);
434 return $self->fold($s1) eq $self->fold($s2);
435 }
436  
437 # -------------------------------------------------------
438 # Locale-aware ucfirst — capitalize first letter of each word.
439 # my $str = $lang->ucfirst($string);
440 # -------------------------------------------------------
441 sub ucfirst {
442 my ( $self, $string ) = @_;
443 return unless defined $string;
444 $string = $self->lc($string);
445 $string =~ s/\A(\S)/$self->uc($1)/e;
446 $string =~ s/([\s.!:"\/)(])(\S)/$1 . $self->uc($2)/ge;
447 return $string;
448 }
449  
450 # -------------------------------------------------------
451 # Locale-aware sort using Unicode::Collate::Locale.
452 #
453 # Provides 100% standard Unicode Collation Algorithm (UCA)
454 # compliance for any locale (tr, de, fr, ru, ar, ja...).
455 # Unicode::Collate::Locale is a Perl core module (since 5.12).
456 #
457 # @sorted = $lang->sort(\@list);
458 # @sorted = $lang->sort(\@list, $field_name_or_index);
459 # -------------------------------------------------------
460 sub sort {
461 my ( $self, $liste, $blok ) = @_;
462 return () unless $liste && ref($liste) eq 'ARRAY' && @$liste;
463  
464 # Helper: extract value for comparison from item (scalar, arrayref, or hashref)
465 my $get_val = sub {
466 my ($item) = @_;
467 return '' unless defined $item;
468 if ( !ref($item) ) {
469 return $item;
470 }
471 elsif ( ref($item) eq 'ARRAY' && defined $blok && $blok ne '' ) {
472 return $item->[$blok] // '';
473 }
474 elsif ( ref($item) eq 'HASH' && defined $blok && $blok ne '' ) {
475 return $item->{$blok} // '';
476 }
477 return "$item";
478 };
479  
480 # Primary: Unicode::Collate::Locale engine
481 if ( my $collator = $self->{_collator} ) {
482 if ( defined($blok) && $blok ne '' ) {
483 return sort {
484 $collator->cmp( $get_val->($a), $get_val->($b) );
485 } @$liste;
486 }
487 return $collator->sort(@$liste);
488 }
489  
490 # Fallback: custom sort_map Schwartzian transform
491 my $sort_map = $self->{_locale}{sort_map} || {};
492 my $sort_re = $self->{_sort_re};
493  
494 my $make_key = sub {
495 my $s = $self->lc( $_[0] );
496 $s =~ s/([a-z])/$1$1/g;
497 $s =~ s/$sort_re/$sort_map->{$1}/g if $sort_re;
498 $s;
499 };
500  
501 if ( defined($blok) && $blok ne '' ) {
502 return map { $_->[0] }
503 sort { $a->[1] cmp $b->[1] }
504 map { [ $_, $make_key->( $get_val->($_) ) ] }
505 @$liste;
506 }
507  
508 return map { $_->[0] }
509 sort { $a->[1] cmp $b->[1] }
510 map { [ $_, $make_key->( $get_val->($_) ) ] }
511 @$liste;
512 }
513  
514 # -------------------------------------------------------
515 # Decode HTML entities (numeric + named universal + locale).
516 # my $str = $lang->decode_entities($string);
517 # -------------------------------------------------------
518 sub decode_entities {
519 my ( $self, $string ) = @_;
520 return unless defined $string;
521  
522 $string =~ s/&#x([0-9a-fA-F]+);/chr(hex($1))/ge;
523 $string =~ s/&#([0-9]+);/chr($1)/ge;
524 my $ent = $self->{_html_entities};
525 $string =~ s{(&[a-zA-Z]+;)}{ $ent->{$1} // $1 }ge;
526  
527 return $string;
528 }
529  
530 # -------------------------------------------------------
531 # Normalize accented/exotic chars to locale equivalents,
532 # strip HTML tags and characters not valid in locale text.
533 # my $str = $lang->normalize($string);
534 # -------------------------------------------------------
535 sub normalize {
536 my ( $self, $string ) = @_;
537 return unless defined $string;
538  
539 $string = $self->decode_entities($string);
540 $string =~ s/<[^>]+>/ /g;
541 $string =~ s/&[a-z0-9]+;/ /g;
542  
543 if ( my $re = $self->{_accent_re} ) {
544 my $am = $self->{_locale}{accent_map};
545 $string =~ s/$re/$am->{$1}/g;
546 }
547  
548 my $safe_re = $self->{_safe_re};
549 $string =~ s/$safe_re/ /g;
550 $string =~ s/^\s+|\s+$//g;
551 $string =~ s/\s+/ /g;
552  
553 return $string;
554 }
555  
556 # Private helper: normalize script digits (Eastern Arabic ٠-٩) & decimal separators
557 sub normalize_num {
558 my ($self, $num) = @_;
559 return '' unless defined $num;
560 $num =~ tr/٠١٢٣٤٥٦٧٨٩۰۱۲۳۴٥۶۷۸۹/01234567890123456789/;
561 $num =~ s/\x{066B}/./g;
562 return $num;
563 }
564  
565 # -------------------------------------------------------
566 # Convert locale string to plain ASCII (for slugs, IDs).
567 # -------------------------------------------------------
568 sub to_ascii {
569 my ( $self, $string, $nonspace ) = @_;
570 return unless defined $string;
571  
572 $string = $self->utf_decode($string);
573  
574 if ($nonspace) {
575 $string = $self->lc($string);
576 }
577  
578 $string = $self->normalize($string);
579  
580 if ( my $re = $self->{_ascii_re} ) {
581 my $am = $self->{_locale}{ascii_map};
582 $string =~ s/$re/$am->{$1}/g;
583 }
584  
585 require Unicode::Normalize;
586 $string = Unicode::Normalize::NFD($string);
587 $string =~ s/\p{M}//g;
588  
589 $string =~ s/[^a-z0-9&,.\-_ ]+/ /gi;
590 $string =~ s/\s+/ /g;
591  
592 if ($nonspace) {
593 $string = CORE::lc($string);
594 $string =~ s/\W+/-/g;
595 $string =~ s/[-_]*_[-_]*/_/g;
596 $string =~ s/-+/-/g;
597 $string =~ s/^[-_]+|[-_]+$//g;
598 }
599  
600 return $string;
601 }
602  
603 # -------------------------------------------------------
604 # First character of string (for alphabetical index).
605 # my $char = $lang->first_char($string);
606 # -------------------------------------------------------
607 sub first_char {
608 my ( $self, $string ) = @_;
609 $string =~ s/\s+//g;
610 return unless $string;
611 $string = $self->uc($string);
612 $string = $self->normalize($string);
613 $string = substr( $string, 0, 1 );
614 $string =~ /[0-9]/ and $string = '0-9';
615 return $string;
616 }
617  
618 # -------------------------------------------------------
619 # Convert number to locale words (for invoice/document printing).
620 #
621 # my $text = $lang->num2text($number);
622 # my $text = $lang->num2text($number, numbers => \%custom_data);
623 # my $text = $lang->num2text($number, currency => { main=>"EUR", sub=>"cent" });
624 #
625 # %custom_data can be a complete numbers hash or partial override.
626 # If locale has no numbers data, falls back to Global Base (gb).
627 # -------------------------------------------------------
628 sub num2text {
629 my ( $self, $num, %opts ) = @_;
630  
631 return '' unless defined $num;
632  
633 # Resolve numbers dataset: explicit override > locale > gb fallback
634 my $numbers;
635 if ( $opts{numbers} ) {
636 $numbers = $opts{numbers};
637 }
638 elsif ( $self->{_locale}{numbers} ) {
639 $numbers = $self->{_locale}{numbers};
640 }
641 else {
642 require AmberDB::Locale::Lang::gb;
643 $numbers = AmberDB::Locale::Lang::gb->data()->{numbers};
644 }
645  
646 # Normalize Eastern Arabic-Indic numerals and decimal separator
647 $num = $self->normalize_num($num);
648  
649 my $dec_sep = $numbers->{decimal_sep} || '.';
650 my $negative_prefix = $numbers->{negative} || 'Minus';
651  
652 # Clean leading/trailing whitespace
653 $num =~ s/^\s+|\s+$//g;
654 return $numbers->{zero} unless length($num);
655  
656 # Check for negative sign
657 my $is_negative = 0;
658 if ( $num =~ s/^\s*[-–—]\s*// ) {
659 $is_negative = 1;
660 }
661  
662 # Clean thousand separators based on decimal_sep convention
663 if ( $dec_sep eq ',' ) {
664 # Format 1.234,56 -> strip dots used as thousand separators
665 $num =~ s/\.(?=\d{3}(?:[^\d]|$))//g;
666 }
667 elsif ( $dec_sep eq '.' ) {
668 # Format 1,234.56 -> strip commas used as thousand separators
669 $num =~ s/,(?=\d{3}(?:[^\d]|$))//g;
670 }
671  
672 # Must contain at least one digit
673 unless ( $num =~ /\d/ ) {
674 return $numbers->{zero};
675 }
676  
677 my $ones = $numbers->{ones} || [];
678 my $tens = $numbers->{tens} || [];
679 my $hundred = $numbers->{hundred} || 'Hundred';
680 my $thousand = $numbers->{thousand} || 'Thousand';
681 my $million = $numbers->{million} || 'Million';
682 my $billion = $numbers->{billion} || 'Billion';
683 my $trillion = $numbers->{trillion} || 'Trillion';
684 my $currency = $opts{currency} || $numbers->{currency} || {};
685 my $thousand_one_prefix = $numbers->{thousand_one_prefix} // 1;
686 my $hundred_one_prefix = $numbers->{hundred_one_prefix} // 1;
687  
688 # Split integer and decimal parts using locale decimal separator or [.,]
689 my $dec_re = quotemeta($dec_sep);
690 my ( $ytl, $ykr ) = split /(?:$dec_re|[,.])/, $num, 2;
691  
692 $ytl =~ s/\D//g if defined $ytl;
693  
694 my ( $str_main, $str_sub );
695  
696 # Decimal/subunit part processing
697 if ( defined $ykr && $ykr =~ /\d/ ) {
698 $ykr =~ s/\D//g;
699 $ykr .= '0' if length($ykr) == 1;
700 $ykr = substr( $ykr, 0, 2 ) if length($ykr) > 2;
701  
702 my $ykr_num = int($ykr);
703 if ( $ykr =~ /[49]$/ ) {
704 $ykr_num++;
705 }
706  
707 # Overflow: 100 subunits rolls over +1 to main integer part
708 if ( $ykr_num >= 100 ) {
709 $ykr_num = 0;
710 $ytl = ( defined $ytl && length $ytl ? $ytl : 0 ) + 1;
711 }
712  
713 if ( $ykr_num > 0 ) {
714 my $t = int( $ykr_num / 10 );
715 my $o = $ykr_num % 10;
716 my $part = '';
717 $part .= $tens->[$t-1] . ' ' if $t > 0 && $tens->[$t-1];
718 $part .= $ones->[$o-1] if $o > 0 && $ones->[$o-1];
719 $part =~ s/\s+$//;
720 $str_sub = $part . ' ' . ( $currency->{sub} || '' ) if $part;
721 }
722 }
723  
724 # Integer/main part processing
725 if ( defined $ytl && $ytl ne '' && $ytl > 0 ) {
726 my @d = ( $ytl =~ /(.)/g );
727  
728 my $str = '';
729 my $ones_d = $d[-1] || 0;
730 my $tens_d = $d[-2] || 0;
731 my $hund_d = $d[-3] || 0;
732 my $th1_d = $d[-4] || 0;
733 my $th10_d = $d[-5] || 0;
734 my $th100_d = $d[-6] || 0;
735 my $mil1_d = $d[-7] || 0;
736 my $mil10_d = $d[-8] || 0;
737 my $mil100_d = $d[-9] || 0;
738 my $bil1_d = $d[-10] || 0;
739 my $bil10_d = $d[-11] || 0;
740 my $bil100_d = $d[-12] || 0;
741  
742 # Units (1-999)
743 $str = $ones->[$ones_d-1] || '' if $ones_d && $ones_d > 0;
744 if ($tens_d && $tens_d > 0) {
745 $str = $tens->[$tens_d-1] . ( $str ? " $str" : '' );
746 }
747 if ($hund_d && $hund_d > 0) {
748 my $h = ( $hund_d == 1 && !$hundred_one_prefix )
749 ? $hundred
750 : $ones->[$hund_d-1] . " $hundred";
751 $str = $h . ( $str ? " $str" : '' );
752 }
753  
754 # Thousands (1,000 - 999,999)
755 if ($th1_d || $th10_d || $th100_d) {
756 my $th_part = '';
757 if ($th1_d) {
758 my $prefix = ( $th1_d == 1 && !$th10_d && !$th100_d && !$thousand_one_prefix )
759 ? '' : $ones->[$th1_d-1] . ' ';
760 $th_part = $prefix;
761 }
762 $th_part = $tens->[$th10_d-1] . " $th_part" if $th10_d && $th10_d > 0;
763 if ($th100_d && $th100_d > 0) {
764 my $h = ( $th100_d == 1 && !$hundred_one_prefix )
765 ? $hundred
766 : $ones->[$th100_d-1] . " $hundred";
767 $th_part = "$h $th_part";
768 }
769 $th_part =~ s/\s+$//;
770 $str = "$th_part $thousand" . ( $str ? " $str" : '' );
771 }
772  
773 # Millions (1,000,000 - 999,999,999)
774 if ($mil1_d || $mil10_d || $mil100_d) {
775 my $mil_part = '';
776 $mil_part .= $ones->[$mil1_d-1] . ' ' if $mil1_d && $mil1_d > 0;
777 $mil_part = $tens->[$mil10_d-1] . " $mil_part" if $mil10_d && $mil10_d > 0;
778 if ($mil100_d && $mil100_d > 0) {
779 my $h = $mil100_d == 1 ? $hundred : $ones->[$mil100_d-1] . " $hundred";
780 $mil_part = "$h $mil_part";
781 }
782 $mil_part =~ s/\s+$//;
783 $str = "$mil_part $million" . ( $str ? " $str" : '' );
784 }
785  
786 # Billions (1,000,000,000 - 999,999,999,999)
787 if ($bil1_d || $bil10_d || $bil100_d) {
788 my $bil_part = '';
789 $bil_part .= $ones->[$bil1_d-1] . ' ' if $bil1_d && $bil1_d > 0;
790 $bil_part = $tens->[$bil10_d-1] . " $bil_part" if $bil10_d && $bil10_d > 0;
791 if ($bil100_d && $bil100_d > 0) {
792 my $h = $bil100_d == 1 ? $hundred : $ones->[$bil100_d-1] . " $hundred";
793 $bil_part = "$h $bil_part";
794 }
795 $bil_part =~ s/\s+$//;
796 $str = "$bil_part $billion" . ( $str ? " $str" : '' );
797 }
798  
799 $str =~ s/\s+/ /g;
800 $str =~ s/^\s+|\s+$//g;
801 $str_main = "$str " . ( $currency->{main} || '' );
802 $str_main =~ s/\s+/ /g;
803 $str_main =~ s/\s+$//;
804 }
805  
806 my $result = join ' ', grep { defined $_ && length($_) } ( $str_main, $str_sub );
807 $result = $numbers->{zero} unless length($result);
808  
809 if ( $is_negative && $result ne $numbers->{zero} ) {
810 $result = "$negative_prefix $result";
811 }
812  
813 return $result;
814 }
815  
816 # -------------------------------------------------------
817 # UTF-8 character-based substring (character count, not byte count).
818 # Safe against cutting UTF-8 multibyte characters in half.
819 #
820 # Signatures:
821 # $lang->substring($string, $length) # offset=0
822 # $lang->substring($string, $offset, $length) # explicit offset
823 # -------------------------------------------------------
824 sub substring {
825 my $self = shift;
826 my $string = shift;
827 return '' unless defined $string;
828  
829 my ( $offset, $length );
830 if ( @_ == 1 ) {
831 $offset = 0;
832 $length = $_[0];
833 }
834 else {
835 ( $offset, $length ) = @_;
836 }
837  
838 $length //= length($string);
839 return $string if $offset == 0 && length($string) <= $length;
840  
841 my $is_raw = !utf8::is_utf8($string);
842 my $ustr = $self->utf_decode($string);
843 my $cut = substr( $ustr, $offset, $length );
844 return $is_raw ? $self->utf_encode($cut) : $cut;
845 }
846  
847 # -------------------------------------------------------
848 # Month names list accessor for current locale (12 elements)
849 # my $months = $lang->months();
850 # -------------------------------------------------------
851 sub months {
852 my ($self) = @_;
853 return $self->{_locale}{months} || [
854 "January", "February", "March", "April", "May", "June",
855 "July", "August", "September", "October", "November", "December"
856 ];
857 }
858  
859 # -------------------------------------------------------
860 # Day names list accessor for current locale (7 elements, Sun..Sat)
861 # my $days = $lang->days();
862 # -------------------------------------------------------
863 sub days {
864 my ($self) = @_;
865 return $self->{_locale}{days} || [
866 "Sunday", "Monday", "Tuesday", "Wednesday",
867 "Thursday", "Friday", "Saturday"
868 ];
869 }
870  
871 # -------------------------------------------------------
872 # Format numeric value according to locale conventions.
873 #
874 # my $formatted = $lang->format_number(1234567.89); # "1.234.567,89" (tr)
875 # my $formatted = $lang->format_number(1234567.89, decimals=>0); # "1.234.568"
876 # my $formatted = $lang->format_number(1234567.89, decimals=>3); # "1.234.567,890"
877 # -------------------------------------------------------
878 sub format_number {
879 my ( $self, $num, %opts ) = @_;
880 return '' unless defined $num && length($num);
881  
882 $num = $self->normalize_num($num);
883 $num =~ s/^\s+|\s+$//g;
884 return '0' if $num eq '';
885  
886 my $fmt = $self->{_locale}{number_format} || {};
887 my $dec_sep = $opts{decimal_sep} // $fmt->{decimal_sep} // '.';
888 my $group_sep = $opts{group_sep} // $fmt->{group_sep} // ',';
889 my $group_size = $fmt->{group_size} || 3;
890  
891 my $is_neg = 0;
892 if ( $num =~ s/^\s*-// ) {
893 $is_neg = 1;
894 }
895  
896 # Normalize input separator if string contains commas/dots
897 $num =~ s/,/./g unless $dec_sep eq '.';
898  
899 my $decimals = $opts{decimals};
900 if ( !defined $decimals ) {
901 if ( $num =~ /\.(\d+)/ ) {
902 $decimals = length($1);
903 $decimals = 2 if $decimals < 2;
904 }
905 else {
906 $decimals = 0;
907 }
908 }
909  
910 if ( $decimals > 0 ) {
911 $num = sprintf( "%.${decimals}f", $num );
912 }
913 else {
914 $num = sprintf( "%.0f", $num );
915 }
916  
917 my ( $int_part, $dec_part ) = split /\./, $num, 2;
918 $int_part //= '0';
919  
920 # Insert thousand group separators
921 1 while $int_part =~ s/(\d+)(\d{$group_size})/$1$group_sep$2/;
922  
923 my $res = $int_part;
924 if ( defined $decimals && $decimals > 0 && defined $dec_part ) {
925 $res .= $dec_sep . $dec_part;
926 }
927  
928 return $is_neg ? "-$res" : $res;
929 }
930  
931 # -------------------------------------------------------
932 # Format currency value according to locale conventions.
933 #
934 # my $str = $lang->format_currency(1234.50); # "₺1.234,50" (tr default)
935 # my $str = $lang->format_currency(1234.50, 'EUR'); # "1.234,50 €"
936 # my $str = $lang->format_currency(1234.50, currency => 'USD');
937 # -------------------------------------------------------
938 sub format_currency {
939 my $self = shift;
940 my $amount = shift;
941 return '' unless defined $amount;
942  
943 my %opts;
944 my $code;
945  
946 if ( @_ == 1 && !ref( $_[0] ) ) {
947 $code = $_[0];
948 }
949 elsif ( @_ % 2 == 0 ) {
950 %opts = @_;
951 $code = $opts{currency} || $opts{code};
952 }
953  
954 $code ||= $self->{_locale}{default_currency} || 'TRY';
955 my $code_uc = CORE::uc($code);
956  
957 require AmberDB::Locale::Currency;
958 my $universal = AmberDB::Locale::Currency->cur_code($code_uc);
959 my $currencies = $self->{_locale}{currencies} || {};
960 my $override = $currencies->{$code_uc} || {};
961  
962 my $symbol = $opts{symbol} // $override->{symbol} // ( $universal ? $universal->{symbol} : $code_uc );
963 $symbol = $self->utf_decode($symbol) if defined $symbol;
964 my $digits = $opts{decimals} // $override->{digits} // ( $universal ? $universal->{digits} : 2 );
965 my $position = $opts{position} // $override->{position} // $self->{_locale}{currency_position} // 'prefix';
966 my $space = $opts{space} // $override->{space} // $self->{_locale}{currency_space} // 0;
967  
968 my $num_str = $self->format_number( $amount, decimals => $digits, %opts );
969  
970 my $gap = $space ? ' ' : '';
971 if ( $position eq 'suffix' ) {
972 return "${num_str}${gap}${symbol}";
973 }
974 else {
975 return "${symbol}${gap}${num_str}";
976 }
977 }
978  
979 # -------------------------------------------------------
980 # Format timestamp or date string into locale date format.
981 #
982 # my $str = $lang->format_date(time()); # "06.08.2026" (short)
983 # my $str = $lang->format_date(time(), 'full'); # "Perşembe, 6 Ağustos 2026"
984 # my $str = $lang->format_date(time(), 'YYYY-MM-DD'); # "2026-08-06"
985 # -------------------------------------------------------
986 sub format_date {
987 my ( $self, $time, $pattern_or_style ) = @_;
988 return '' unless defined $time && length($time);
989  
990 $pattern_or_style ||= 'short';
991  
992 my ( $sec, $min, $hour, $mday, $mon, $year, $wday );
993  
994 if ( $time =~ /^\d+$/ ) {
995 ( $sec, $min, $hour, $mday, $mon, $year, $wday ) = localtime($time);
996 $year += 1900;
997 $mon += 1;
998 }
999 elsif ( $time =~ /^(\d{4})[.\/-](\d{2})[.\/-](\d{2})(?:[ T](\d{2}):(\d{2}):?(\d{2})?)?/ ) {
1000 $year = $1;
1001 $mon = int($2);
1002 $mday = int($3);
1003 $hour = defined $4 ? int($4) : 0;
1004 $min = defined $5 ? int($5) : 0;
1005 $sec = defined $6 ? int($6) : 0;
1006  
1007 require Time::Local;
1008 my $ep = eval { Time::Local::timelocal( $sec, $min, $hour, $mday, $mon - 1, $year ) };
1009 if ( defined $ep ) {
1010 $wday = ( localtime($ep) )[6];
1011 }
1012 else {
1013 $wday = 0;
1014 }
1015 }
1016 else {
1017 return $time;
1018 }
1019  
1020 my $formats = $self->{_locale}{date_format} || {};
1021 my $pattern = $formats->{$pattern_or_style} || $pattern_or_style;
1022  
1023 my $months = $self->months();
1024 my $days = $self->days();
1025  
1026 my $month_name = $months->[ $mon - 1 ] || '';
1027 my $day_name = $days->[$wday] || '';
1028 my $short_mon = substr( $month_name, 0, 3 );
1029 my $short_day = substr( $day_name, 0, 3 );
1030  
1031 my %tokens = (
1032 'YYYY' => sprintf( '%04d', $year ),
1033 'YY' => sprintf( '%02d', $year % 100 ),
1034 'MMMM' => $month_name,
1035 'MMM' => $short_mon,
1036 'MM' => sprintf( '%02d', $mon ),
1037 'M' => $mon,
1038 'DD' => sprintf( '%02d', $mday ),
1039 'D' => $mday,
1040 'dddd' => $day_name,
1041 'ddd' => $short_day,
1042 'HH' => sprintf( '%02d', $hour ),
1043 'H' => $hour,
1044 'mm' => sprintf( '%02d', $min ),
1045 'm' => $min,
1046 'ss' => sprintf( '%02d', $sec ),
1047 's' => $sec,
1048 );
1049  
1050 my $re = join '|', map { quotemeta $_ } sort { length($b) <=> length($a) } keys %tokens;
1051 $pattern =~ s/($re)/$tokens{$1}/g;
1052  
1053 return $pattern;
1054 }
1055  
1056 # -------------------------------------------------------
1057 # Parse locale formatted date string back into unix timestamp / date components.
1058 #
1059 # my $epoch = $lang->parse_date("06.08.2026"); # timestamp
1060 # my $hash = $lang->parse_date("06.08.2026", hash => 1); # { year=>2026, month=>8, day=>6 }
1061 # -------------------------------------------------------
1062 sub parse_date {
1063 my ( $self, $str, %opts ) = @_;
1064 return unless defined $str && length($str);
1065  
1066 $str =~ s/^\s+|\s+$//g;
1067  
1068 my ( $day, $month, $year, $hour, $min, $sec ) = ( 0, 0, 0, 0, 0, 0 );
1069  
1070 if ( $str =~ /^(\d{1,2})[.\/-](\d{1,2})[.\/-](\d{4})(?:\s+(\d{1,2}):(\d{1,2}):?(\d{1,2})?)?/ ) {
1071 my ( $p1, $p2, $p3 ) = ( int($1), int($2), int($3) );
1072 $hour = int( $4 // 0 );
1073 $min = int( $5 // 0 );
1074 $sec = int( $6 // 0 );
1075  
1076 my $fmt = $self->{_locale}{date_format}{short} || 'DD.MM.YYYY';
1077 if ( $fmt =~ /^MM/i ) {
1078 $month = $p1;
1079 $day = $p2;
1080 $year = $p3;
1081 }
1082 else {
1083 $day = $p1;
1084 $month = $p2;
1085 $year = $p3;
1086 }
1087 }
1088 elsif ( $str =~ /^(\d{4})[.\/-](\d{1,2})[.\/-](\d{1,2})(?:\s+(\d{1,2}):(\d{1,2}):?(\d{1,2})?)?/ ) {
1089 $year = int($1);
1090 $month = int($2);
1091 $day = int($3);
1092 $hour = int( $4 // 0 );
1093 $min = int( $5 // 0 );
1094 $sec = int( $6 // 0 );
1095 }
1096  
1097 return unless $year && $month && $day;
1098  
1099 if ( $opts{hash} ) {
1100 return {
1101 year => $year,
1102 month => $month,
1103 day => $day,
1104 hour => $hour,
1105 minute => $min,
1106 second => $sec,
1107 };
1108 }
1109  
1110 require Time::Local;
1111 return eval { Time::Local::timelocal( $sec, $min, $hour, $day, $month - 1, $year ) };
1112 }
1113  
1114 # Private helper: securely evaluate sanitized CLDR plural expressions
1115 sub _eval_plural_rule {
1116 my ( $self, $cond, $count ) = @_;
1117 return 0 unless defined $cond && length $cond;
1118  
1119 my $n = abs( $count // 0 );
1120  
1121 # Whitelist strictly only digits, 'n', whitespace, arithmetic and logical operators
1122 return 0 unless $cond =~ /^[n0-9+\-*\/%&|!=<>()\s]+$/;
1123  
1124 # Replace 'n' variable token with actual numeric value
1125 ( my $expr = $cond ) =~ s/\bn\b/$n/g;
1126  
1127 # Safely evaluate numeric expression isolated from global DIE handlers
1128 my $res = eval {
1129 local $SIG{__DIE__} = sub {};
1130 eval $expr; ## no critic
1131 };
1132 return $res ? 1 : 0;
1133 }
1134  
1135 # -------------------------------------------------------
1136 # Evaluate CLDR plural rule and select template.
1137 #
1138 # my $text = $lang->plural(1, { one => "{count} ürün", other => "{count} ürün" });
1139 # my $text = $lang->plural(5, { one => "{count} item", other => "{count} items" });
1140 # -------------------------------------------------------
1141 sub plural {
1142 my ( $self, $count, $forms ) = @_;
1143 return '' unless defined $forms;
1144  
1145 $count //= 0;
1146 my $form_key = 'other';
1147  
1148 my $rule = $self->{_locale}{plural_rule} || 'one{n==1}other';
1149  
1150 for my $key (qw(zero one two few many)) {
1151 if ( $rule =~ /\b$key\{([^{}]+)\}/ ) {
1152 my $cond = $1;
1153 if ( $self->_eval_plural_rule( $cond, $count ) ) {
1154 $form_key = $key;
1155 last;
1156 }
1157 }
1158 }
1159  
1160 my $template;
1161 if ( ref($forms) eq 'HASH' ) {
1162 $template = $forms->{$form_key} // $forms->{other} // $forms->{one} // '';
1163 }
1164 else {
1165 $template = "$forms";
1166 }
1167  
1168 my $fmt_count = $self->format_number($count, decimals => 0);
1169 $template =~ s/\{count\}|\{n\}/$fmt_count/g;
1170  
1171 return $template;
1172 }
1173  
1174 # -------------------------------------------------------
1175 # Language tag accessor
1176 # my $tag = $lang->language; # "tr", "en", "de" ...
1177 # -------------------------------------------------------
1178 sub language { return $_[0]->{_lang} }
1179  
1180 1;
1181  
1182 __END__