Zonemaster/Engine/Translator.pm untested

filter: Statementstmt 0.0% 0 / 137 Branchbran 0.0% 0 / 30 Conditioncond 0.0% 0 / 31 MC/DCmcdc 0.0% 0 / 19 Subroutinesub 0.0% 0 / 24 Podpod 0.0% 0 / 15 totaltotal 0.0% 0 / 256 CC 16 SCAR 22.5
CC
16
Cov
0%
initialize
20.0
_init_locale
20.0
locale
20.0
CRAP 9.5
1 package Zonemaster::Engine::Translator;
2  
3 use v5.16.0;
4 use warnings;
5  
6 use version; our $VERSION = version->declare("v1.0.8");
7  
8 use Carp qw[confess croak];
9 use Locale::Messages qw[textdomain];
10 use Locale::TextDomain qw[Zonemaster-Engine];
11 use POSIX qw[setlocale LC_MESSAGES];
12 use Readonly;
13  
14 use Zonemaster::Engine::Test;
15  
16 ###
17 ### Tag descriptions
18 ###
19  
20 Readonly my %TAG_DESCRIPTIONS => (
21 CANNOT_CONTINUE => sub {
22 __x # SYSTEM:CANNOT_CONTINUE
23 "Not enough data about {domain} was found to be able to run tests.", @_;
24 },
25 DEPENDENCY_VERSION => sub {
26 __x # SYSTEM:DEPENDENCY_VERSION
27 "Using prerequisite module {name} version {version}.", @_;
28 },
29 GLOBAL_VERSION => sub {
30 __x # SYSTEM:GLOBAL_VERSION
31 "Using version {version} of the Zonemaster engine.", @_;
32 },
33 LOGGER_CALLBACK_ERROR => sub {
34 __x # SYSTEM:LOGGER_CALLBACK_ERROR
35 "Logger callback died with error: {exception}", @_;
36 },
37 LOOKUP_ERROR => sub {
38 __x # SYSTEM:LOOKUP_ERROR
39 "DNS query to {ns} for {domain}/{type}/{class} failed with error: {message}", @_;
40 },
41 MODULE_ERROR => sub {
42 __x # SYSTEM:MODULE_ERROR
43 "Fatal error in {module}: {msg}", @_;
44 },
45 MODULE_VERSION => sub {
46 __x # SYSTEM:MODULE_VERSION
47 "Using module {module} version {version}.", @_;
48 },
49 MODULE_END => sub {
50 __x # SYSTEM:MODULE_END
51 "Module {module} finished running.", @_;
52 },
53 NO_NETWORK => sub {
54 __x # SYSTEM:NO_NETWORK
55 "Both IPv4 and IPv6 are disabled.";
56 },
57 UNKNOWN_METHOD => sub {
58 __x # SYSTEM:UNKNOWN_METHOD
59 "Request to run unknown method {testcase} in module {module}.", @_;
60 },
61 UNKNOWN_MODULE => sub {
62 __x # SYSTEM:UNKNOWN_MODULE
63 "Request to run {testcase} in unknown module {module}. Known modules: {module_list}.", @_;
64 },
65 SKIP_IPV4_DISABLED => sub {
66 __x # SYSTEM:SKIP_IPV4_DISABLED
67 "IPv4 is disabled, not sending \"{rrtype}\" query to {ns}.", @_;
68 },
69 SKIP_IPV6_DISABLED => sub {
70 __x # SYSTEM:SKIP_IPV6_DISABLED
71 "IPv6 is disabled, not sending \"{rrtype}\" query to {ns}.", @_;
72 },
73 FAKE_DELEGATION_TO_SELF => sub {
74 __x # SYSTEM:FAKE_DELEGATION_TO_SELF
75 "Name server {ns} not adding fake delegation for domain {domain} to itself.", @_;
76 },
77 FAKE_DELEGATION_IN_ZONE_NO_IP => sub {
78 __x # SYSTEM:FAKE_DELEGATION_IN_ZONE_NO_IP
79 "The fake delegation of domain {domain} includes an in-zone name server {nsname} "
80 . "without mandatory glue (without IP address).",
81 @_;
82 },
83 FAKE_DELEGATION_NO_IP => sub {
84 __x # SYSTEM:FAKE_DELEGATION_NO_IP
85 "The fake delegation of domain {domain} includes a name server {nsname} "
86 . "that cannot be resolved to any IP address.",
87 @_;
88 },
89 PACKET_BIG => sub {
90 __x # SYSTEM:PACKET_BIG
91 "Big packet size ({size}) (try with \"{command}\").", @_;
92 },
93 );
94  
95 ###
96 ### Construction
97 ###
98  
99 my $instance;
100  
101 sub new {
102 my ( $class, %attrs ) = @_;
103  
104 $class->initialize( %attrs );
105  
106 return $class->instance;
107 }
108  
109 sub instance {
110 my ( $class ) = @_;
111  
112 if ( !defined $instance ) {
113 $class->initialize();
114 }
115  
116 return $instance;
117 }
118  
119 sub initialize {
120 my ( $class, %attrs ) = @_;
121  
122 if ( defined $instance ) {
123 confess "already initialized";
124 }
125  
126 my $locale;
127 if ( exists $attrs{locale} ) {
128 $locale = delete $attrs{locale};
129  
130 if ( !defined $locale || ref $locale ne '' ) {
131 confess "argument 'locale' must not be a defined scalar";
132 }
133 }
134  
135 my $obj = {
136 _locale => $locale // _init_locale(),
137 _all_tag_descriptions => $class->_build_all_tag_descriptions(),
138 _last_language => _build_last_language(),
139 };
140  
141 $instance = bless $obj, $class;
142  
143 return;
144 }
145  
146 ###
147 ### Builder Methods
148 ###
149  
150 # Get the program's underlying LC_MESSAGES and make sure it can be effectively
151 # updated down the line.
152 #
153 # If the underlying LC_MESSAGES is invalid, it attempts to second guess Perl's
154 # fallback locale.
155 #
156 # Side effects:
157 # * Updates the program's underlying LC_MESSAGES to the returned value.
158 # * Unsets LC_ALL.
159 sub _init_locale {
160 my $locale = setlocale( LC_MESSAGES, "" );
161  
162 delete $ENV{LC_ALL};
163  
164 if ( !defined $locale ) {
165 my $language = $ENV{LANGUAGE} // "";
166 for my $value ( split /:/, $language ) {
167 if ( $value ne "" && $value !~ /[.]/ ) {
168 $value .= ".UTF-8";
169 }
170 $locale = setlocale( LC_MESSAGES, $value );
171 if ( defined $locale ) {
172 last;
173 }
174 }
175 $locale //= "C";
176 }
177  
178 return $locale;
179 }
180  
181 sub _load_data {
182 my $self = shift;
183  
184 my $old_locale = $self->locale;
185  
186 $self->locale( 'C' );
187  
188 my %data;
189 for my $mod ( keys %{ $self->all_tag_descriptions } ) {
190 for my $tag ( keys %{ $self->all_tag_descriptions->{$mod} } ) {
191 $data{$mod}{$tag} = $self->_translate_tag( $mod, $tag, {} );
192 }
193 }
194  
195 $self->locale( $old_locale );
196  
197 return \%data;
198 }
199  
200 sub _build_all_tag_descriptions {
201 my ( $class ) = @_;
202  
203 my %all_tag_descriptions;
204  
205 $all_tag_descriptions{System} = \%TAG_DESCRIPTIONS;
206 foreach my $mod ( Zonemaster::Engine::Test->modules ) {
207 my $module = 'Zonemaster::Engine::Test::' . $mod;
208 $all_tag_descriptions{ $mod } = $module->tag_descriptions;
209 }
210  
211 return \%all_tag_descriptions;
212 }
213  
214 sub _build_last_language {
215 return $ENV{LANGUAGE} // '';
216 }
217  
218 ###
219 ### Instance methods
220 ###
221  
222 sub data {
223 my ( $self ) = @_;
224  
225 if ( !exists $self->{_data} ) {
226 $self->{_data} = $self->_load_data;
227 }
228  
229 return $self->{_data};
230 }
231  
232 sub all_tag_descriptions {
233 my ( $self ) = @_;
234  
235 return $self->{_all_tag_descriptions};
236 }
237  
238 sub locale {
239 my ( $self, @args ) = @_;
240  
241 if ( @args ) {
242 my $new_locale = shift @args;
243  
244 # On some systems gettext takes its locale from setlocale().
245 if ( !defined setlocale( LC_MESSAGES, $new_locale ) ) {
246 return;
247 }
248  
249 $self->_last_language( $ENV{LANGUAGE} // '' );
250  
251 # On some systems gettext takes its locale from %ENV.
252 $ENV{LC_MESSAGES} = $new_locale;
253  
254 # On some systems gettext refuses to switch over to another locale unless
255 # the textdomain is reset.
256 textdomain( 'Zonemaster-Engine' );
257  
258 if ( !defined $new_locale || ref $new_locale ne '' ) {
259 croak "locale must be a defined scalar";
260 }
261  
262 $self->{_locale} = $new_locale;
263 } ## end if ( @args )
264  
265 return $self->{_locale};
266 };
267  
268 sub to_string {
269 my ( $self, $entry ) = @_;
270  
271 return sprintf( "%7.2f %-9s %s", $entry->timestamp, $entry->level, $self->translate_tag( $entry ) );
272 }
273  
274 sub translate_tag {
275 my ( $self, $entry ) = @_;
276  
277 return $self->_translate_tag( $entry->module, $entry->tag, $entry->printable_args ) // $entry->string;
278 }
279  
280  
281 sub test_case_description {
282 my ( $self, $test_name ) = @_;
283  
284 my $module = $test_name;
285 $module =~ s/\d+$//;
286  
287 return $self->_translate_tag( $module, uc $test_name, {} ) // $test_name;
288 }
289  
290 sub _last_language {
291 my $self = shift;
292  
293 if ( @_ ) {
294 my $last_language = shift;
295 if ( !defined $last_language || ref $last_language ne '' ) {
296 croak "_last_language must be a defined scalar";
297 }
298 $self->{_last_language} = $last_language;
299 }
300  
301 return $self->{_last_language};
302 }
303  
304 sub _translate_tag {
305 my ( $self, $module, $tag, $args ) = @_;
306  
307 if ( $ENV{LANGUAGE} // '' ne $self->_last_language ) {
308 $self->locale( $self->locale );
309 }
310  
311 my $code = $self->all_tag_descriptions->{$module}{$tag};
312  
313 if ( $code ) {
314 return $code->( %{$args} );
315 }
316 else {
317 return undef;
318 }
319 }
320  
321 1;
322  
323 =head1 NAME
324  
325 Zonemaster::Engine::Translator - translation support for Zonemaster
326  
327 =head1 SYNOPSIS
328  
329 Zonemaster::Engine::Translator->initialize( locale => 'sv_SE.UTF-8' );
330  
331 my $trans = Zonemaster::Engine::Translator->instance;
332 say $trans->to_string($entry);
333  
334 This is a singleton class.
335  
336 The instance of this class requires exclusive control over C<$ENV{LC_MESSAGES}>
337 and the program's underlying LC_MESSAGES.
338 At times it resets gettext's textdomain.
339 On construction it unsets C<$ENV{LC_ALL}> and from then on it must remain unset.
340  
341 On systems that support C<$ENV{LANGUAGE}>, this variable overrides the locale()
342 attribute unless the locale() attribute is set to C<"C">.
343  
344 =head1 ATTRIBUTES
345  
346 =over
347  
348 =item locale
349  
350 The locale used for localized messages.
351  
352 say $translator->locale();
353 if ( !$translator->locale( 'sv_SE.UTF-8' ) ) {
354 say "failed to update locale";
355 }
356  
357 The value of this attribute is mirrored in C<$ENV{LC_MESSAGES}>.
358  
359 When writing to this attribute, a request is made to update the program's
360 underlying LC_MESSAGES.
361 If this request fails, the attribute value remains unchanged and an empty list
362 is returned.
363  
364 As a side effect when successfully updating this attribute gettext's textdomain
365 is reset.
366  
367 =item data
368  
369 A reference to a hash with translation data. This is unlikely to be useful to
370 end-users.
371  
372 =item all_tag_descriptions
373  
374 =back
375  
376 =head1 METHODS
377  
378 =over
379  
380 =item initialize(%args)
381  
382 Provide initial values for the single instance of this class.
383  
384 Zonemaster::Engine::Translator->initialize( locale => 'sv_SE.UTF-8' );
385  
386 This method must be called at most once and before the first call to instance().
387  
388 =item instance()
389  
390 Returns the single instance of this class.
391  
392 my $translator = Zonemaster::Engine::Translator->instance;
393  
394 If initialize() has not been called prior to the first call to instance(), it
395 is the same as if initialize() had been called without arguments.
396  
397 =item new(%args)
398  
399 Use of this method is deprecated.
400  
401 =over
402  
403 =item locale
404  
405 If no initial value is provided to the constructor, one is determined by calling
406 setlocale( LC_MESSAGES, "" ).
407  
408 =back
409  
410 =item to_string($entry)
411  
412 Takes a L<Zonemaster::Engine::Logger::Entry> object as its argument and returns a translated string with the timestamp, level, message and arguments in the
413 entry.
414  
415 =item translate_tag($entry)
416  
417 Takes a L<Zonemaster::Engine::Logger::Entry> object as its argument and returns a translation of its tag and arguments.
418  
419 =item test_case_description($testcase)
420  
421 Takes a string (test case ID) and returns the translated test case description.
422  
423 =item BUILD
424  
425 Internal method that's only mentioned here to placate L<Pod::Coverage>.
426  
427 =back
428  
429 =cut