| 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 |