blib/lib/Lingua/Text.pm

filter: Statementstmt 100% 159 / 159 Branchbran 94.2% 66 / 70 Conditioncond 97.6% 41 / 42 MC/DCmcdc 95.8% 23 / 24 Subroutinesub 100% 28 / 28 Podpod 100% 4 / 4 totaltotal 98.1% 321 / 327 CC 57 SCAR 22.7
CC
57
Cov
98%
_get_language
21.0
new
14.0
AUTOLOAD
6.0
CRAP 9.7
↑ Summary
1 package Lingua::Text;
2  
3 16 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 16 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 16 ▶use autodie qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 16 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 16 ▶use HTML::Entities;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 16 ▶use Object::Configure;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 16 ▶use Params::Get;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 16 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 16 ▶use Scalar::Util qw(blessed);
Subroutine BEGIN: called CC=1 SCAR=0.0
13 16 ▶use I18N::LangTags::Detect;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 16 ▶use Sub::Protected;
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 =head1 NAME
17  
18 Lingua::Text - Store the same text in many languages; retrieve it in the user's language automatically
19  
20 =head1 VERSION
21  
22 Version 0.10
23  
24 =cut
25  
26 16 our $VERSION = '0.10';
27 16 our $AUTOLOAD;
28  
29 # ---------------------------------------------------------------------------
30 # Constants
31 # ---------------------------------------------------------------------------
32  
33 # ISO 639-1 language code with optional ISO 3166-1 country suffix (e.g. 'en', 'en_US').
34 # The pattern is case-sensitive: lower-case lang, upper-case country.
35 # /x lets us annotate each component; spaces and # comments inside /x are ignored.
36 16 Readonly::Scalar my $LANG_RE => qr/
37 ^
38 [a-z]{2} # ISO 639-1 two-letter language code (e.g. 'en', 'fr')
39 (?:_[A-Z]{2})? # optional ISO 3166-1 country suffix (e.g. '_US', '_GB')
40 $
41 /x;
42  
43 # Error message catalog. All templates accept the package name as first
44 # sprintf argument so callers never hard-code the package string.
45 # Capitalised "Usage:" marks programmer errors (croak); lower-case marks
46 # runtime warnings (carp) -- the carp.t suite relies on this distinction.
47 16 Readonly::Hash my %MESSAGES => (
48 new_oo_style => '%s: use ->new() not ::new() to instantiate',
49 set_no_args => '%s: Usage: set(text => $text, lang => $language)',
50 set_usage => '%s: usage: set(text => $text, lang => $language)',
51 str_usage => '%s: usage: as_string(lang => $language)',
52 );
53  
54 16 ▶use overload (
Subroutine BEGIN: called CC=1 SCAR=0.0
55 '""' => \&as_string,
56 1163 ▶ bool => sub { 1 },
Subroutine __ANON__: called CC=1 SCAR=0.0
57 16 fallback => 1, # let boolean tests bypass as_string
58 16 );
59  
60 # ---------------------------------------------------------------------------
61 # Public API
62 # ---------------------------------------------------------------------------
63  
64 =head1 SYNOPSIS
65  
66 =head2 Basic use: store translations and print in the user's language
67  
68 use Lingua::Text;
69  
70 my $greeting = Lingua::Text->new(
71 en => 'Hello',
72 fr => 'Bonjour',
73 de => 'Hallo',
74 );
75  
76 # The system locale (LANG, LC_MESSAGES, etc.) picks the language.
77 # No code change is needed when the user's OS language changes.
78 print $greeting, "\n";
79  
80 =head2 Add translations after construction
81  
82 my $label = Lingua::Text->new();
83 $label->en('Submit');
84 $label->fr('Envoyer');
85 $label->de('Abschicken');
86  
87 # Ask for a specific language explicitly
88 print $label->as_string('fr'), "\n"; # Envoyer
89  
90 =head2 Build from a database hash
91  
92 # Suppose the database returns: { en => 'Apple', fr => 'Pomme', de => 'Apfel' }
93 my $row = $db->selectrow_hashref('SELECT en, fr, de FROM fruit WHERE id = ?', {}, $id);
94 my $name = Lingua::Text->new($row);
95 print $name; # prints in the user's system language
96  
97 =head2 Add one translation to an existing object (clone)
98  
99 my $base = Lingua::Text->new(en => 'colour', fr => 'couleur');
100 my $us = $base->new(en => 'color'); # American English override
101  
102 # $us has en => 'color', fr => 'couleur'
103 # $base is unchanged: en => 'colour', fr => 'couleur'
104  
105 =head2 Store text at runtime using a language variable
106  
107 my $message = Lingua::Text->new();
108 my $user_lang = 'de'; # could come from a web request header
109  
110 $message->set(text => 'Willkommen', lang => $user_lang);
111 print $message->as_string($user_lang), "\n"; # Willkommen
112  
113 =head2 Prepare multilingual text for HTML output
114  
115 my $title = Lingua::Text->new(
116 en => 'read more',
117 fr => "lire la suite",
118 )->encode(); # converts accented characters to HTML entities
119  
120 print "<title>$title</title>"; # safe for browsers in any locale
121  
122 =head1 DESCRIPTION
123  
124 Lingua::Text is a simple container that stores the same piece of text in
125 multiple languages inside a single Perl object. When you ask the object to
126 print itself (or convert to a string), it automatically reads the user's
127 operating-system language setting and returns the correct translation.
128  
129 =head2 How language detection works
130  
131 The module reads the following environment variables, in this order, and uses
132 the first one it finds that contains a two-letter language code:
133  
134 =over 4
135  
136 =item 1. C<LANGUAGE> (space- or colon-separated preference list, e.g. C<fr:en>)
137  
138 =item 2. C<LC_ALL>
139  
140 =item 3. C<LC_MESSAGES>
141  
142 =item 4. C<LANG> (e.g. C<en_US.UTF-8> or C<de_DE>)
143  
144 =back
145  
146 In CGI or web environments, C<I18N::LangTags::Detect> also inspects the
147 C<HTTP_ACCEPT_LANGUAGE> request header (when available in the environment)
148 before falling back to the variables above. The memoisation cache tracks
149 this variable alongside the four above, so the cache is invalidated
150 correctly when the header changes between requests.
151  
152 Only the first two letters are used (e.g. C<en_GB.UTF-8> becomes C<en>), so
153 you only need to store one translation per language, not per locale variant.
154  
155 If none of these variables is set, or if C<LANG> is set to the POSIX C<C>
156 or C<C.UTF-8> locale, the module returns C<undef> (or C<'en'> for the C
157 locale).
158  
159 =head2 How string interpolation works
160  
161 The object overloads Perl's C<""> (stringify) operator. This means you can
162 use a Lingua::Text object directly in strings:
163  
164 print "Hello: $greeting\n";
165 my $html = "<h1>" . $title . "</h1>";
166  
167 You do B<not> need to call C<as_string()> yourself in most cases.
168  
169 =head2 Language code format
170  
171 Language codes follow ISO 639-1: two lower-case letters, e.g. C<en>, C<fr>,
172 C<de>, C<es>, C<zh>. An optional ISO 3166-1 country suffix may follow an
173 underscore: C<en_US>, C<zh_CN>. The module stores and retrieves by the
174 two-letter code only; the country part of an environment variable is ignored
175 during lookup.
176  
177 =head1 METHODS
178  
179 =head2 new
180  
181 Create a new Lingua::Text object. The object starts empty, or pre-loaded
182 with one or more translations you provide.
183  
184 Calling C<new()> on an B<existing> object creates an independent copy (a
185 clone) with any extra translations you supply merged in. The original object
186 is never modified.
187  
188 =head3 ARGUMENTS
189  
190 You may pass arguments in any of the following forms:
191  
192 =over 4
193  
194 =item No arguments -- creates an empty object
195  
196 my $t = Lingua::Text->new();
197  
198 =item Key/value pairs -- one pair per language
199  
200 my $t = Lingua::Text->new(en => 'boat', fr => 'bateau');
201  
202 =item A hash reference
203  
204 my $t = Lingua::Text->new({ en => 'boat', fr => 'bateau' });
205  
206 =item A single plain string -- stored under the current system locale language
207  
208 # Only works if a locale environment variable is set.
209 # If no locale is set, the text is silently discarded. See COMMON PITFALLS.
210 my $t = Lingua::Text->new('hello');
211  
212 =item An existing Lingua::Text object -- creates a clone
213  
214 my $clone = $original->new(); # exact copy
215 my $clone = $original->new(de => 'zusatz'); # copy + one more language
216  
217 =back
218  
219 =head3 RETURN VALUE
220  
221 Returns a blessed Lingua::Text reference on success.
222  
223 Returns C<undef> and emits a C<carp> warning when called as a plain function
224 with arguments (e.g. C<Lingua::Text::new(en => 'hi')> without the arrow).
225  
226 =head3 EXAMPLE
227  
228 use Lingua::Text;
229  
230 # Empty object
231 my $t = Lingua::Text->new();
232 $t->en('Good morning');
233 $t->de('Guten Morgen');
234  
235 # Pre-populated from a hash reference
236 my %translations = (en => 'cat', fr => 'chat', de => 'Katze');
237 my $animal = Lingua::Text->new(\%translations);
238  
239 # Clone and override the English translation
240 my $us = $animal->new(en => 'kitty');
241  
242 =head3 API SPECIFICATION
243  
244 =head4 Input
245  
246 # Params::Validate::Strict-compatible schema
247 # (all parameters are optional; the whole argument list may be empty)
248  
249 en => { type => 'string', optional => 1 } # and any other ISO 639-1 code
250 fr => { type => 'string', optional => 1 }
251 ... # one key per language
252  
253 # OR a single HASHREF containing the same keys
254  
255 # OR a single SCALAR (stored under the current locale language)
256  
257 =head4 Language key domain
258  
259 Keys passed to C<new()> are stored verbatim in the internal C<{texts}> hash
260 without validation at construction time. Access restrictions come from the
261 consumers:
262  
263 =over 4
264  
265 =item *
266  
267 B<AUTOLOAD accessor> -- only installs an accessor for keys matching
268 C</^[a-z]{2}$/>: exactly two lower-case ASCII letters. C<en_US> (with
269 country suffix), C<eng> (three letters), C<EN> (upper-case) and all other
270 keys are silently ignored by the accessor mechanism.
271  
272 =item *
273  
274 B<encode()> -- only processes keys accepted by C<_is_valid_language()>:
275 C</^[a-z]{2}(?:_[A-Z]{2})?$/>. Keys with C<en_US>-style country suffixes
276 are encoded; non-language keys injected by L<Object::Configure> (e.g.
277 C<logger>, C<config_path>) are skipped.
278  
279 =back
280  
281 Equivalence partitions for language keys
282  
283 PARTITION EXAMPLE AUTOLOAD encode()
284 --------------------------------------------------------
285 2-lower (valid) 'en' YES YES
286 2-lower + _XX 'en_US' NO YES
287 1 char 'e' NO NO
288 3+ chars 'eng' NO NO
289 uppercase 'EN' NO NO
290 non-alpha '12' NO NO
291  
292 =head4 Output
293  
294 # Return::Set schema
295 on_success => Lingua::Text, # blessed reference
296 on_misuse => undef # with carp warning
297  
298 =head3 MESSAGES
299  
300 =over 4
301  
302 =item C<"use -E<gt>new() not ::new() to instantiate"> [carp]
303  
304 You called C<Lingua::Text::new(...)> (double-colon, function style) with
305 arguments. Use C<Lingua::Text-E<gt>new(...)> (arrow, method style) instead.
306  
307 =back
308  
309 =cut
310  
311 559 ▶sub new {
Subroutine new: called CC=14 SCAR=26.4
Pod documented
312 559 my $class = shift;
313  
314 # Detect function-style misuse: Lingua::Text::new(args...)
315 # A legitimate invocant is either a blessed object (clone) or a class name
316 # that inherits from this package. Anything else (e.g. the first key of a
317 # hash accidentally consumed as the invocant) triggers a warning.
318 # SECURITY: call UNIVERSAL::isa() as a function, not as a method on $class.
319 # Method dispatch on an attacker-controlled string would invoke any isa()
320 # defined on that package; the function form bypasses method resolution.
321 559 ▶ my $is_class = !ref($class) && defined($class) && eval { UNIVERSAL::isa($class, __PACKAGE__) };
Condition100%6/6
!ref($class) && defined $class && eval { do { UNIVERSAL::isa($class, __PACKAGE__) } }
!ll&&!rl&&r
369514
not ref $class and defined $class
!ll&&!rl&&r
297523
MC/DC100%3/3
!ref($class) && defined $class && eval { do { UNIVERSAL::isa($class, __PACKAGE__) } }
not ref $class defined $class eval { do { UNIVERSAL::isa($class, __PACKAGE__) } }
Truth table100%4/4
not(A) and B && C
A= not ref $classB= defined $classC= eval { do { UNIVERSAL::isa($class, __PACKAGE__) } }
ABCresult
0XX0
10X0
1100
1111
322  
323 # A valid object invocant must be a Lingua::Text instance (or subclass),
324 # not just any blessed reference. A foreign blessed object (e.g. from
325 # a completely unrelated package) would pass `blessed()` but crash the clone
326 # path at `%{$class->{'texts'}}` because it has no 'texts' slot.
327 # UNIVERSAL::isa() as a function is used (not method dispatch) for the same
328 # security reason as above.
329 559 ▶ my $is_object = blessed($class) && UNIVERSAL::isa($class, __PACKAGE__);
Condition100%3/3
builtin::blessed($class) && UNIVERSAL::isa($class, __PACKAGE__)
!ll&&!rl&&r
530227
MC/DC100%2/2
builtin::blessed($class) && UNIVERSAL::isa($class, __PACKAGE__)
builtin::blessed($class) UNIVERSAL::isa($class, __PACKAGE__)
Truth table100%3/3
A && B
A= builtin::blessed($class)B= UNIVERSAL::isa($class, __PACKAGE__)
ABresult
0X0
100
111
330  
331 # Syllogism:
332 # P1: A valid invocant is a Lingua::Text blessed object (clone path) or
333 # a class name that inherits from Lingua::Text (isa check).
334 # P2: !defined($class) implies both $is_class and $is_object are false
335 # (each requires defined($class) in their own derivation).
336 # Conclusion: De Morgan reduction -- the original
337 # "!defined || (!class && !object)"
338 # is logically equivalent to "!($is_object || $is_class)".
339 559 ▶ unless($is_object || $is_class) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($is_object or $is_class) 18 541 559
Condition100%3/3
$is_object or $is_class
l!l&&r!l&&!r
2751418
MC/DC100%2/2
$is_object or $is_class
$is_object $is_class
Truth table100%3/3
A or B
A= $is_objectB= $is_class
ABresult
1X1
011
000
340 # undef invocant = bare Lingua::Text::new() with no args -- allowed
341 18 ▶ if(defined($class)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $class) 11 7 18
342 11 Carp::carp(_err('new_oo_style'));
343 11 return;
344 }
345 7 $class = __PACKAGE__;
346 }
347  
348 # Build the initial parameter hash from whatever form the caller used.
349 # A single non-ref scalar is the positional form: store under the locale lang
350 # if one is detected, or silently discard it when no locale is set (the
351 # documented pitfall). We must NOT let it reach get_params(), which croaks
352 # on an odd-length list (get_params(undef, $scalar) = 1 arg = odd).
353 548 my $params;
354 548 ▶ if((scalar(@_) == 1) && (!ref($_[0]))) {
Branch: 2 branches
BranchTrueFalseTotal
if (scalar @_ == 1 and not ref $_[0]) { } 17 531 548
elsif (@_) { } 352 179 531
Condition100%3/3
scalar @_ == 1 and not ref $_[0]
!ll&&!rl&&r
5112017
MC/DC100%2/2
scalar @_ == 1 and not ref $_[0]
scalar @_ == 1 not ref $_[0]
Truth table100%3/3
A and not(B)
A= scalar @_ == 1B= not ref $_[0]
ABresult
0X0
100
111
355 17 my $lang = _get_language();
356 17 ▶ $params = { $lang => $_[0] } if $lang;
Branch: 1 branch
BranchTrueFalseTotal
if $lang 11 6 17
357 } elsif(@_) {
358 352 $params = Params::Get::get_params(undef, \@_);
359 }
360  
361 # Clone path: caller is an existing object
362 548 ▶ if($is_object) {
Branch: 1 branch
BranchTrueFalseTotal
if ($is_object) 27 521 548
363 27 ▶ if($params) {
Branch: 1 branch
BranchTrueFalseTotal
if ($params) 18 9 27
364 18 return bless { texts => {%{$class->{'texts'}}, %{$params}} }, ref($class);
365 }
366 9 return bless { %{$class} }, ref($class);
367 }
368  
369 # Allow Object::Configure to inject defaults (e.g. from a config file)
370 521 $params = Object::Configure::configure($class, $params);
371 521 ▶ return bless( $params ? { texts => $params } : {}, $class );
Branch: 1 branch
BranchTrueFalseTotal
$params ? : 489 32 521
372 }
373  
374 =head2 set
375  
376 Store or replace a single translation. Use this when the language code is
377 held in a variable at runtime; if the language is fixed at coding time, the
378 shorthand accessor (e.g. C<$t-E<gt>en('Hello')>) is simpler.
379  
380 =head3 ARGUMENTS
381  
382 text -- the translation string (required)
383 lang -- two-letter language code (optional; defaults to the system locale)
384  
385 The arguments may be passed as a hash, a hash reference, or as a plain
386 positional string (only C<text>; C<lang> then comes from the system locale).
387  
388 =head3 RETURN VALUE
389  
390 Returns the object itself (C<$self>) on success, so calls may be chained.
391 Because the object stringifies to its current-locale translation, the return
392 value often I<looks> like the text you just stored -- but it is the object,
393 not the string. See L</COMMON PITFALLS>.
394  
395 Returns C<undef> and emits a C<carp> warning when required arguments are
396 missing or when no language can be determined.
397  
398 =head3 EXAMPLE
399  
400 my $t = Lingua::Text->new();
401  
402 # Hash-reference form
403 $t->set({ text => 'House', lang => 'en' });
404  
405 # Flat hash form
406 $t->set(text => 'Maison', lang => 'fr');
407  
408 # Positional: lang comes from the system locale
409 $t->set('Haus'); # stored under whatever language $ENV{LANG} says
410  
411 # Method chaining (set() returns $self)
412 my $t = Lingua::Text->new()->set(text => 'Hello', lang => 'en')
413 ->set(text => 'Hola', lang => 'es');
414  
415 # Store the language code from a variable
416 my $user_lang = 'de';
417 $t->set(text => 'Willkommen', lang => $user_lang);
418  
419 =head3 API SPECIFICATION
420  
421 =head4 Input
422  
423 # Params::Validate::Strict-compatible schema
424 text => {
425 type => 'string',
426 },
427 lang => {
428 type => 'string',
429 optional => 1,
430 default => _get_language(), # falls back to system locale
431 regex => qr/^[a-z]{2}(?:_[A-Z]{2})?$/,
432 }
433  
434 =head4 lang parameter domain (BVA)
435  
436 The C<lang> value is validated by the regex C</^[a-z]{2}(?:_[A-Z]{2})?$/>.
437  
438 # BOUNDARY VALUE ANALYSIS
439 #
440 # PARTITION EXAMPLE VALID? REASON
441 # -------------------------------------------------------
442 # 1 char (below minimum) 'e' NO too short
443 # 2 lowercase (MINIMUM) 'en' YES minimum valid length
444 # 3 lowercase 'eng' NO exceeds simple maximum
445 # 5 chars with suffix (MAX) 'en_US' YES 2-lower + _ + 2-UPPER
446 # 6 chars, country 3-long 'en_USA' NO country must be exactly 2
447 # 4 chars, country 1-long 'en_U' NO country must be exactly 2
448 # trailing underscore only 'en_' NO country code absent
449 # 2 uppercase 'EN' NO must be lower-case
450 # mixed case 'En' NO must be lower-case
451 # 2 digits '12' NO digits not in [a-z]
452 # empty string '' NO zero length
453  
454 =head4 text parameter domain
455  
456 Any defined scalar is a valid text value. Length has no documented limit.
457  
458 # BOUNDARY VALUE ANALYSIS
459 #
460 # PARTITION EXAMPLE VALID? REASON
461 # ---------------------------------------------------------------
462 # empty string '' YES length 0 (minimum)
463 # falsy '0' '0' YES defined, even if falsy
464 # regular ASCII 'hello' YES representative valid
465 # Unicode "\x{E9}tude" YES stored verbatim
466 # 1 MB string 'x' x 1_000_000 YES no documented size limit
467 # undef undef NO undefined = missing text
468  
469 =head4 Output
470  
471 # Return::Set schema
472 on_success => $self, # the same Lingua::Text object
473 on_no_args => undef # with croak (programmer error)
474 on_missing_lang => undef # with carp
475 on_invalid_lang => undef # with carp (lang fails ISO 639-1 check)
476 on_missing_text => undef # with carp
477  
478 =head3 MESSAGES
479  
480 =over 4
481  
482 =item C<"Usage: set(text =E<gt> $text, lang =E<gt> $language)"> [croak]
483  
484 C<set()> was called with no arguments at all. Provide at least C<text>.
485  
486 =item C<"usage: set(text =E<gt> $text, lang =E<gt> $language)"> [carp]
487  
488 One of three conditions: C<text> is missing or undef; C<lang> is missing and
489 no locale environment variable is set; or C<lang> was supplied but fails the
490 ISO 639-1 validation check (e.g. a three-letter code like C<'abc'>).
491 Pass C<lang> as a two-letter code (e.g. C<'en'>) to resolve all three.
492  
493 =back
494  
495 =cut
496  
497 192 ▶sub set {
Subroutine set: called CC=6 SCAR=17.9
Pod documented
498 192 my $self = shift;
499  
500 192 ▶ Carp::croak(_err('set_no_args')) unless @_;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ 7 185 192
501  
502 185 my $params = Params::Get::get_params('text', @_);
503  
504 # SECURITY: use // (defined-or), not || (truthiness).
505 # || would silently substitute the system locale when the caller explicitly
506 # passes lang => '' or lang => '0', masking an invalid-argument error.
507 185 ▶ my $lang = $params->{'lang'} // _get_language();
Condition100%3/3
$params->{"lang"} // _get_language()
l!l&&r!l&&!r
17096
MC/DC100%2/2
$params->{"lang"} // _get_language()
$params->{"lang"} _get_language()
Truth table100%3/3
A // B
A= $params->{"lang"}B= _get_language()
ABresult
1X1
011
000
508 185 ▶ return _carp_set_usage() unless defined($lang);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $lang 6 179 185
509  
510 # Syllogism:
511 # P1 (object invariant): every key in $self->{texts} must satisfy $LANG_RE.
512 # P2: $lang was resolved from caller input -- it may be any string.
513 # Conclusion: validate at the API boundary before writing; reject here to
514 # maintain the invariant rather than letting bad keys propagate.
515 179 ▶ return _carp_set_usage() unless _is_valid_language($lang);
Branch: 1 branch
BranchTrueFalseTotal
unless _is_valid_language($lang) 61 118 179
516  
517 118 my $text = $params->{'text'};
518 118 ▶ return _carp_set_usage() unless defined($text);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $text 9 109 118
519  
520 109 $self->{'texts'}->{$lang} = $text;
521 109 return $self;
522 }
523  
524 =head2 as_string
525  
526 Return the stored translation for a given language, or for the system locale
527 when no language is specified.
528  
529 This method is also invoked automatically whenever Perl needs to convert the
530 object to a string -- for example inside C<print>, in string concatenation, or
531 in a comparison like C<$t eq 'hello'>. You rarely need to call it directly.
532  
533 =head3 ARGUMENTS
534  
535 lang -- two-letter language code (optional; defaults to the system locale)
536  
537 Accepted forms:
538  
539 $t->as_string() # uses system locale
540 $t->as_string('fr') # positional
541 $t->as_string(lang => 'fr') # named
542 $t->as_string({ lang => 'fr' }) # hash reference
543 "$t" # stringification overload (uses system locale)
544  
545 =head3 RETURN VALUE
546  
547 =over 4
548  
549 =item Returns the translation string when the language is known and stored.
550  
551 =item Returns C<undef> -- B<without> a warning -- when the language is known
552 but no translation exists for it. This is the normal "not translated yet"
553 case.
554  
555 =item Returns C<undef> -- B<with> a C<carp> warning -- when no language can
556 be determined (no argument supplied I<and> no locale environment variable set).
557  
558 =back
559  
560 =head3 EXAMPLE
561  
562 use Lingua::Text;
563  
564 my $t = Lingua::Text->new(en => 'boat', fr => 'bateau');
565  
566 # Explicit language
567 print $t->as_string('en'), "\n"; # boat
568 print $t->as_string(lang => 'fr'), "\n"; # bateau
569  
570 # System locale (assume LANG=de_DE.UTF-8)
571 print $t->as_string(), "\n"; # undef -- no German stored
572  
573 # String interpolation (same as calling as_string() with no args)
574 $ENV{LANG} = 'en_US.UTF-8';
575 print "I see a $t.\n"; # I see a boat.
576  
577 # Checking for a missing translation
578 if(!defined($t->as_string('zh'))) {
579 print "No Chinese translation available.\n";
580 }
581  
582 =head3 API SPECIFICATION
583  
584 =head4 Input
585  
586 # Params::Validate::Strict-compatible schema
587 lang => {
588 type => 'string',
589 optional => 1,
590 default => _get_language(),
591 # NOTE: unlike set(), as_string() performs NO format validation on
592 # the lang argument. Any defined scalar is used directly as a hash
593 # key into the internal {texts} store. An unrecognised key simply
594 # returns undef without a warning (the 'on_not_found' state below).
595 }
596  
597 =head4 lang argument domain
598  
599 # EQUIVALENCE PARTITIONS
600 #
601 # INPUT RESULT
602 # ---------------------------------------------------------------
603 # Stored key ('en' exists) returns the text (no warning)
604 # Valid format, not stored returns undef (no warning)
605 # Invalid format, not stored returns undef (no warning)
606 # Empty string '' returns undef (no warning)
607 # undef falls back to _get_language()
608 # no argument falls back to _get_language()
609 #
610 # Argument forms accepted:
611 # as_string('en') positional
612 # as_string(lang => 'en') named hash
613 # as_string({ lang => 'en' }) hash reference
614  
615 =head4 Output
616  
617 # Return::Set schema
618 on_found => SCALAR, # the translation string
619 on_not_found => undef, # language is known; no translation stored
620 on_no_language => undef # with carp warning
621  
622 =head3 MESSAGES
623  
624 =over 4
625  
626 =item C<"usage: as_string(lang =E<gt> $language)"> [carp]
627  
628 No C<lang> was supplied and no locale environment variable (C<LANG>,
629 C<LC_MESSAGES>, C<LC_ALL>, C<LANGUAGE>) is set. Either pass the language
630 explicitly or set the locale before calling.
631  
632 =back
633  
634 =cut
635  
636 233 ▶sub as_string {
Subroutine as_string: called CC=6 SCAR=17.9
Pod documented
637 233 my $self = shift;
638  
639 # Guard against the overload calling convention: Perl passes ($self, $other, $swap)
640 # when the "" handler is invoked during a comparison. We only want the first arg.
641 # Fast path: single positional scalar (e.g. as_string('en')) skips Params::Get
642 # to avoid parameter-parsing overhead on what is often the hottest call site.
643 233 my $lang;
644 233 ▶ if(@_ && defined($_[0])) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_ and defined $_[0]) 93 140 233
Condition100%3/3
@_ and defined $_[0]
!ll&&!rl&&r
796193
MC/DC100%2/2
@_ and defined $_[0]
@_ defined $_[0]
Truth table100%3/3
A and B
A= @_B= defined $_[0]
ABresult
0X0
100
111
645 93 ▶ if(my $params = Params::Get::get_params('lang', \@_)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $params = Params::Get::get_params("lang", \@_)) 93 0 93
646 93 $lang = $params->{'lang'};
647 }
648 }
649 233 ▶ $lang //= _get_language();
Condition100%3/3
$lang //= _get_language()
l!l&&r!l&&!r
9311129
MC/DC100%2/2
$lang //= _get_language()
$lang _get_language()
Truth table100%3/3
A //= B
A= $langB= _get_language()
ABresult
1X1
011
000
650  
651 233 ▶ if(defined($lang)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $lang) 204 29 233
652 204 return $self->{'texts'}->{$lang};
653 }
654 29 Carp::carp(_err('str_usage'));
655 29 return;
656 }
657  
658 =head2 encode
659  
660 Convert every stored translation from raw Unicode text to HTML entities.
661 Call this once on an object before embedding its text in HTML pages, to make
662 accented characters and other special characters safe for all browsers.
663  
664 For example, the French word C<"\x{E9}tude"> (e-acute followed by "tude")
665 becomes C<"&eacute;tude"> after encoding.
666  
667 B<Important:> This method modifies the object I<in place> and B<cannot be
668 undone>. There is no C<decode()> counterpart. See L</COMMON PITFALLS>.
669  
670 =head3 ARGUMENTS
671  
672 None.
673  
674 =head3 RETURN VALUE
675  
676 Returns the object itself (C<$self>), so C<encode()> can be chained directly
677 onto C<new()>.
678  
679 =head3 EXAMPLE
680  
681 use Lingua::Text;
682  
683 # Build an object and encode it in one step
684 my $t = Lingua::Text->new(
685 en => 'study',
686 fr => "\x{E9}tude", # e with acute accent (Unicode codepoint U+00E9)
687 )->encode();
688  
689 print $t->fr(); # &eacute;tude
690 print $t->en(); # study (plain ASCII is unchanged)
691  
692 # Use encoded text safely inside HTML
693 my $html = "<p>" . $t . "</p>";
694  
695 =head3 API SPECIFICATION
696  
697 =head4 Input
698  
699 None.
700  
701 =head4 Output
702  
703 # Return::Set schema
704 on_success => $self # the same Lingua::Text object, with texts encoded
705  
706 =cut
707  
708 108 ▶sub encode {
Subroutine encode: called CC=6 SCAR=17.9
Pod documented
709 108 my $self = shift;
710  
711 # Iterate over keys to avoid stale iterator state from each().
712 108 for my $lang (keys %{$self->{'texts'}}) {
713 # SECURITY V2: Object::Configure may inject non-language keys (e.g. 'logger')
714 # that carry blessed references. utf8::decode() modifies its argument IN
715 # PLACE, which would corrupt the referenced object's internal string buffer.
716 # encode_entities() would then stringify it, potentially leaking its repr.
717 # Only process keys that satisfy the object invariant (valid ISO 639-1 code).
718 239 ▶ next unless _is_valid_language($lang);
Branch: 1 branch
BranchTrueFalseTotal
unless _is_valid_language($lang) 84 155 239
719  
720 155 my $v = $self->{'texts'}->{$lang};
721  
722 # SECURITY V3: a caller may store undef via $t->en(undef). utf8::decode(undef)
723 # emits "Use of uninitialized value" under 'use warnings' and is a no-op,
724 # but encode_entities(undef) returns '' which silently drops the entry.
725 # Skip explicitly so the stored undef is preserved unchanged.
726 155 ▶ next unless defined($v) && !ref($v);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $v and not ref $v 13 142 155
Condition100%3/3
defined $v and not ref $v
!ll&&!rl&&r
67142
MC/DC100%2/2
defined $v and not ref $v
defined $v not ref $v
Truth table100%3/3
A and not(B)
A= defined $vB= not ref $v
ABresult
0X0
100
111
727  
728 142 ▶ utf8::decode($v) unless utf8::is_utf8($v);
Branch: 1 branch
BranchTrueFalseTotal
unless utf8::is_utf8($v) 139 3 142
729 142 $self->{'texts'}->{$lang} = HTML::Entities::encode_entities($v);
730 }
731 108 return $self;
732 }
733  
734 =head2 Language accessor methods
735  
736 Any two-letter method name that is a valid ISO 639-1 language code acts as a
737 combined getter and setter for that language's translation. These methods do
738 not need to be declared; Perl's C<AUTOLOAD> mechanism intercepts them.
739  
740 $t->en('Hello'); # store an English translation
741 my $text = $t->fr(); # retrieve the French translation (undef if not stored)
742 $t->zh(''); # store an empty string (distinct from undef/not-stored)
743 $t->en(0); # store the string "0" (falsy values work correctly)
744  
745 =head3 ARGUMENTS
746  
747 =over 4
748  
749 =item B<Setter form> -- pass one scalar argument
750  
751 The value is stored under the method's language code and also returned.
752  
753 =item B<Getter form> -- call with no arguments
754  
755 Returns the stored string for that language, or C<undef> if nothing has been
756 stored.
757  
758 =back
759  
760 =head3 RETURN VALUE
761  
762 =over 4
763  
764 =item Returns the stored translation string (getter) or the value just stored
765 (setter).
766  
767 =item Returns C<undef> -- silently -- when the language has no stored
768 translation.
769  
770 =item Returns C<undef> silently for any method name that is not a recognised
771 two-letter ISO 639-1 code. This means typos (e.g. C<$t-E<gt>enn()>) fail
772 invisibly. See L</COMMON PITFALLS>.
773  
774 =back
775  
776 =head3 EXAMPLE
777  
778 my $t = Lingua::Text->new();
779  
780 $t->en('Good morning');
781 $t->fr('Bonjour');
782 $t->de('Guten Morgen');
783  
784 print $t->en(), "\n"; # Good morning
785 print $t->ja(), "\n"; # (nothing -- no Japanese stored)
786  
787 # Chaining setters is not supported; use set() for that.
788 # Setters return the stored value, not $self.
789  
790 =head3 API SPECIFICATION
791  
792 =head4 Method name domain (BVA)
793  
794 The accessor is only created for method names that match C</^[a-z]{2}$/>:
795 exactly two lower-case ASCII letters. All other names return C<undef>
796 silently and never install an accessor.
797  
798 # BOUNDARY VALUE ANALYSIS
799 #
800 # NAME CHARS MATCHES /^[a-z]{2}$/ RESULT
801 # ---------------------------------------------------------------
802 # 'e' 1 NO (below minimum) undef (silent)
803 # 'en' 2 YES (minimum valid) accessor works
804 # 'eng' 3 NO (above maximum) undef (silent)
805 # 'EN' 2 NO (uppercase) undef (silent)
806 # 'En' 2 NO (mixed case) undef (silent)
807 # 'en_US' 5 NO (underscore) undef (silent)
808  
809 =head4 Input
810  
811 # Setter: one positional SCALAR (may be undef, '', or '0')
812 # Getter: no arguments
813  
814 =head4 Value domain (setter)
815  
816 Any scalar value -- including C<undef>, C<''>, and C<'0'> -- is accepted
817 and stored verbatim. C<encode()> will later skip C<undef> and reference
818 values; the accessor itself is a transparent store.
819  
820 # EQUIVALENCE PARTITIONS
821 #
822 # VALUE STORED? ENCODE() EFFECT
823 # --------------------------------------------------
824 # 'hello' YES encoded if non-ASCII chars
825 # '' YES unchanged (no entities)
826 # '0' YES unchanged
827 # undef YES skipped by encode() (preserved)
828 # arrayref YES skipped by encode() (preserved)
829  
830 =head4 Output
831  
832 # Return::Set schema
833 on_set => SCALAR | undef # the value just stored
834 on_get => SCALAR | undef # the stored value, or undef if absent
835 on_invalid => undef # silently, for non-language method names
836  
837 =head3 MESSAGES
838  
839 None. All failure cases return C<undef> silently. See L</COMMON PITFALLS>
840 for guidance on typo detection.
841  
842 =cut
843  
844 641 ▶sub AUTOLOAD {
Subroutine AUTOLOAD: called CC=6 SCAR=17.9
845 641 ▶ my $self = shift or return;
Branch: 1 branch
BranchTrueFalseTotal
my $self = shift() or return 641 0 641
846  
847 641 my ($key) = $AUTOLOAD =~ /::(\w+)\z/;
848  
849 641 ▶ return if $key eq 'DESTROY';
Branch: 1 branch
BranchTrueFalseTotal
if $key eq "DESTROY" 553 88 641
850 88 ▶ return unless ref($self) eq __PACKAGE__;
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self eq __PACKAGE__ 1 87 88
851 # Syllogism:
852 # P1: _is_valid_language accepts ^[a-z]{2}(?:_[A-Z]{2})?$ (case-sensitive).
853 # P2: AUTOLOAD method names are bare identifiers; the \w+ capture never
854 # produces the _XX suffix, so the relevant subset is ^[a-z]{2}$.
855 # P3: Any key passing /^[a-z]{2}$/ (no i-flag) is exactly two lowercase
856 # letters -- a strict subset of what _is_valid_language accepts.
857 # Conclusion: the _is_valid_language call is a tautology after the regex
858 # and is removed. The i-flag is also dropped to make the check strict.
859 87 ▶ return unless $key =~ /^[a-z]{2}$/;
Branch: 1 branch
BranchTrueFalseTotal
unless $key =~ /^[a-z]{2}$/ 32 55 87
860  
861 # Install a real method for $key so all future calls bypass AUTOLOAD entirely.
862 # Each two-letter code gets its own closure installed exactly once. This
863 # reduces repeated accessor cost from AUTOLOAD overhead (~5 regex ops) to a
864 # direct method dispatch, which is the dominant cost when rendering a page
865 # that stringifies many objects through the same language code.
866 {
867 16 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
868 55 ▶ *{__PACKAGE__ . '::' . $key} = sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
869 519 ▶ my $s = shift or return;
Branch: 1 branch
BranchTrueFalseTotal
my $s = shift() or return 519 0 519
870 519 ▶ $s->{'texts'}->{$key} = shift if @_;
Branch: 1 branch
BranchTrueFalseTotal
if @_ 74 445 519
871 519 return $s->{'texts'}->{$key};
872 55 };
873 }
874  
875 # Use @_ presence (not truthiness) so falsy values like '0' or '' are stored
876 55 ▶ if(@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 16 39 55
877 16 $self->{'texts'}->{$key} = shift;
878 }
879  
880 55 return $self->{'texts'}->{$key};
881 }
882  
883 # ---------------------------------------------------------------------------
884 # Private helpers
885 # ---------------------------------------------------------------------------
886  
887 # Purpose: Format a message from the catalog with the package name filled in.
888 # Entry: $key -- key into %MESSAGES.
889 # Exit: Formatted string ready for Carp.
890 # Effects: None.
891 132 ▶sub _err :Protected {
Subroutine _err: called CC=2 SCAR=6.9
892 132 my ($key) = @_;
893 132 my $fmt = $MESSAGES{$key};
894 132 ▶ return sprintf($fmt, __PACKAGE__) if defined($fmt);
Branch: 1 branch
BranchTrueFalseTotal
if defined $fmt 130 2 132
895 # Defensive: a future caller added a new key without a matching %MESSAGES entry.
896 # confess rather than returning a string so the programmer sees the bad key
897 # immediately at the call site instead of getting a silent wrong message.
898 2 Carp::confess("Internal error: _err() called with unknown key '$key' -- add it to %MESSAGES");
899 16 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
900  
901 # Purpose: Issue a carp warning for a set() usage mistake and return undef.
902 # Extracted to eliminate the duplicated carp + return pattern in set().
903 # Entry: None (uses package-level _err).
904 # Exit: undef.
905 # Effects: Emits a Carp warning visible at the caller's call site.
906 78 ▶sub _carp_set_usage :Protected {
Subroutine _carp_set_usage: called CC=1 SCAR=0.0
907 78 Carp::carp(_err('set_usage'));
908 78 return;
909 16 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
910  
911 # https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html
912 # https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html
913 #
914 # Purpose: Determine the two-letter ISO 639-1 language code for the running
915 # environment by probing standard locale environment variables in
916 # precedence order.
917 # Entry: Environment variables: LANGUAGE, LC_ALL, LC_MESSAGES, LANG.
918 # Exit: Lower-case two-letter code (e.g. 'en', 'fr'), or undef if the
919 # locale is absent, empty, or set to the POSIX 'C' locale.
920 # Returns 'en' when LANG=C or LANG=C.<encoding>.
921 # Effects: Read-only. The result is memoised against an env-var snapshot so
922 # repeated calls within the same process incur only five string
923 # comparisons rather than a full I18N::LangTags::Detect scan.
924 # The cache is invalidated automatically whenever LANGUAGE, LC_ALL,
925 # LC_MESSAGES, LANG, or HTTP_ACCEPT_LANGUAGE changes (e.g. local %ENV
926 # in tests).
927 {
928 16 my ($cached_lang, %cached_env);
929  
930 186 ▶ sub _get_language :Protected {
Subroutine _get_language: called CC=21 SCAR=30.5
931 # Fast path: env vars unchanged since last call -- return cached result.
932 # Using 'exists' rather than defined($cached_lang) so a cached undef is
933 # also served from cache (avoids re-probing an env with no locale set).
934 186 ▶ if(exists $cached_env{LANG}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $cached_env{"LANG"}) 172 14 186
935 172 my $stale = 0;
936 172 for my $v (qw(LANGUAGE LC_ALL LC_MESSAGES LANG HTTP_ACCEPT_LANGUAGE)) {
937 651 ▶ if(($ENV{$v} // '') ne $cached_env{$v}) { $stale = 1; last }
Branch: 1 branch
BranchTrueFalseTotal
if (($ENV{$v} // "") ne $cached_env{$v}) 140 511 651
Condition100%2/2
$ENV{$v} // ""
l!l
155496
MC/DC100%1/1
$ENV{$v} // ""
$ENV{$v}
Truth table100%2/2
A
A= $ENV{$v}
Aresult
11
00
938 }
939 172 ▶ return $cached_lang unless $stale;
Branch: 1 branch
BranchTrueFalseTotal
unless $stale 32 140 172
940 }
941  
942 # Slow path: probe the environment.
943 # SECURITY V1 (taint mode): under perl -T, %ENV values are tainted.
944 # Perl only untaints a substring via a regex CAPTURE GROUP -- the captured
945 # $1 is untainted once the match succeeds. substr() on a tainted string
946 # propagates taint, so the previous substr()-based extraction was wrong
947 # for taint-mode callers. Restore explicit capturing groups here.
948 154 my $lang;
949 154 for my $tag (I18N::LangTags::Detect::detect()) {
950 34 ▶ if($tag =~ /^([a-z]{2})/i) { $lang = lc($1); last } # $1 untainted
Branch: 1 branch
BranchTrueFalseTotal
if ($tag =~ /^([a-z]{2})/i) 32 2 34
951 }
952 154 ▶ if(!defined($lang) && ($ENV{'LANGUAGE'} // '') =~ /^([a-z]{2})/i) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $lang and ($ENV{"LANGUAGE"} // "") =~ /^([a-z]{2})/i) 6 148 154
Condition100%5/5
not defined $lang and ($ENV{"LANGUAGE"} // "") =~ /^([a-z]{2})/i
!ll&&!rl&&r
321166
$ENV{"LANGUAGE"} // ""
l!l
16106
MC/DC100%2/2
not defined $lang and ($ENV{"LANGUAGE"} // "") =~ /^([a-z]{2})/i
not defined $lang $ENV{"LANGUAGE"}
Truth table100%3/3
not(A) and B
A= not defined $langB= $ENV{"LANGUAGE"}
ABresult
0X0
100
111
953 6 $lang = lc($1); # $1 untainted
954 }
955 154 ▶ if(!defined($lang)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $lang) 116 38 154
956 116 for my $var ('LC_ALL', 'LC_MESSAGES', 'LANG') {
957 334 ▶ my $val = $ENV{$var} // next;
Condition100%2/2
$ENV{$var} // (next)
l!l
99235
MC/DC100%1/1
$ENV{$var} // (next)
$ENV{$var}
Truth table100%2/2
A
A= $ENV{$var}
Aresult
11
00
958 99 ▶ if($val =~ /^([a-z]{2})/i) {
Branch: 1 branch
BranchTrueFalseTotal
if ($val =~ /^([a-z]{2})/i) 67 32 99
959 67 my $code = lc($1); # $1 untainted
960 67 ▶ if(_is_valid_language($code)) { $lang = $code; last }
Branch: 1 branch
BranchTrueFalseTotal
if (_is_valid_language($code)) 67 0 67
961 }
962 }
963 }
964 # POSIX 'C' locale is treated as English.
965 # (?:\z|\.) matches 'C' at end-of-string or 'C.' (e.g. 'C.UTF-8').
966 # Non-capturing group: the dot is tested but its value is never needed.
967 154 ▶ $lang //= 'en' if ($ENV{'LANG'} // '') =~ /^C(?:\z|\.)/;
Branch: 1 branch
BranchTrueFalseTotal
if ($ENV{"LANG"} // "") =~ /^C(?:\z|\.)/ 9 145 154
Condition75%3/4
$ENV{"LANG"} // ""
l!l
10549
$lang //= "en"
l!l
09
MC/DC100%1/1
$ENV{"LANG"} // ""
$ENV{"LANG"}
MC/DC0%0/1
$lang //= "en"
$lang
Truth table100%2/2
A
A= $ENV{"LANG"}
Aresult
11
00
Truth table50%1/2
A
A= $lang
Aresult
11
00
968  
969 # Cache result and snapshot the five vars we check.
970 154 $cached_lang = $lang;
971 154 ▶ $cached_env{$_} = $ENV{$_} // '' for qw(LANGUAGE LC_ALL LC_MESSAGES LANG HTTP_ACCEPT_LANGUAGE);
Condition100%2/2
$ENV{$_} // ""
l!l
178592
MC/DC100%1/1
$ENV{$_} // ""
$ENV{$_}
Truth table100%2/2
A
A= $ENV{$_}
Aresult
11
00
972 154 return $lang;
973 16 ▶ }
Subroutine BEGIN: called CC=1 SCAR=0.0
974 }
975  
976 # Purpose: Validate that a string is a well-formed language code accepted by
977 # this module (ISO 639-1 with optional ISO 3166-1 country suffix).
978 # Entry: $lang -- candidate string.
979 # Exit: True if $lang matches $LANG_RE; false otherwise.
980 16 ▶sub _is_valid_language :Protected {
Subroutine _is_valid_language: called CC=1 SCAR=0.0
981 520 my ($lang) = @_;
982 520 return $lang =~ $LANG_RE;
983 16 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
984  
985 =head1 COMMON PITFALLS
986  
987 This section documents behaviours that often surprise first-time users.
988  
989 =head2 encode() cannot be undone
990  
991 C<encode()> modifies the object in place. There is no C<decode()>. If you
992 call C<encode()> twice on the same object, every special character is encoded
993 twice (e.g. C<&eacute;> becomes C<&amp;eacute;>). Always call C<encode()>
994 once, as the last step, and only on a freshly built object.
995  
996 # WRONG -- double-encoding
997 my $t = Lingua::Text->new(fr => "\x{E9}tude")->encode()->encode();
998 print $t->fr(); # &amp;eacute;tude (broken HTML)
999  
1000 # CORRECT
1001 my $t = Lingua::Text->new(fr => "\x{E9}tude")->encode();
1002 print $t->fr(); # &eacute;tude
1003  
1004 =head2 Missing translation returns undef, not an empty string
1005  
1006 When a translation is not stored for the requested language, C<as_string()>
1007 and the accessor methods return C<undef>, not C<"">. Use C<defined()> to test
1008 for absence, not a truth check.
1009  
1010 my $t = Lingua::Text->new(en => 'hello');
1011  
1012 my $de = $t->de();
1013 print "Missing\n" unless defined($de); # correct
1014 print "Missing\n" unless $de; # WRONG -- also triggers for $de = '0'
1015  
1016 =head2 Typos in language codes are silent
1017  
1018 The AUTOLOAD accessor returns C<undef> for any two-letter name that is not a
1019 valid ISO 639-1 code, and also for valid codes that have no stored translation.
1020 A typo like C<$t-E<gt>enn()> produces C<undef> without any warning.
1021  
1022 $t->en('hello');
1023 print $t->enn(); # undef -- no warning, no error
1024  
1025 To guard against this, always check with C<defined()> and, during development,
1026 consider adding a test that verifies the expected languages are present.
1027  
1028 =head2 new('text') silently drops the text when no locale is set
1029  
1030 When you pass a single string to C<new()>, it is stored under the current
1031 system language. If no locale environment variable (C<LANG>, C<LC_MESSAGES>,
1032 etc.) is set, the language cannot be determined and the text is silently
1033 discarded.
1034  
1035 # Safe: locale is set
1036 $ENV{LANG} = 'en_GB.UTF-8';
1037 my $t = Lingua::Text->new('hello');
1038 print $t->en(); # hello
1039  
1040 # Unsafe: no locale
1041 delete $ENV{LANG};
1042 delete $ENV{LC_MESSAGES};
1043 my $t = Lingua::Text->new('hello'); # text is lost
1044 print defined($t->en()) ? $t->en() : 'lost'; # lost
1045  
1046 # Safe alternative: always name the language explicitly
1047 my $t = Lingua::Text->new(en => 'hello');
1048  
1049 =head2 set() and the language accessors return $self or the value, not the text
1050  
1051 C<set()> returns the object (C<$self>). Because of the stringify overload,
1052 when you print or compare the return value, it I<looks> like a string -- but it
1053 is an object. Do not rely on this behaviour; retrieve the value separately.
1054  
1055 my $t = Lingua::Text->new();
1056 my $result = $t->set(text => 'Hello', lang => 'en');
1057  
1058 # $result is the Lingua::Text object, not the string 'Hello'
1059 # This works due to stringify overload, but is misleading:
1060 print $result; # Hello (via stringify)
1061  
1062 # Clearer intent:
1063 $t->set(text => 'Hello', lang => 'en');
1064 print $t->as_string('en'); # Hello
1065  
1066 The AUTOLOAD setter (e.g. C<$t-E<gt>en('Hello')>) returns the stored value
1067 directly, not C<$self>.
1068  
1069 =head2 A Lingua::Text object is always true
1070  
1071 The object overloads the boolean C<bool> operator to always return true, even
1072 when it contains no translations. Do B<not> use an object as a truth test to
1073 check whether it has any content.
1074  
1075 my $t = Lingua::Text->new(); # empty
1076 if($t) { print "always reached\n"; } # always true
1077  
1078 # To check whether a specific language is stored:
1079 if(defined($t->en())) { print "English is stored\n"; }
1080  
1081 =head2 Function-style call with arguments is an error
1082  
1083 Perl allows calling methods as functions, but Lingua::Text::new() (with
1084 double-colon and arguments) will emit a warning and return C<undef>.
1085  
1086 my $t = Lingua::Text::new(en => 'hi'); # WRONG -- carp warning, returns undef
1087 my $t = Lingua::Text->new(en => 'hi'); # correct
1088  
1089 Calling C<Lingua::Text::new()> with B<no> arguments works (it creates an empty
1090 object), but the arrow form is still preferred.
1091  
1092 =head1 PERFORMANCE
1093  
1094 Three optimisations address the hot paths in typical web or CGI use (many
1095 objects stringified per request, same accessor called repeatedly):
1096  
1097 =over 4
1098  
1099 =item B<Memoised locale detection>
1100  
1101 C<_get_language()> is called on every C<as_string()> invocation (including
1102 stringify via C<"">). The result is cached against a snapshot of the five
1103 relevant environment variables (C<LANGUAGE>, C<LC_ALL>, C<LC_MESSAGES>,
1104 C<LANG>, C<HTTP_ACCEPT_LANGUAGE>). As long as those variables do not change,
1105 subsequent calls cost only five string comparisons instead of a full
1106 C<I18N::LangTags::Detect::detect()> scan. The cache is invalidated
1107 automatically when any of those variables change -- including C<local %ENV>
1108 in tests.
1109  
1110 =item B<AUTOLOAD method installation>
1111  
1112 The first call to any two-letter accessor (e.g. C<$t-E<gt>en()>) installs a
1113 real subroutine in the package symbol table. All subsequent calls for that
1114 code dispatch directly, bypassing the AUTOLOAD regex and guard overhead
1115 entirely.
1116  
1117 =item B<Single-argument fast path in as_string()>
1118  
1119 C<$t-E<gt>as_string('en')> skips C<Params::Get::get_params()> when exactly
1120 one non-reference argument is supplied. Named (C<lang =E<gt> 'en'>) and
1121 hashref (C<{ lang =E<gt> 'en' }>) forms still go through the full parser.
1122  
1123 =back
1124  
1125 =head1 LIMITATIONS
1126  
1127 =over 4
1128  
1129 =item * B<No decode()>: Once C<encode()> is called, all translations are
1130 HTML-entity-encoded. There is no method to reverse this.
1131  
1132 =item * B<No language fallback>: If C<en_GB> is the system locale but only
1133 C<en> is stored, the module finds the text correctly (because the country
1134 suffix is stripped). However, if C<en_GB> is stored as a key and the system
1135 locale is C<en_US>, the text is I<not> found. Only two-letter codes are used
1136 as storage keys.
1137  
1138 =item * B<Silent AUTOLOAD failures>: Unrecognised method names (including
1139 typos) return C<undef> without any diagnostic.
1140  
1141 =item * B<Object::Configure semantics>: The exact effect of
1142 L<Object::Configure> depends on the installed version and any project-level
1143 configuration present. Without a configuration file, it passes parameters
1144 through unchanged.
1145  
1146 =back
1147  
1148 =head1 DEPENDENCIES
1149  
1150 Runtime:
1151  
1152 =over 4
1153  
1154 =item * L<Carp> -- C<carp>/C<croak> for warnings and errors
1155  
1156 =item * L<HTML::Entities> -- HTML entity encoding in C<encode()>
1157  
1158 =item * L<I18N::LangTags::Detect> -- locale detection from environment variables
1159  
1160 =item * L<Object::Configure> -- optional config-file defaults for C<new()>
1161  
1162 =item * L<Params::Get> -- flexible argument parsing for public methods
1163  
1164 =item * L<Readonly> -- constant definitions for the message catalog and patterns
1165  
1166 =item * L<Scalar::Util> -- C<blessed()> for safe type testing
1167  
1168 =item * L<Sub::Protected> -- enforcement of protected method access
1169  
1170 =back
1171  
1172 =head1 AUTHOR
1173  
1174 Nigel Horne, C<< <njh at nigelhorne.com> >>
1175  
1176 =head1 BUGS
1177  
1178 Please report bugs at L<https://github.com/nigelhorne/Lingua-Text/issues>.
1179  
1180 =head1 SEE ALSO
1181  
1182 =over 4
1183  
1184 =item * L<Object::Configure> -- runtime object configuration
1185  
1186 =item * L<I18N::LangTags::Detect> -- the locale detection module used internally
1187  
1188 =item * L<HTML::Entities> -- the HTML encoding module used by C<encode()>
1189  
1190 =item * L<Test Dashboard|https://nigelhorne.github.io/CGI-Info/coverage/>
1191  
1192 =back
1193  
1194 =head1 SUPPORT
1195  
1196 This module is provided as-is without any warranty.
1197  
1198 Documentation:
1199  
1200 perldoc Lingua::Text
1201  
1202 Online resources:
1203  
1204 =over 4
1205  
1206 =item * MetaCPAN: L<https://metacpan.org/release/Lingua-Text>
1207  
1208 =item * Bug tracker: L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Lingua-Text>
1209  
1210 =item * CPANTS: L<http://cpants.cpanauthors.org/dist/Lingua-Text>
1211  
1212 =item * CPAN Testers: L<http://matrix.cpantesters.org/?dist=Lingua-Text>
1213  
1214 =item * Dependencies: L<http://deps.cpantesters.org/?module=Lingua-Text>
1215  
1216 =back
1217  
1218 =encoding utf-8
1219  
1220 =head1 FORMAL SPECIFICATION
1221  
1222 =head2 new
1223  
1224 -- Type definitions
1225 STRING == seq CHAR
1226 LANG == { l : STRING | l =~ /^[a-z]{2}(_[A-Z]{2})?$/ }
1227  
1228 -- State: a partial function from language codes to strings
1229 ┌─ LinguaText ────────────────────────────────────────────
1230 │ texts : LANG ⇸ STRING
1231 └─────────────────────────────────────────────────────────
1232  
1233 -- Construction: initialise texts from zero or more lang/string pairs
1234 ┌─ new ───────────────────────────────────────────────────
1235 │ ΔLinguaText
1236 │ init? : LANG ⇸ STRING
1237 ├─────────────────────────────────────────────────────────
1238 │ texts' = init?
1239 └─────────────────────────────────────────────────────────
1240  
1241 -- Clone: merge the parent's texts with any new pairs (new pairs win)
1242 ┌─ clone ─────────────────────────────────────────────────
1243 │ ΔLinguaText
1244 │ parent? : LinguaText
1245 │ extra? : LANG ⇸ STRING
1246 ├─────────────────────────────────────────────────────────
1247 │ texts' = parent?.texts ⊕ extra?
1248 └─────────────────────────────────────────────────────────
1249  
1250 =head2 set
1251  
1252 -- set: add or replace one translation; all others remain unchanged
1253 ┌─ set ───────────────────────────────────────────────────
1254 │ ΔLinguaText
1255 │ lang? : LANG
1256 │ text? : STRING
1257 ├─────────────────────────────────────────────────────────
1258 │ texts' = texts ⊕ { lang? ↦ text? }
1259 └─────────────────────────────────────────────────────────
1260 -- ⊕ denotes relational override: lang? wins over any existing entry
1261  
1262 =head2 as_string
1263  
1264 -- as_string: look up one translation; state is unchanged (Xi schema)
1265 ┌─ as_string ─────────────────────────────────────────────
1266 │ ΞLinguaText
1267 │ lang? : LANG ∪ { current_locale }
1268 │ result! : STRING ∪ { undef }
1269 ├─────────────────────────────────────────────────────────
1270 │ lang? ∈ dom texts ⟹ result! = texts(lang?)
1271 │ lang? ∉ dom texts ⟹ result! = undef
1272 └─────────────────────────────────────────────────────────
1273 -- The state schema Ξ means texts is not modified by this operation.
1274  
1275 =head2 encode
1276  
1277 -- Let entity : STRING -> STRING be HTML::Entities::encode_entities
1278 -- and dec : STRING -> STRING be utf8::decode (applied only when needed)
1279 ┌─ encode ────────────────────────────────────────────────
1280 │ ΔLinguaText
1281 │ ∀ l : dom texts
1282 │ • texts'(l) = entity(dec(texts(l)))
1283 └─────────────────────────────────────────────────────────
1284 -- texts' replaces every value; dom texts is unchanged.
1285  
1286 =head1 LICENCE AND COPYRIGHT
1287  
1288 Copyright 2021-2026 Nigel Horne.
1289  
1290 Usage is subject to the GPL2 licence terms.
1291 If you use it, please let me know.
1292  
1293 =cut
1294  
1295 16 1;
↑ Summary