| 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__)
}
}
not ref $class and defined $class
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__)
}
}
| |||||||||||||||||||||||||||||||||||
| 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__)
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__)
| |||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
$is_object or $is_class
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
| |||||||||||||||||||||||||||||||||||
| 340 | # undef invocant = bare Lingua::Text::new() with no args -- allowed | ||||||||||||||||||||||||||||||||||
| 341 | 18 | ▶ | if(defined($class)) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
scalar @_ == 1 and not ref $_[0]
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]
| |||||||||||||||||||||||||||||||||||
| 355 | 17 | my $lang = _get_language(); | |||||||||||||||||||||||||||||||||
| 356 | 17 | ▶ | $params = { $lang => $_[0] } if $lang; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 363 | 27 | ▶ | if($params) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 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()
MC/DC100%2/2
$params->{"lang"} // _get_language()
$params->{"lang"}
_get_language()
Truth table100%3/3
A // B
A= $params->{"lang"}B= _get_language()
| |||||||||||||||||||||||||||||||||||
| 508 | 185 | ▶ | return _carp_set_usage() unless defined($lang); | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 516 | |||||||||||||||||||||||||||||||||||
| 517 | 118 | my $text = $params->{'text'}; | |||||||||||||||||||||||||||||||||
| 518 | 118 | ▶ | return _carp_set_usage() unless defined($text); | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
@_ and defined $_[0]
MC/DC100%2/2
@_ and defined $_[0]
@_
defined $_[0]
Truth table100%3/3
A and B
A= @_B= defined $_[0]
| |||||||||||||||||||||||||||||||||||
| 645 | 93 | ▶ | if(my $params = Params::Get::get_params('lang', \@_)) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 646 | 93 | $lang = $params->{'lang'}; | |||||||||||||||||||||||||||||||||
| 647 | } | ||||||||||||||||||||||||||||||||||
| 648 | } | ||||||||||||||||||||||||||||||||||
| 649 | 233 | ▶ | $lang //= _get_language(); | ||||||||||||||||||||||||||||||||
|
Condition100%3/3
$lang //= _get_language()
MC/DC100%2/2
$lang //= _get_language()
$lang
_get_language()
Truth table100%3/3
A //= B
A= $langB= _get_language()
| |||||||||||||||||||||||||||||||||||
| 650 | |||||||||||||||||||||||||||||||||||
| 651 | 233 | ▶ | if(defined($lang)) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 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<"é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(); # é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
| |||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
defined $v and not ref $v
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
| |||||||||||||||||||||||||||||||||||
| 727 | |||||||||||||||||||||||||||||||||||
| 728 | 142 | ▶ | utf8::decode($v) unless utf8::is_utf8($v); | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 846 | |||||||||||||||||||||||||||||||||||
| 847 | 641 | my ($key) = $AUTOLOAD =~ /::(\w+)\z/; | |||||||||||||||||||||||||||||||||
| 848 | |||||||||||||||||||||||||||||||||||
| 849 | 641 | ▶ | return if $key eq 'DESTROY'; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 850 | 88 | ▶ | return unless ref($self) eq __PACKAGE__; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 870 | 519 | ▶ | $s->{'texts'}->{$key} = shift if @_; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 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
Condition100%2/2
$ENV{$v} // ""
MC/DC100%1/1
$ENV{$v} // ""
$ENV{$v}
Truth table100%2/2
A
A= $ENV{$v}
| |||||||||||||||||||||||||||||||||||
| 938 | } | ||||||||||||||||||||||||||||||||||
| 939 | 172 | ▶ | return $cached_lang unless $stale; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 951 | } | ||||||||||||||||||||||||||||||||||
| 952 | 154 | ▶ | if(!defined($lang) && ($ENV{'LANGUAGE'} // '') =~ /^([a-z]{2})/i) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%5/5
not defined $lang and ($ENV{"LANGUAGE"} // "") =~ /^([a-z]{2})/i
$ENV{"LANGUAGE"} // ""
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"}
| |||||||||||||||||||||||||||||||||||
| 953 | 6 | $lang = lc($1); # $1 untainted | |||||||||||||||||||||||||||||||||
| 954 | } | ||||||||||||||||||||||||||||||||||
| 955 | 154 | ▶ | if(!defined($lang)) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 956 | 116 | for my $var ('LC_ALL', 'LC_MESSAGES', 'LANG') { | |||||||||||||||||||||||||||||||||
| 957 | 334 | ▶ | my $val = $ENV{$var} // next; | ||||||||||||||||||||||||||||||||
|
Condition100%2/2
$ENV{$var} // (next)
MC/DC100%1/1
$ENV{$var} // (next)
$ENV{$var}
Truth table100%2/2
A
A= $ENV{$var}
| |||||||||||||||||||||||||||||||||||
| 958 | 99 | ▶ | if($val =~ /^([a-z]{2})/i) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 959 | 67 | my $code = lc($1); # $1 untainted | |||||||||||||||||||||||||||||||||
| 960 | 67 | ▶ | if(_is_valid_language($code)) { $lang = $code; last } | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 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
Condition75%3/4
$ENV{"LANG"} // ""
$lang //= "en"
MC/DC100%1/1
$ENV{"LANG"} // ""
$ENV{"LANG"}
MC/DC0%0/1
$lang //= "en"
$lang
Truth table100%2/2
A
A= $ENV{"LANG"}
Truth table50%1/2
A
A= $lang
| |||||||||||||||||||||||||||||||||||
| 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{$_} // ""
MC/DC100%1/1
$ENV{$_} // ""
$ENV{$_}
Truth table100%2/2
A
A= $ENV{$_}
| |||||||||||||||||||||||||||||||||||
| 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<é> becomes C<&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(); # &eacute;tude (broken HTML) | ||||||||||||||||||||||||||||||||||
| 999 | |||||||||||||||||||||||||||||||||||
| 1000 | # CORRECT | ||||||||||||||||||||||||||||||||||
| 1001 | my $t = Lingua::Text->new(fr => "\x{E9}tude")->encode(); | ||||||||||||||||||||||||||||||||||
| 1002 | print $t->fr(); # é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; | |||||||||||||||||||||||||||||||||