Debian Codegraph @

Debconf/Template.pm

raw
1 #!/usr/bin/perl
2
3 =head1 NAME
4
5 Debconf::Template - Template object with persistence.
6
7 =cut
8
9 package Debconf::Template;
10 use warnings;
11 use strict;
12 use POSIX;
13 use FileHandle;
14 use Debconf::Gettext;
15 use Text::Wrap;
16 use Text::Tabs;
17 use Debconf::Db;
18 use Debconf::Iterator;
19 use Debconf::Question;
20 use fields qw(template);
21 use Debconf::Log q{:all};
22 use Debconf::Encoding;
23 use Debconf::Config;
24
25 # Class data
26 our %template;
27 $Debconf::Template::i18n=1;
28
29 # A hash of known template fields. Others are warned about.
30 our %known_field = map { $_ => 1 }
31 qw{template description choices default type};
32
33 # Convince perl to not do encoding conversions on text output to stdout.
34 # Debconf does its own conversions.
35 binmode(STDOUT);
36 binmode(STDERR);
37
38 =head1 DESCRIPTION
39
40 This is an object that represents a Template. Each Template has some associated
41 data, the fields of the template structure. To get at this data, just use
42 $template->fieldname to read a field, and $template->fieldname(value) to write
43 a field. Any field names at all can be used, the convention is to lower-case
44 their names.
45
46 Common fields are "default", "type", and "description". The field
47 named "extended_description" holds the extended description, if any.
48
49 Templates support internationalization. If LANG or a related environment
50 variable is set, and you request a field from a template, it will see if
51 "fieldname-$LANG" exists, and if so return that instead.
52
53 =cut
54
55 =head1 CLASS METHODS
56
57 =item new(template, owner, type)
58
59 The name of the template to create must be passed to this function.
60
61 When a new template is created, a question is created with the same name
62 as the template. This is to ensure that the template has at least
63 one owner -- the question, and to make life easier for debconf users -- so
64 they don't have to manually register that question.
65
66 The owner field, then, is actually used to set the owner of the question.
67
68 =cut
69
70 sub new {
71 my Debconf::Template $this=shift;
72 my $template=shift || die "no template name specified";
73 my $owner=shift || 'unknown';
74 my $type=shift || die "no template type specified";
75
76 # See if we can use an existing template.
77 if ($Debconf::Db::templates->exists($template) and
78 $Debconf::Db::templates->owners($template)) {
79 # If a question matching this template already exists in
80 # the db, add the owner to it; otherwise, create one. This
81 # handles shared owner questions.
82 if ($Debconf::Db::config->exists($template)) {
83 my $q=Debconf::Question->get($template);
84 $q->addowner($owner, $type) if $q;
85 } else {
86 my $q=Debconf::Question->new($template, $owner, $type);
87 $q->template($template);
88 }
89
90 # See if the template claims to own any questions that
91 # cannot be found. If so, the db is corrupted; attempt to
92 # recover.
93 my @owners=$Debconf::Db::templates->owners($template);
94 foreach my $question (@owners) {
95 my $q=Debconf::Question->get($question);
96 if (! $q) {
97 warn sprintf(gettext("warning: possible database corruption. Will attempt to repair by adding back missing question %s."), $question);
98 my $newq=Debconf::Question->new($question, $owner, $type);
99 $newq->template($template);
100 }
101 }
102
103 $this = fields::new($this);
104 $this->{template}=$template;
105 return $template{$template}=$this;
106 }
107
108 # Really making a new template.
109 unless (ref $this) {
110 $this = fields::new($this);
111 }
112 $this->{template}=$template;
113
114 # Create a question in the db to go with it, unless
115 # one with the same name already exists. If one with the same name
116 # exists, it may be a shared question so we add the current owner
117 # to it.
118 if ($Debconf::Db::config->exists($template)) {
119 my $q=Debconf::Question->get($template);
120 $q->addowner($owner, $type) if $q;
121 }
122 else {
123 my $q=Debconf::Question->new($template, $owner, $type);
124 $q->template($template);
125 }
126
127 # This is what actually creates the template in the db.
128 return unless $Debconf::Db::templates->addowner($template, $template, $type);
129
130 $Debconf::Db::templates->setfield($template, 'type', $type);
131 return $template{$template}=$this;
132 }
133
134 =head2 get(templatename)
135
136 Get an existing template (it may be pulled out of the database, etc).
137
138 =cut
139
140 sub get {
141 my Debconf::Template $this=shift;
142 my $template=shift;
143 return $template{$template} if exists $template{$template};
144 if ($Debconf::Db::templates->exists($template)) {
145 $this = fields::new($this);
146 $this->{template}=$template;
147 return $template{$template}=$this;
148 }
149 return;
150 }
151
152 =head2 i18n
153
154 This class method controls whether internationalization is enabled for all
155 templates. Sometimes it may be necessary to get at the C values of fields,
156 bypassing internationalization. To enable this, set i18n to a false value.
157 This is only for when you explicitly want an untranslated version (which may
158 not be suitable for display), not merely for when a C locale is in use.
159
160 =cut
161
162 sub i18n {
163 my $class=shift;
164 $Debconf::Template::i18n=shift;
165 }
166
167 =head2 load
168
169 This class method reads a templates file, instantiates a template for each
170 item in it, and returns all the instantiated templates. Pass it the file to
171 load (or an already open FileHandle).
172
173 Any other parameters that are passed to this function will be passed on to
174 the template constructor when it is called.
175
176 =cut
177
178 sub load {
179 my $this=shift;
180 my $file=shift;
181
182 my @ret;
183 my $fh;
184
185 if (ref $file) {
186 $fh=$file;
187 }
188 else {
189 $fh=FileHandle->new($file) || die "$file: $!";
190 }
191 local $/="\n\n"; # read a template at a time.
192 while (<$fh>) {
193 # Parse the data into a hash structure.
194 my %data;
195
196 # Sets a field to a value in the hash, with sanity
197 # checking.
198 my $save = sub {
199 my $field=shift;
200 my $value=shift;
201 my $extended=shift;
202 my $file=shift;
203
204 # Make sure there are no blank lines at the end of
205 # the extended field, as that causes problems when
206 # stringifying and elsewhere, and is pointless
207 # anyway.
208 $extended=~s/\n+$//;
209
210 if ($field ne '') {
211 if (exists $data{$field}) {
212 die sprintf(gettext("Template #%s in %s has a duplicate field \"%s\" with new value \"%s\". Probably two templates are not properly separated by a lone newline.\n"), $., $file, $field, $value);
213 }
214 $data{$field}=$value;
215 $data{"extended_$field"}=$extended
216 if length $extended;
217 }
218 };
219
220 # Ignore any number of leading and trailing newlines.
221 s/^\n+//;
222 s/\n+$//;
223 my ($field, $value, $extended)=('', '', '');
224 foreach my $line (split "\n", $_) {
225 chomp $line;
226 if ($line=~/^([[email protected]]*):\s?(.*)/) {
227 # Beginning of new field. First, save the
228 # old one.
229 $save->($field, $value, $extended, $file);
230 $field=lc $1;
231 $value=$2;
232 $value=~s/\s*$//;
233 $extended='';
234 my $basefield=$field;
235 $basefield=~s/-.+$//;
236 if (! $known_field{$basefield}) {
237 warn sprintf(gettext("Unknown template field '%s', in stanza #%s of %s\n"), $field, $., $file);
238 }
239 }
240 elsif ($line=~/^\s\.$/) {
241 # Continuation of field that contains only
242 # a blank line.
243 $extended.="\n\n";
244 }
245 elsif ($line=~/^\s(\s+.*)/) {
246 # Continuation of a field, with a doubly
247 # indented bit that should not be wrapped.
248 my $bit=$1;
249 $bit=~s/\s*$//;
250 $extended.="\n" if length $extended &&
251 $extended !~ /[\n ]$/;
252 $extended.=$bit."\n";
253 }
254 elsif ($line=~/^\s(.*)/) {
255 # Continuation of field.
256 my $bit=$1;
257 $bit=~s/\s*$//;
258 $extended.=' ' if length $extended &&
259 $extended !~ /[\n ]$/;
260 $extended.=$bit;
261 }
262 else {
263 die sprintf(gettext("Template parse error near `%s', in stanza #%s of %s\n"), $line, $., $file);
264 }
265 }
266 $save->($field, $value, $extended, $file);
267
268 # Sanity checks.
269 die sprintf(gettext("Template #%s in %s does not contain a 'Template:' line\n"), $., $file)
270 unless $data{template};
271
272 # Create and populate template from hash.
273 my $template=$this->new($data{template}, @_, $data{type});
274 # Ensure template is empty, then fill with new data.
275 $template->clearall;
276 foreach my $key (keys %data) {
277 next if $key eq 'template';
278 $template->$key($data{$key});
279 }
280 push @ret, $template;
281 }
282
283 return @ret;
284 }
285
286 =head1 METHODS
287
288 =head2 template
289
290 Returns the name of the template.
291
292 =cut
293
294 sub template {
295 my $this=shift;
296
297 return $this->{template};
298 }
299
300 =head2 fields
301
302 Returns a list of all fields that are present in the object.
303
304 =cut
305
306 sub fields {
307 my $this=shift;
308
309 return $Debconf::Db::templates->fields($this->{template});
310 }
311
312 =head2 clearall
313
314 Clears all the fields of the object.
315
316 =cut
317
318 sub clearall {
319 my $this=shift;
320
321 foreach my $field ($this->fields) {
322 $Debconf::Db::templates->removefield($this->{template}, $field);
323 }
324 }
325
326 =head2 stringify
327
328 This may be called as either a class method (in which case it takes a list
329 of templates), or as a normal method (which makes it act on only the one
330 object). It converts the template objects back into template file format,
331 and returns a string containing the data.
332
333 =cut
334
335 sub stringify {
336 my $this=shift;
337
338 my @templatestrings;
339 foreach (ref $this ? $this : @_) {
340 my $data='';
341 # Order the fields with Template and Type the top and the
342 # rest sorted.
343 foreach my $key ('template', 'type',
344 (grep { $_ ne 'template' && $_ ne 'type'} sort $_->fields)) {
345 next if $key=~/^extended_/;
346 # Support special case of -ll_LL items.
347 if ($key =~ m/-[a-z]{2}_[a-z]{2}(@[^_@.])?(-fuzzy)?$/) {
348 my $casekey=$key;
349 $casekey=~s/([a-z]{2})(@[^_@.]|)(-fuzzy|)$/uc($1).$2.$3/eg;
350 $data.=ucfirst($casekey).": ".$_->$key."\n";
351 }
352 else {
353 $data.=ucfirst($key).": ".$_->$key."\n";
354 }
355 my $e="extended_$key";
356 my $ext=$_->$e;
357 if (defined $ext) {
358 # Add extended field.
359 $Text::Wrap::break = qr/\n|\s(?=\S)/;
360 my $extended=expand(wrap(' ', ' ', $ext));
361 # The word wrapper sometimes outputs multiple
362 # " \n" lines, so collapse those into one.
363 $extended=~s/(\n )+\n/\n .\n/g;
364 $data.=$extended."\n" if length $extended;
365 }
366 }
367 push @templatestrings, $data;
368 }
369 return join("\n", @templatestrings);
370 }
371
372 =head2 AUTOLOAD
373
374 Creates and calls accessor methods to handle fields.
375 This supports internationalization.
376 It pulls data out of the backend db.
377
378 =cut
379
380 # Helpers for _getlocalelist
381 sub _addterritory {
382 my $locale=shift;
383 my $territory=shift;
384 $locale=~s/^([^_@.]+)/$1$territory/;
385 return $locale;
386 }
387 sub _addcharset {
388 my $locale=shift;
389 my $charset=shift;
390 $locale=~s/^([^@.]+)/$1$charset/;
391 return $locale;
392 }
393 # Returns the list of locale names as searched (with slight changes) by GNU libc
394 sub _getlocalelist {
395 my $locale=shift;
396 $locale=~s/(@[^.]+)//;
397 my $modifier=$1;
398 my ($lang, $territory, $charset)=($locale=~m/^
399 ([^_@.]+) # Language
400 (_[^_@.]+)? # Territory
401 (\..+)? # Charset
402 /x);
403 my (@ret) = ($lang);
404 @ret = map { ($_.$modifier, $_) } @ret if defined $modifier;
405 @ret = map { (_addterritory($_,$territory), $_) } @ret if defined $territory;
406 @ret = map { (_addcharset($_,$charset), $_) } @ret if defined $charset;
407 return @ret;
408 }
409
410 # Helper for AUTOLOAD; calculate the current locale, with aliases expanded,
411 # and normalized. May also generate a fallback. Returns both.
412 sub _getlangs {
413 my $language=setlocale(LC_MESSAGES);
414 my @langs = ();
415 # LANGUAGE has a higher precedence than LC_MESSAGES
416 if (exists $ENV{LANGUAGE} && $ENV{LANGUAGE} ne '') {
417 foreach (split(/:/, $ENV{LANGUAGE})) {
418 push (@langs, _getlocalelist($_));
419 }
420 }
421 return @langs, _getlocalelist($language);
422 }
423
424 # Lower-case language name because fields are stored in lower case.
425 my @langs=map { lc $_ } _getlangs();
426
427 sub AUTOLOAD {
428 (my $field = our $AUTOLOAD) =~ s/.*://;
429 no strict 'refs';
430 *$AUTOLOAD = sub {
431 my $this=shift;
432 if (@_) {
433 return $Debconf::Db::templates->setfield($this->{template}, $field, shift);
434 }
435
436 my $ret;
437 my $want_i18n = $Debconf::Template::i18n && Debconf::Config->c_values ne 'true';
438
439 # Check to see if i18n and/or charset encoding should
440 # be used.
441 if ($want_i18n && @langs) {
442 foreach my $lang (@langs) {
443 # Avoid displaying Choices-C values
444 $lang = 'en' if $lang eq 'c';
445
446 # First check for a field that matches the
447 # language and the encoding. No charset
448 # conversion is needed. This also takes care
449 # of the old case where encoding is
450 # not specified.
451 $ret=$Debconf::Db::templates->getfield($this->{template}, $field.'-'.$lang);
452 return $ret if defined $ret;
453
454 # Failing that, look for a field that matches
455 # the language, and do charset conversion.
456 if ($Debconf::Encoding::charmap) {
457 foreach my $f ($Debconf::Db::templates->fields($this->{template})) {
458 if ($f =~ /^\Q$field-$lang\E\.(.+)/) {
459 my $encoding = $1;
460 $ret = Debconf::Encoding::convert($encoding, $Debconf::Db::templates->getfield($this->{template}, lc($f)));
461 return $ret if defined $ret;
462 }
463 }
464 }
465
466 # For en, force the default template if no
467 # language-specific template was found,
468 # since English text is usually found in a
469 # plain field rather than something like
470 # Choices-en.UTF-8. This allows you to
471 # override other locale variables for a
472 # different language with LANGUAGE=en.
473 last if $lang eq 'en';
474 }
475 } elsif (not $want_i18n and $field !~ /-c$/i) {
476 # If i18n is turned off, try *-C first.
477 $ret=$Debconf::Db::templates->getfield($this->{template}, $field.'-c');
478 return $ret if defined $ret;
479 }
480
481 $ret=$Debconf::Db::templates->getfield($this->{template}, $field);
482 return $ret if defined $ret;
483
484 # If the user asked for a language-specific field, fall
485 # back to the unadorned field. This allows *-C to be
486 # used to force untranslated data, and *-* to fall back
487 # to untranslated data if no translation is available.
488 if ($field =~ /-/) {
489 (my $plainfield = $field) =~ s/-.*//;
490 $ret=$Debconf::Db::templates->getfield($this->{template}, $plainfield);
491 return $ret if defined $ret;
492 return '';
493 }
494
495 return '';
496 };
497 goto &$AUTOLOAD;
498 }
499
500 # Do nothing.
501 sub DESTROY {}
502
503 # Overload stringification so metaget of a question's template field
504 # returns the template name.
505 use overload
506 '""' => sub {
507 my $template=shift;
508 $template->template;
509 };
510
511 =head1 AUTHOR
512
513 Joey Hess <[email protected]>
514
515 =cut
516
517 1