blib/lib/Mojolicious/Plugin/Buffer/I18N.pm

filter: Statementstmt 100% 83 / 83 Branchbran 100% 30 / 30 Conditioncond 100% 20 / 20 MC/DCmcdc 100% 13 / 13 Subroutinesub 100% 20 / 20 Podpod 100% 2 / 2 totaltotal 100% 168 / 168 CC 23 SCAR 15.5
CC
23
Cov
100%
_variant_key
9.0
i18n
7.0
_select_variant
6.0
CRAP 4.7
« blib/lib/Mojolicious/Plugin/Buffer.pm ↑ Summary examples/hypnotoad/lib/MyApp.pm »
1 package Mojolicious::Plugin::Buffer::I18N;
2  
3 39 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 39 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 39 ▶use autodie qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 39 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
8 39 ▶use Exporter qw(import);
Subroutine BEGIN: called CC=1 SCAR=0.0
9 39 ▶use Params::Get qw(get_params);
Subroutine BEGIN: called CC=1 SCAR=0.0
10 39 ▶use Params::Validate::Strict qw(validate_strict);
Subroutine BEGIN: called CC=1 SCAR=0.0
11 39 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 39 ▶use Scalar::Util qw(blessed looks_like_number);
Subroutine BEGIN: called CC=1 SCAR=0.0
13 39 ▶use Sub::Private { mode => 'enforce' };
Subroutine BEGIN: called CC=1 SCAR=0.0
14  
15 39 ▶use version; our $VERSION = version->declare('0.002.0');
Subroutine BEGIN: called CC=1 SCAR=0.0
16  
17 # Classes that want the i18n() method import it rather than inheriting it, so
18 # the plugin keeps Mojolicious::Plugin as its only base class
19 39 our @EXPORT_OK = qw(i18n);
20  
21 # A placeholder is %{name}, or %{name:FORMAT} where FORMAT is a single
22 # sprintf conversion such as %d or %.1f. The conversion letters are limited
23 # so a translated string cannot smuggle in a vector flag or a %n.
24 39 Readonly::Scalar my $PLACEHOLDER => qr/(%\{(\w+)(?::(%[-+ 0#]*\d*(?:\.\d+)?[sdufeEgGxXob]))?\})/;
25  
26 # How deeply variant hashes (gender inside plural, or the reverse) may nest
27 # before the lookup gives up; it stops a self-referencing catalog looping
28 39 Readonly::Scalar my $MAX_VARIANT_DEPTH => 4;
29  
30 # Input schema for i18n(), shared by the code and the POD
31 39 Readonly::Hash my %I18N_SCHEMA => (
32 key => {type => 'string', min => 1},
33 args => {type => 'hashref', optional => 1},
34 );
35  
36 # The English catalog. Every user-facing string, error and log line in the
37 # distribution lives here so that it can be translated or reworded with the
38 # messages option instead of by editing code.
39 39 Readonly::Hash my %MESSAGES => (
40 # Programming errors in a caller of i18n() itself
41 i18n_key_missing => 'Mojolicious::Plugin::Buffer::I18N: a message key is required',
42  
43 # Plugin registration
44 options_not_hash => 'Mojolicious::Plugin::Buffer: options must be a hash reference',
45 unknown_option => q{Mojolicious::Plugin::Buffer: unknown option '%{option}'},
46 option_invalid => 'Mojolicious::Plugin::Buffer: %{option} has an invalid value',
47 option_flag => 'Mojolicious::Plugin::Buffer: %{option} must be a true or false value',
48 option_optimise_content => 'Mojolicious::Plugin::Buffer: optimise_content must be 0, 1 or 2',
49 option_last_modified => 'Mojolicious::Plugin::Buffer: last_modified must be 0, 1, an epoch, a date string or a code reference',
50 option_min_compress_size => 'Mojolicious::Plugin::Buffer: min_compress_size must be a non-negative integer',
51 option_min_compress_saving => 'Mojolicious::Plugin::Buffer: min_compress_saving must be a non-negative integer',
52 option_encodings => 'Mojolicious::Plugin::Buffer: encodings must be an array reference',
53 option_compressible_types => 'Mojolicious::Plugin::Buffer: compressible_types must be an array reference',
54 option_excluded_types => 'Mojolicious::Plugin::Buffer: excluded_types must be an array reference',
55 option_vary_by => 'Mojolicious::Plugin::Buffer: vary_by must be an array reference of header names',
56 option_cache_key => 'Mojolicious::Plugin::Buffer: cache_key must be a string or a code reference',
57 option_cache => 'Mojolicious::Plugin::Buffer: cache must be an object understanding get(), set() and remove()',
58 option_cache_duration => 'Mojolicious::Plugin::Buffer: cache_duration must be a duration',
59 option_template_mtime_cache => 'Mojolicious::Plugin::Buffer: template_mtime_cache must be an object understanding get() and set()',
60 option_template_mtime_cache_duration => 'Mojolicious::Plugin::Buffer: template_mtime_cache_duration must be a duration',
61 option_cache_lock_timeout => 'Mojolicious::Plugin::Buffer: cache_lock_timeout must be a positive number of seconds',
62 option_cache_lock => 'Mojolicious::Plugin::Buffer: cache_lock must be an object with acquire() and release() methods',
63 option_cache_lock_dir => 'Mojolicious::Plugin::Buffer: cache_lock_dir must be a directory path',
64 option_messages => 'Mojolicious::Plugin::Buffer: messages must be a hash reference',
65 lock_options_combined => 'Mojolicious::Plugin::Buffer: cache_lock and cache_lock_dir cannot be combined',
66 unknown_encoding => q{Mojolicious::Plugin::Buffer: unknown encoding '%{encoding}'},
67  
68 # Sent to a client while another request builds the page
69 retry_later => "The page is being generated, please try again.\n",
70  
71 # File lock backend
72 lock_dir_create_failed => q{Mojolicious::Plugin::Buffer: cannot create cache_lock_dir '%{dir}': %{error}},
73 lock_dir_not_writable => q{Mojolicious::Plugin::Buffer: cache_lock_dir '%{dir}' is not a writable directory},
74 lock_key_undefined => 'cache key is not defined',
75 lock_open_failed => 'cannot open %{path}: %{error}',
76 lock_failed => 'cannot lock %{path}: %{error}',
77 unlock_failed => 'cannot unlock %{path}: %{error}',
78  
79 # Redis lock backend
80 redis_client_invalid => 'Mojolicious::Plugin::Buffer: cache_lock redis must be an object with an eval() method or a code reference returning one',
81 redis_namespace_invalid => 'Mojolicious::Plugin::Buffer: cache_lock namespace must be a non-empty string',
82 redis_ttl_invalid => 'Mojolicious::Plugin::Buffer: cache_lock ttl must be a positive number of seconds',
83 redis_no_client => 'Redis client factory returned no client',
84 redis_no_result => 'Redis lock command returned no result',
85 redis_lock_failed => 'Redis lock failed: %{error}',
86 redis_unlock_failed => 'Redis unlock failed: %{error}',
87 redis_invalid_guard => 'invalid lock guard',
88  
89 # Log lines written while serving requests
90 log_no_packer => 'Buffer: HTML::Packer is not installed, optimising white space only',
91 log_declaration_failed => 'Buffer: %{method} failed: %{error}',
92 log_release_failed => 'Buffer: could not release waiting requests: %{error}',
93 log_optimised => {
94 one => 'Buffer: optimised HTML from %{from} to %{to} byte',
95 other => 'Buffer: optimised HTML from %{from} to %{to} bytes',
96 },
97 log_compressed => {
98 one => 'Buffer: compressed with %{encoding} from %{from} to %{to} byte',
99 other => 'Buffer: compressed with %{encoding} from %{from} to %{to} bytes',
100 },
101 log_compress_failed => 'Buffer: %{encoding} compression failed: %{error}',
102 log_packer_failed => 'Buffer: HTML::Packer failed: %{error}',
103 log_not_modified => 'Buffer: not modified, sending 304',
104 log_not_modified_etag => 'Buffer: not modified, sending 304 (ETag %{etag})',
105 log_cache_hit => 'Buffer: cache hit for %{key}',
106 log_cache_get_failed => 'Buffer: cache get failed: %{error}',
107 log_cache_set_failed => 'Buffer: cache set failed: %{error}',
108 log_cached => 'Buffer: cached the response for %{key}',
109 log_stale_entry => 'Buffer: discarding a cache entry older than the application or its templates',
110 log_lock_failed => 'Buffer: shared cache lock failed: %{error}',
111 log_unlock_failed => 'Buffer: shared cache unlock failed: %{error}',
112 unknown_error => 'unknown error',
113 log_building => 'Buffer: this request will build the cache entry for %{key}',
114 log_waiting => 'Buffer: waiting for the cache entry for %{key}',
115 log_waiting_worker => 'Buffer: waiting for another worker to build the cache entry for %{key}',
116 log_gave_up => 'Buffer: gave up waiting for another request to finish',
117 log_gave_up_worker => 'Buffer: gave up waiting for another worker',
118 log_filled_elsewhere => 'Buffer: another worker filled the cache entry',
119 log_not_cached_elsewhere => 'Buffer: the other worker did not cache a response',
120 log_finish_waiter_failed => 'Buffer: could not finish a waiting request: %{error}',
121 log_flight_expired => 'Buffer: an in-flight response did not finish in time',
122 log_serving_waiter => 'Buffer: serving a waiting request from the finished response',
123 log_uncacheable_flight => 'Buffer: the in-flight response could not be cached',
124 log_mtime_get_failed => 'Buffer: template mtime cache get failed: %{error}',
125 log_mtime_set_failed => 'Buffer: template mtime cache set failed: %{error}',
126 log_mtime_not_stored => 'Buffer: template mtime cache did not store the scan',
127 );
128  
129 =encoding utf8
130  
131 =head1 NAME
132  
133 Mojolicious::Plugin::Buffer::I18N - message catalog for Mojolicious::Plugin::Buffer
134  
135 =head1 VERSION
136  
137 Version 0.002.0
138  
139 =head1 SYNOPSIS
140  
141 Translate the text that visitors see when the server is busy (an
142 application using L<Mojolicious::Plugin::Buffer>):
143  
144 plugin 'Buffer' => {
145 messages => {
146 retry_later => "Die Seite wird erstellt, bitte versuchen Sie es erneut.\n",
147 },
148 };
149  
150 Reword a log line, keeping its plural forms. Give I<every> form, because an
151 override replaces the whole message:
152  
153 plugin 'Buffer' => {
154 messages => {
155 log_compressed => {
156 one => 'packed %{from} -> %{to} byte (%{encoding})',
157 other => 'packed %{from} -> %{to} bytes (%{encoding})',
158 },
159 },
160 };
161  
162 Use a code reference for a language whose plural rules need more than
163 C<zero>, C<one> and C<other>, such as Polish:
164  
165 plugin 'Buffer' => {
166 messages => {
167 log_optimised => sub {
168 my $args = shift;
169 my $n = $args->{count};
170 my $word = $n == 1 ? 'bajt'
171 : ($n % 10 >= 2 && $n % 10 <= 4 && ($n % 100 < 10 || $n % 100 >= 20)) ? 'bajty'
172 : 'bajtow';
173 return "Buffer: HTML z %{from} do %{to} $word";
174 },
175 },
176 };
177  
178 Use the catalog in your own class. The method reads the overrides from the
179 C<messages> key of the object:
180  
181 package My::Thing;
182 use Mojolicious::Plugin::Buffer::I18N qw(i18n);
183  
184 sub new { my ($class, %args) = @_; return bless {messages => $args{messages}}, $class }
185  
186 my $thing = My::Thing->new(messages => {unknown_option => q{No such option: %{option}}});
187 print $thing->i18n('unknown_option', {option => 'wibble'});
188 # No such option: wibble
189  
190 List every key, for example to start a translation:
191  
192 my $catalog = Mojolicious::Plugin::Buffer::I18N->catalog;
193 print "$_\n" for sort keys %$catalog;
194  
195 =head1 DESCRIPTION
196  
197 Every error, warning, log line and client-facing string produced by
198 L<Mojolicious::Plugin::Buffer> and its lock backends is looked up here by a
199 I<message key>, so none of them is written into the program logic. An
200 application can replace any of them with the C<messages> option of the
201 plugin, or the C<messages> attribute of a lock backend.
202  
203 =head2 How it works, in plain words
204  
205 =over 4
206  
207 =item 1. The program asks for a message by its key, for example
208 C<unknown_option>, and passes some values, for example
209 C<< {option =E<gt> 'wibble'} >>.
210  
211 =item 2. The object's own C<messages> hash is checked first. If it has the
212 key, that text is used. If not, the built-in English text is used.
213  
214 =item 3. If the text has several forms (for plural or gender), the right
215 form is chosen from the C<count> and C<gender> values.
216  
217 =item 4. Each placeholder, such as C<%{option}>, is replaced by its value.
218  
219 =item 5. If anything goes wrong (an unknown key, a missing form, a code
220 reference that dies), the key itself is returned. So you always see
221 I<something>, never an empty message.
222  
223 =back
224  
225 =head2 Words used in this document
226  
227 =over 4
228  
229 =item key
230  
231 The name of a message, for example C<retry_later>. Keys are ASCII words.
232  
233 =item template
234  
235 The text stored for a key, before placeholders are filled in.
236  
237 =item placeholder
238  
239 A marker in a template, written C<%{name}>, that is replaced by a value.
240  
241 =item variant
242  
243 One form of a message that has several forms, such as the singular form
244 C<one> and the plural form C<other>.
245  
246 =back
247  
248 =head2 Templates
249  
250 A template is one of these three things:
251  
252 =over 4
253  
254 =item a string
255  
256 Placeholders are written C<%{name}>, or C<%{name:FORMAT}> where C<FORMAT> is
257 a single C<sprintf> conversion such as C<%d>, C<%5.1f> or C<%x>. A
258 placeholder whose argument was not supplied is left in the text unchanged,
259 so a missing argument is visible rather than silently blank. An argument
260 that is present but undefined becomes the empty string.
261  
262 =item a hash of variants
263  
264 Used for plurals and grammatical gender. The rules are tried in this
265 order:
266  
267 =over 4
268  
269 =item 1. If the C<gender> argument is a key of the hash, that variant is
270 used.
271  
272 =item 2. Otherwise, if C<count> is a number: C<zero> is used for 0 and
273 C<one> for 1, when those keys exist.
274  
275 =item 3. Otherwise C<other> is used.
276  
277 =back
278  
279 Variants may be nested, for example gender variants whose values are plural
280 variants. Nesting stops after 4 levels.
281  
282 =item a code reference
283  
284 Called with the argument hash. It returns a string or a hash of variants.
285 Use it for languages whose plural rules cannot be written with C<zero>,
286 C<one> and C<other>. If it dies, the message key is used instead.
287  
288 =back
289  
290 =head1 METHODS
291  
292 =head2 i18n
293  
294 my $text = $self->i18n($key, \%args);
295  
296 =head3 Purpose
297  
298 Turn a message key and its arguments into text. It is exported on request
299 and called as a method, so overrides held by the calling object take
300 precedence over the English catalog.
301  
302 =head3 Arguments
303  
304 =over 4
305  
306 =item C<$key> (positional, required)
307  
308 The message key, a non-empty string such as C<'unknown_option'>.
309  
310 =item C<$args> (positional, optional)
311  
312 A hash reference of values for the placeholders, plus the optional
313 selectors C<count> and C<gender>.
314  
315 =back
316  
317 =head3 Returns
318  
319 The text of the message. For an unknown key the key itself is returned, so
320 a missing translation never hides that something happened.
321  
322 =head3 Side effects
323  
324 None. If the invocant is a blessed hash with a C<messages> hash, its entries
325 are consulted first; nothing is written.
326  
327 =head3 Example
328  
329 use Mojolicious::Plugin::Buffer::I18N qw(i18n);
330  
331 # Class method: the English catalog
332 print __PACKAGE__->i18n('unknown_encoding', {encoding => 'lzma'});
333 # Mojolicious::Plugin::Buffer: unknown encoding 'lzma'
334  
335 # Plural selection with a sprintf conversion
336 my $self = bless {messages => {
337 items => {
338 one => '%{count} item weighs %{kg:%.1f} kg',
339 other => '%{count} items weigh %{kg:%.1f} kg',
340 },
341 }}, __PACKAGE__;
342 print $self->i18n('items', {count => 3, kg => 2.25});
343 # 3 items weigh 2.2 kg
344  
345 =head3 API SPECIFICATION
346  
347 =head4 Input
348  
349 # Params::Get::get_params([qw(key args)], @_) then
350 # Params::Validate::Strict::validate_strict
351 {
352 key => { type => 'string', min => 1 },
353 args => { type => 'hashref', optional => 1 },
354 }
355  
356 =head4 Output
357  
358 # Return::Set schema
359 { type => 'string' }
360  
361 =head3 MESSAGES
362  
363 Key / Message Meaning Resolution
364 ---------------------------------------- ------------------------------ ----------------------------
365 i18n_key_missing No key was passed Pass a message key
366 "a message key is required"
367 validate_strict: Parameter 'key' ... The key was empty or not a Pass a non-empty string key
368 string
369 validate_strict: Parameter 'args' ... The arguments were not a hash Pass a hash reference
370  
371 All three croak. The last two come from L<Params::Validate::Strict> and are
372 not translated, because they report a programming error in the caller
373 rather than a condition a user can act on.
374  
375 =head3 PSEUDOCODE
376  
377 croak if there is no key
378 validate key and args
379 look the key up in the invocant's overrides, then in the catalog
380 if it is not found, return the key
381 while the template is a code reference or a hash of variants,
382 and the nesting limit has not been reached:
383 call the code reference, or pick the variant for gender/count
384 if the result is not a plain string, return the key
385 replace every %{name} or %{name:FORMAT} whose argument exists
386 return the text
387  
388 =cut
389  
390 201 ▶sub i18n {
Subroutine i18n: called CC=7 SCAR=19.5
Pod documented
391 201 my ($self, $key, $args) = @_;
392  
393 # The commonest misuse gets its own message; the schema covers the rest
394 201 ▶ croak(__PACKAGE__->i18n('i18n_key_missing')) unless defined($key);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $key 2 199 201
395  
396 # Positional (key, args) become a hash so the schema can name them
397 199 my $params = validate_strict(
398 schema => \%I18N_SCHEMA,
399 input => get_params([qw(key args)], $key, $args),
400 );
401 195 ▶ ($key, $args) = ($params->{key}, $params->{args} // {});
Condition100%2/2
$params->{"args"} // {}
l!l
15738
MC/DC100%1/1
$params->{"args"} // {}
$params->{"args"}
Truth table100%2/2
A
A= $params->{"args"}
Aresult
11
00
402  
403 # The invocant's overrides win over the English catalog
404 195 ▶ my $overrides = (blessed($self) && ref($self->{messages}) eq 'HASH') ? $self->{messages} : {};
Branch: 1 branch
BranchTrueFalseTotal
builtin::blessed($self) && ref $self->{'messages'} eq 'HASH' ? : 54 141 195
Condition100%3/3
builtin::blessed($self) and ref $self->{"messages"} eq "HASH"
!ll&&!rl&&r
613554
MC/DC100%2/2
builtin::blessed($self) and ref $self->{"messages"} eq "HASH"
builtin::blessed($self) ref $self->{"messages"} eq "HASH"
Truth table100%3/3
A and B
A= builtin::blessed($self)B= ref $self->{"messages"} eq "HASH"
ABresult
0X0
100
111
405 195 ▶ my $template = exists($overrides->{$key}) ? $overrides->{$key} : $MESSAGES{$key};
Branch: 1 branch
BranchTrueFalseTotal
exists $overrides->{$key} ? : 52 143 195
406  
407 195 my $text = _select_variant($template, $args);
408  
409 # An unknown key, or a template that resolved to nothing usable, is
410 # reported by name so the event is never lost
411 195 ▶ return defined($text) ? _interpolate($text, $args) : $key;
Branch: 1 branch
BranchTrueFalseTotal
defined $text ? : 185 10 195
412 }
413  
414 =head2 catalog
415  
416 my $messages = Mojolicious::Plugin::Buffer::I18N->catalog;
417  
418 =head3 Purpose
419  
420 Return a copy of the English catalog, for translators who want every key
421 and for tests that check a key exists.
422  
423 =head3 Arguments
424  
425 None.
426  
427 =head3 Returns
428  
429 A hash reference mapping each message key to its template. It is a shallow
430 copy: changing it does not change the catalog.
431  
432 =head3 Side effects
433  
434 None.
435  
436 =head3 Example
437  
438 my $catalog = Mojolicious::Plugin::Buffer::I18N->catalog;
439 print "$_\n" for sort keys %$catalog;
440  
441 =head3 API SPECIFICATION
442  
443 =head4 Input
444  
445 # No arguments besides the invocant
446 {}
447  
448 =head4 Output
449  
450 # Return::Set schema
451 { type => 'hashref', min => 1 }
452  
453 =head3 MESSAGES
454  
455 None.
456  
457 =cut
458  
459 86 ▶sub catalog {
Subroutine catalog: called CC=1 SCAR=0.0
Pod documented
460 86 return {%MESSAGES};
461 }
462  
463 # Purpose: Resolve a template to a plain string by following code
464 # references and gender/plural variant hashes.
465 # Entry criteria: $template is a string, hashref, coderef or undef; $args
466 # is a hashref.
467 # Exit status: The selected string, or undef when nothing usable was
468 # found (unknown key, missing variant, dying coderef, or
469 # nesting deeper than $MAX_VARIANT_DEPTH).
470 # Side effects: Calls translator-supplied code references.
471 195 ▶sub _select_variant :Private {
Subroutine _select_variant: called CC=6 SCAR=17.9
472 195 my ($template, $args) = @_;
473  
474 195 my $depth = 0;
475 195 ▶ while (ref($template) && ($depth++ < $MAX_VARIANT_DEPTH)) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $template and $depth++ < $MAX_VARIANT_DEPTH) 52 195 247
Condition100%3/3
ref $template and $depth++ < $MAX_VARIANT_DEPTH
!ll&&!rl&&r
193252
MC/DC100%2/2
ref $template and $depth++ < $MAX_VARIANT_DEPTH
ref $template $depth++ < $MAX_VARIANT_DEPTH
Truth table100%3/3
A and B
A= ref $templateB= $depth++ < $MAX_VARIANT_DEPTH
ABresult
0X0
100
111
476 52 ▶ if (ref($template) eq 'CODE') {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $template eq 'CODE') { } 10 42 52
elsif (ref $template eq 'HASH') { } 40 2 42
477 # A broken translation must not take the caller down with it
478 10 $template = eval { $template->($args) };
479 } elsif (ref($template) eq 'HASH') {
480 40 $template = $template->{_variant_key($template, $args)};
481 } else {
482 2 $template = undef;
483 }
484 }
485  
486 195 ▶ return ref($template) ? undef : $template;
Branch: 1 branch
BranchTrueFalseTotal
ref $template ? : 2 193 195
487 39 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
488  
489 # Purpose: Choose which variant of a hash applies to these arguments.
490 # Entry criteria: $variants is a hashref; $args is a hashref.
491 # Exit status: A key of $variants, or 'other' as the fallback.
492 # Side effects: None.
493 40 ▶sub _variant_key :Private {
Subroutine _variant_key: called CC=9 SCAR=22.0
494 40 my ($variants, $args) = @_;
495  
496 40 my ($gender, $count) = @{$args}{qw(gender count)};
497 40 my $key = 'other';
498  
499 # Gender is checked first so a gendered message can hold plural variants
500 40 ▶ if (defined($gender) && exists($variants->{$gender})) {
Branch: 2 branches
BranchTrueFalseTotal
if (defined $gender and exists $variants->{$gender}) { } 4 36 40
elsif (defined $count and &looks_like_number($count)) { } 24 22 46
Condition100%3/3
defined $gender and exists $variants->{$gender}
!ll&&!rl&&r
2884
MC/DC100%2/2
defined $gender and exists $variants->{$gender}
defined $gender exists $variants->{$gender}
Truth table100%3/3
A and B
A= defined $genderB= exists $variants->{$gender}
ABresult
0X0
100
111
501 4 $key = $gender;
502 ▶ } elsif (defined($count) && looks_like_number($count)) {
Condition100%3/3
defined $count and &looks_like_number($count)
!ll&&!rl&&r
10224
MC/DC100%2/2
defined $count and &looks_like_number($count)
defined $count &looks_like_number($count)
Truth table100%3/3
A and B
A= defined $countB= &looks_like_number($count)
ABresult
0X0
100
111
503 24 ▶ $key = 'zero' if ($count == 0) && exists($variants->{zero});
Branch: 1 branch
BranchTrueFalseTotal
if $count == 0 and exists $variants->{"zero"} 2 22 24
Condition100%3/3
$count == 0 and exists $variants->{"zero"}
!ll&&!rl&&r
2022
MC/DC100%2/2
$count == 0 and exists $variants->{"zero"}
$count == 0 exists $variants->{"zero"}
Truth table100%3/3
A and B
A= $count == 0B= exists $variants->{"zero"}
ABresult
0X0
100
111
504 24 ▶ $key = 'one' if ($count == 1) && exists($variants->{one});
Branch: 1 branch
BranchTrueFalseTotal
if $count == 1 and exists $variants->{"one"} 6 18 24
Condition100%3/3
$count == 1 and exists $variants->{"one"}
!ll&&!rl&&r
1626
MC/DC100%2/2
$count == 1 and exists $variants->{"one"}
$count == 1 exists $variants->{"one"}
Truth table100%3/3
A and B
A= $count == 1B= exists $variants->{"one"}
ABresult
0X0
100
111
505 }
506  
507 40 return $key;
508 39 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
509  
510 # Purpose: Fill %{name} and %{name:FORMAT} placeholders.
511 # Entry criteria: $text is a defined string; $args is a hashref.
512 # Exit status: The text with every supplied placeholder replaced.
513 # Placeholders with no argument are left as they are.
514 # Side effects: None; numeric-format warnings are silenced because a
515 # translated message must never produce a warning itself.
516 185 ▶sub _interpolate :Private {
Subroutine _interpolate: called CC=4 SCAR=13.9
517 185 my ($text, $args) = @_;
518  
519 39 ▶ no warnings qw(numeric redundant missing);
Subroutine BEGIN: called CC=1 SCAR=0.0
520 185 $text =~ s{$PLACEHOLDER}{
521 !exists($args->{$2}) ? $1
522 : !defined($args->{$2}) ? ''
523 : defined($3) ? sprintf($3, $args->{$2})
524 108 ▶ : $args->{$2}
Branch: 3 branches
BranchTrueFalseTotal
!exists $args->{$2} ? : 4 104 108
!defined($args->{$2}) ? : 2 102 104
defined $3 ? : 16 86 102
525 }ge;
526  
527 185 return $text;
528 39 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
529  
530 39 1;
531  
532 =head1 COMMON PITFALLS
533  
534 =over 4
535  
536 =item * B<An override replaces the whole message; it is not merged.> If the
537 built-in message has C<one> and C<other> forms and you override it with a
538 plain string, both forms are replaced by that one string. If you override
539 it with C<< {other =E<gt> '...'} >> only, there is no C<one> form any more.
540 Give every form you need.
541  
542 =item * B<undef is not "use the default".> C<< messages =E<gt>
543 {retry_later =E<gt> undef} >> makes the message the bare key, so visitors
544 see the word C<retry_later>. To go back to the built-in text, I<delete> the
545 key from the hash instead.
546  
547 =item * B<A missing argument stays visible.> C<i18n('unknown_option')>
548 without C<option> returns C<... unknown option '%{option}'>. This is on
549 purpose, so that a mistake shows. An argument that I<exists> but is undef
550 becomes the empty string.
551  
552 =item * B<There is no escape for a literal C<%{name}>.> If a translated
553 text must show C<%{word}> itself, do not pass an argument called C<word>.
554 A plain C<%> that is not followed by C<{> is always left alone.
555  
556 =item * B<Gender is checked before count.> With both C<gender> and C<count>
557 given, a matching gender variant wins. Put the plural forms I<inside> the
558 gender variant if you need both.
559  
560 =item * B<A code reference that dies is silent.> The key is returned
561 instead, and no warning is given. Test your code references.
562  
563 =item * B<A format is one conversion only.> C<%{n:%d}> works. C<%{n:%d%%}>
564 does not match the placeholder rule and is left in the text unchanged. The
565 conversions C<%n> and vector flags are refused on purpose.
566  
567 =item * B<Messages are chosen once per application.> The plugin does not
568 read C<Accept-Language>. See L</LIMITATIONS>.
569  
570 =back
571  
572 =head1 ENCODING
573  
574 =over 4
575  
576 =item Templates and arguments
577  
578 Both may hold any Perl characters: accented letters, any other script, and
579 emoji. Use C<use utf8;> in a source file that contains such characters
580 literally, or write them as escapes like C<"\x{1F600}">. A C<%{name:%5s}>
581 width counts characters, not bytes.
582  
583 =item The returned text
584  
585 The result is a Perl character string. It is not encoded. When you print
586 it, use a handle with an encoding layer, such as
587 C<binmode(STDOUT, ':encoding(UTF-8)')>, or Perl warns "Wide character".
588 L<Mojo::Log> encodes every line to UTF-8 by itself, so log lines are safe.
589 The plugin encodes the C<retry_later> text to UTF-8 and sends it with
590 C<charset=UTF-8>.
591  
592 =item Keys
593  
594 Keys are matched exactly. All built-in keys are ASCII; use ASCII for your
595 own keys too.
596  
597 =item Messages from Params::Validate::Strict
598  
599 These are English and are passed through unchanged.
600  
601 =back
602  
603 =head1 LIMITATIONS
604  
605 =over 4
606  
607 =item * Messages are chosen once per application, not per request. The
608 plugin does not negotiate C<Accept-Language>, so the C<retry_later> text sent
609 with a C<503> is the same for every client. A per-language reply needs a
610 custom C<messages> code reference that reads a value the application set.
611  
612 =item * Plural selection only knows C<zero>, C<one> and C<other>. Languages
613 with more categories (Polish, Arabic, Welsh, ...) need a code reference
614 template.
615  
616 =item * Messages produced by L<Params::Validate::Strict> for programming
617 errors (a missing or malformed message key) are passed through in English.
618  
619 =back
620  
621 =head1 SEE ALSO
622  
623 L<Mojolicious::Plugin::Buffer>
624  
625 =head1 AUTHOR
626  
627 Nigel Horne, C<< <njh at bandsman.co.uk> >>
628  
629 =head1 FORMAL SPECIFICATION
630  
631 This section describes the catalog in the Z notation, for readers who want
632 an exact model. You do not need it to use the module. C<defaults> is the
633 built-in English catalog and C<overrides> is the C<messages> hash of the
634 object the method is called on.
635  
636 [KEY, TEXT, NAME, VALUE]
637  
638 Args == NAME ⇸ VALUE
639 Template ::= str⟨⟨TEXT⟩⟩ | variants⟨⟨NAME ⇸ Template⟩⟩ | code⟨⟨Args → Template⟩⟩
640  
641 ┌─ Catalog ───────────────────────────────────
642 │ defaults : KEY ⇸ Template
643 │ overrides : KEY ⇸ Template
644 └─────────────────────────────────────────────
645  
646 select : Template × Args × ℕ ⇸ TEXT ∪ {⊥}
647  
648 select(t, a, d) = ⊥ if d ≥ 4 ∧ t ∉ ran str
649 select(str s, a, d) = s
650 select(code f, a, d) = select(f(a), a, d + 1) if f(a) does not die
651 = ⊥ otherwise
652 select(variants v, a, d) = select(v(pick(v, a)), a, d + 1)
653 if pick(v, a) ∈ dom v
654 = ⊥ otherwise
655  
656 pick(v, a) = gender a if gender a ∈ dom v
657 = zero if count a = 0 ∧ zero ∈ dom v
658 = one if count a = 1 ∧ one ∈ dom v
659 = other otherwise
660  
661 =head2 i18n
662  
663 C<interpolate> replaces each placeholder C<%{n}> or C<%{n:F}> for which
664 C<n ∈ dom args?>, and leaves every other placeholder unchanged.
665  
666 ┌─ I18n ──────────────────────────────────────
667 │ ΞCatalog
668 │ key? : KEY ; args? : Args ; text! : TEXT
669 ├─────────────────────────────────────────────
670 │ key? ≠ ∅
671 │ let m == defaults ⊕ overrides •
672 │ key? ∈ dom m ∧ select(m key?, args?, 0) ≠ ⊥
673 │ ⇒ text! = interpolate(select(m key?, args?, 0), args?)
674 │ key? ∉ dom m ∨ select(m key?, args?, 0) = ⊥
675 │ ⇒ text! = key?
676 └─────────────────────────────────────────────
677 -- key? undefined or empty, or args? not a hash: croak
678  
679 =head2 catalog
680  
681 ┌─ Catalog_Copy ──────────────────────────────
682 │ ΞCatalog
683 │ result! : KEY ⇸ Template
684 ├─────────────────────────────────────────────
685 │ result! = defaults
686 └─────────────────────────────────────────────
687  
688 =head1 STATE DIAGRAM
689  
690 This module keeps no state between calls: the catalog never changes while
691 the program runs, and the overrides belong to the calling object. So
692 instead of states, this diagram shows the path one call to L</i18n> takes.
693 Each box is a step; the text on an arrow is the condition for taking it.
694  
695 i18n(key, args)
696 |
697 v
698 +--------------------+ key undef or empty,
699 | 1. CHECK ARGUMENTS | or args not a hash
700 | | ----------------------> croak
701 +--------------------+
702 | ok
703 v
704 +--------------------+ key in neither hash
705 | 2. LOOK UP THE KEY | ----------------------> return the key
706 | overrides first, | (e.g. "retry_later")
707 | then the defaults |
708 +--------------------+
709 | found
710 v
711 +--------------------+ undef template, dying
712 | 3. RESOLVE | code ref, no variant
713 | code ref: call it | fits, or 4 levels deep
714 | hash: pick variant | ----------------------> return the key
715 | repeat until plain |
716 +--------------------+
717 | plain string
718 v
719 +--------------------+
720 | 4. FILL IN | This step cannot fail. A placeholder
721 | %{name} and | with no argument is left as it is.
722 | %{name:FORMAT} |
723 +--------------------+
724 |
725 v
726 return the text
727  
728 =head1 LICENSE AND COPYRIGHT
729  
730 Copyright 2026 Nigel Horne.
731  
732 This program is free software; you can redistribute it and/or modify it
733 under the terms of the GNU General Public License as published by the Free
734 Software Foundation; either version 2 of the License, or (at your option)
735 any later version.
736  
737 =cut
« blib/lib/Mojolicious/Plugin/Buffer.pm ↑ Summary examples/hypnotoad/lib/MyApp.pm »