SL/DBUpgrade2.pm

   1 package SL::DBUpgrade2;
   2
   3 use IO::File;
   4 use List::MoreUtils qw(any);
   5
   6 use SL::Common;
   7 use SL::DBUpgrade2::Base;
   8 use SL::DBUtils;
   9 use SL::Iconv;
  10
  11 use strict;
  12
  13 sub new {
  14   my $package = shift;
  15
  16   return bless({}, $package)->init(@_);
  17 }
  18
  19 sub init {
  20   my ($self, %params) = @_;
  21
  22   if ($params{auth}) {
  23     $params{path_suffix} = "-auth";
  24     $params{schema}      = "auth.";
  25   }
  26
  27   $params{path_suffix} ||= '';
  28   $params{schema}      ||= '';
  29   $params{path}          = "sql/" . $params{dbdriver} . "-upgrade2" . $params{path_suffix};
  30
  31   map { $self->{$_} = $params{$_} } keys %params;
  32
  33   return $self;
  34 }
  35
  36 sub path {
  37   $_[0]{path};
  38 }
  39
  40 sub parse_dbupdate_controls {
  41   $::lxdebug->enter_sub();
  42
  43   my ($self) = @_;
  44
  45   my $form   = $self->{form};
  46   my $locale = $::locale;
  47
  48   local *IN;
  49   my %all_controls;
  50
  51   my $path = $self->path;
  52
  53   foreach my $file_name (<$path/*.sql>, <$path/*.pl>) {
  54     next unless (open(IN, $file_name));
  55
  56     my $file = $file_name;
  57     $file =~ s|.*/||;
  58
  59     my $control = {
  60       "priority" => 1000,
  61       "depends"  => [],
  62     };
  63
  64     while (<IN>) {
  65       chomp();
  66       next unless (/^(--|\#)\s*\@/);
  67       s/^(--|\#)\s*\@//;
  68       s/\s*$//;
  69       next if ($_ eq "");
  70
  71       my @fields = split(/\s*:\s*/, $_, 2);
  72       next unless (scalar(@fields) == 2);
  73
  74       if ($fields[0] eq "depends") {
  75         push(@{$control->{"depends"}}, split(/\s+/, $fields[1]));
  76       } else {
  77         $control->{$fields[0]} = $fields[1];
  78       }
  79     }
  80
  81     next if ($control->{ignore});
  82
  83     $control->{charset} = 'UTF-8' if $file =~ m/\.pl$/;
  84     $control->{charset} = $control->{charset} || $control->{encoding} || Common::DEFAULT_CHARSET;
  85
  86     if (!$control->{"tag"}) {
  87       _control_error($form, $file_name, $locale->text("Missing 'tag' field.")) ;
  88     }
  89
  90     if ($control->{"tag"} =~ /[^a-zA-Z0-9_\(\)\-]/) {
  91       _control_error($form, $file_name, $locale->text("The 'tag' field must only consist of alphanumeric characters or the carachters - _ ( )"))
  92     }
  93
  94     if (defined($all_controls{$control->{"tag"}})) {
  95       _control_error($form, $file_name, sprintf($locale->text("More than one control file with the tag '%s' exist."), $control->{"tag"}))
  96     }
  97
  98     if (!$control->{"description"}) {
  99       _control_error($form, $file_name, sprintf($locale->text("Missing 'description' field."))) ;
 100     }
 101
 102     $control->{"priority"}  *= 1;
 103     $control->{"priority"} ||= 1000;
 104     $control->{"file"}       = $file;
 105
 106     delete @{$control}{qw(depth applied)};
 107
 108     $all_controls{$control->{"tag"}} = $control;
 109
 110     close(IN);
 111   }
 112
 113   foreach my $control (values(%all_controls)) {
 114     foreach my $dependency (@{$control->{"depends"}}) {
 115       _control_error($form, $control->{"file"}, sprintf($locale->text("Unknown dependency '%s'."), $dependency)) if (!defined($all_controls{$dependency}));
 116     }
 117
 118     map({ $_->{"loop"} = 0; } values(%all_controls));
 119     _check_for_loops($form, $control->{"file"}, \%all_controls, $control->{"tag"});
 120   }
 121
 122   map({ _dbupdate2_calculate_depth(\%all_controls, $_->{"tag"}) }
 123       values(%all_controls));
 124
 125   $self->{all_controls} = \%all_controls;
 126
 127   $::lxdebug->leave_sub();
 128
 129   return $self;
 130 }
 131
 132 sub process_query {
 133   $::lxdebug->enter_sub();
 134
 135   my ($self, $dbh, $filename, $version_or_control, $db_charset) = @_;
 136
 137   my $form  = $self->{form};
 138   my $fh    = IO::File->new($filename, "r") or $form->error("$filename : $!\n");
 139   my $query = "";
 140   my $sth;
 141   my @quote_chars;
 142
 143   my $file_charset = Common::DEFAULT_CHARSET;
 144   while (<$fh>) {
 145     last if !/^--/;
 146     next if !/^--\s*\@(?:charset|encoding):\s*(.+)/;
 147     $file_charset = $1;
 148     last;
 149   }
 150   $fh->seek(0, SEEK_SET);
 151
 152   $db_charset ||= Common::DEFAULT_CHARSET;
 153
 154   $dbh->begin_work();
 155
 156   while (<$fh>) {
 157     $_ = SL::Iconv::convert($file_charset, $db_charset, $_);
 158
 159     # Remove DOS and Unix style line endings.
 160     chomp;
 161
 162     # remove comments
 163     s/--.*$//;
 164
 165     for (my $i = 0; $i < length($_); $i++) {
 166       my $char = substr($_, $i, 1);
 167
 168       # Are we inside a string?
 169       if (@quote_chars) {
 170         if ($char eq $quote_chars[-1]) {
 171           pop(@quote_chars);
 172         } elsif (length $quote_chars[-1] > 1
 173              &&  substr($_, $i, length $quote_chars[-1]) eq $quote_chars[-1]) {
 174           $i   += length($quote_chars[-1]) - 1;
 175           $char = $quote_chars[-1];
 176           pop(@quote_chars);
 177         }
 178         $query .= $char;
 179
 180       } else {
 181         my ($tag, $tag_end);
 182         if (($char eq "'") || ($char eq "\"")) {
 183           push(@quote_chars, $char);
 184
 185         } elsif ($char eq '$'                                            # start of dollar quoting
 186              && ($tag_end  = index($_, '$', $i + 1)) > -1                # ends on same line
 187              && (do { $tag = substr($_, $i + 1, $tag_end - $i - 1); 1 }) # extract tag
 188              &&  $tag      =~ /^ (?= [A-Za-z_] [A-Za-z0-9_]* | ) $/x) {  # tag is identifier
 189           push @quote_chars, $char = '$' . $tag . '$';
 190           $i = $tag_end;
 191         } elsif ($char eq ";") {
 192
 193           # Query is complete. Send it.
 194
 195           $sth = $dbh->prepare($query);
 196           if (!$sth->execute()) {
 197             my $errstr = $dbh->errstr;
 198             $sth->finish();
 199             $dbh->rollback();
 200             $form->dberror("The database update/creation did not succeed. " .
 201                            "The file ${filename} containing the following " .
 202                            "query failed:<br>${query}<br>" .
 203                            "The error message was: ${errstr}<br>" .
 204                            "All changes in that file have been reverted.");
 205           }
 206           $sth->finish();
 207
 208           $char  = "";
 209           $query = "";
 210         }
 211
 212         $query .= $char;
 213       }
 214     }
 215
 216     # Insert a space at the end of each line so that queries split
 217     # over multiple lines work properly.
 218     if ($query ne '') {
 219       $query .= @quote_chars ? "\n" : ' ';
 220     }
 221   }
 222
 223   if (ref($version_or_control) eq "HASH") {
 224     $dbh->do("INSERT INTO " . $self->{schema} . "schema_info (tag, login) VALUES (" . $dbh->quote($version_or_control->{"tag"}) . ", " . $dbh->quote($form->{"login"}) . ")");
 225   } elsif ($version_or_control) {
 226     $dbh->do("UPDATE defaults SET version = " . $dbh->quote($version_or_control));
 227   }
 228   $dbh->commit();
 229
 230   $fh->close();
 231
 232   $::lxdebug->leave_sub();
 233 }
 234
 235 # Process a Perl script which updates the database.
 236 # If the script returns 1 then the update was successful.
 237 # Return code "2" means "needs more interaction; remove
 238 # users/nologin and end current request".
 239 # All other return codes are fatal errors.
 240 sub process_perl_script {
 241   $::lxdebug->enter_sub();
 242
 243   my ($self, $dbh, $filename, $version_or_control, $db_charset) = @_;
 244
 245   $dbh->begin_work;
 246
 247   # setup dbup_ export vars & run script
 248   my %dbup_myconfig = map { ($_ => $::form->{$_}) } qw(dbname dbuser dbpasswd dbhost dbport dbconnect);
 249   my $result        = SL::DBUpgrade2::Base::execute_script(
 250     file_name => $filename,
 251     tag       => $version_or_control->{tag},
 252     dbh       => $dbh,
 253     myconfig  => \%dbup_myconfig,
 254   );
 255
 256   if (1 != ($result // 1)) {
 257     $dbh->rollback();
 258   }
 259
 260   if (!defined($result)) {
 261     print $::form->parse_html_template("dbupgrade/error", { file  => $filename, error => $@ });
 262     ::end_of_request();
 263   } elsif (1 != $result) {
 264     unlink("users/nologin") if (2 == $result);
 265     ::end_of_request();
 266   }
 267
 268   if (ref($version_or_control) eq "HASH") {
 269     $dbh->do("INSERT INTO " . $self->{schema} . "schema_info (tag, login) VALUES (" . $dbh->quote($version_or_control->{tag}) . ", " . $dbh->quote($::form->{login}) . ")");
 270   } elsif ($version_or_control) {
 271     $dbh->do("UPDATE defaults SET version = " . $dbh->quote($version_or_control));
 272   }
 273   $dbh->commit();
 274
 275   $::lxdebug->leave_sub();
 276 }
 277
 278 sub process_file {
 279   my ($self, $dbh, $filename, $version_or_control, $db_charset) = @_;
 280
 281   if ($filename =~ m/sql$/) {
 282     $self->process_query($dbh, $filename, $version_or_control, $db_charset);
 283   } else {
 284     $self->process_perl_script($dbh, $filename, $version_or_control, $db_charset);
 285   }
 286 }
 287
 288 sub update_available {
 289   my ($self, $cur_version) = @_;
 290
 291   local *SQLDIR;
 292
 293   my $dbdriver = $self->{dbdriver};
 294   opendir SQLDIR, "sql/${dbdriver}-upgrade" || error("", "sql/${dbdriver}-upgrade: $!");
 295   my @upgradescripts = grep /${dbdriver}-upgrade-\Q$cur_version\E.*\.(sql|pl)$/, readdir SQLDIR;
 296   closedir SQLDIR;
 297
 298   return ($#upgradescripts > -1);
 299 }
 300
 301 sub update2_available {
 302   $::lxdebug->enter_sub();
 303
 304   my ($self, $dbh) = @_;
 305
 306   map { $_->{applied} = 0; } values %{ $self->{all_controls} };
 307
 308   my $sth = $dbh->prepare(qq|SELECT tag FROM | . $self->{schema} . qq|schema_info|);
 309   if ($sth->execute) {
 310     while (my ($tag) = $sth->fetchrow_array) {
 311       $self->{all_controls}->{$tag}->{applied} = 1 if defined $self->{all_controls}->{$tag};
 312     }
 313   }
 314   $sth->finish();
 315
 316   my $needs_update = any { !$_->{applied} } values %{ $self->{all_controls} };
 317
 318   $::lxdebug->leave_sub();
 319
 320   return $needs_update;
 321 }
 322
 323 sub unapplied_upgrade_scripts {
 324   my ($self, $dbh) = @_;
 325
 326   my @all_scripts = map { $_->{applied} = 0; $_ } $self->sort_dbupdate_controls;
 327
 328   my $query = qq|SELECT tag FROM | . $self->{schema} . qq|schema_info|;
 329   my $sth   = $dbh->prepare($query);
 330   $sth->execute || $self->{form}->dberror($query);
 331   while (my ($tag) = $sth->fetchrow_array()) {
 332     $self->{all_controls}->{$tag}->{applied} = 1 if defined $self->{all_controls}->{$tag};
 333   }
 334   $sth->finish;
 335
 336   return grep { !$_->{applied} } @all_scripts;
 337 }
 338
 339 sub apply_admin_dbupgrade_scripts {
 340   my ($self, $called_from_admin) = @_;
 341
 342   return 0 if !$self->{auth};
 343
 344   my $dbh               = $::auth->dbconnect;
 345   my @unapplied_scripts = $self->unapplied_upgrade_scripts($dbh);
 346
 347   return 0 if !@unapplied_scripts;
 348
 349   my $db_charset           = $::lx_office_conf{system}->{dbcharset} || Common::DEFAULT_CHARSET;
 350   $self->{form}->{login} ||= 'admin';
 351
 352   map { $_->{description} = SL::Iconv::convert($_->{charset}, $db_charset, $_->{description}) } values %{ $self->{all_controls} };
 353
 354   if ($called_from_admin) {
 355     $self->{form}->{title} = $::locale->text('Dataset upgrade');
 356     $self->{form}->header;
 357   }
 358
 359   print $self->{form}->parse_html_template("dbupgrade/header", { dbname => $::auth->{DB_config}->{db} });
 360
 361   foreach my $control (@unapplied_scripts) {
 362     $::lxdebug->message(LXDebug->DEBUG2(), "Applying Update $control->{file}");
 363     print $self->{form}->parse_html_template("dbupgrade/upgrade_message2", $control);
 364
 365     $self->process_file($dbh, "sql/$self->{dbdriver}-upgrade2-auth/$control->{file}", $control, $db_charset);
 366   }
 367
 368   print $self->{form}->parse_html_template("dbupgrade/footer", { is_admin => 1 }) if $called_from_admin;
 369
 370   return 1;
 371 }
 372
 373 sub _check_for_loops {
 374   my ($form, $file_name, $controls, $tag, @path) = @_;
 375
 376   push(@path, $tag);
 377
 378   my $ctrl = $controls->{$tag};
 379
 380   if ($ctrl->{"loop"} == 1) {
 381     # Not done yet.
 382     _control_error($form, $file_name, $::locale->text("Dependency loop detected:") . " " . join(" -> ", @path))
 383
 384   } elsif ($ctrl->{"loop"} == 0) {
 385     # Not checked yet.
 386     $ctrl->{"loop"} = 1;
 387     map({ _check_for_loops($form, $file_name, $controls, $_, @path); } @{ $ctrl->{"depends"} });
 388     $ctrl->{"loop"} = 2;
 389   }
 390 }
 391
 392 sub _control_error {
 393   my ($form, $file_name, $message) = @_;
 394
 395   $form = $::form;
 396   my $locale = $::locale;
 397
 398   $form->error(sprintf($locale->text("Error in database control file '%s': %s"), $file_name, $message));
 399 }
 400
 401 sub _dbupdate2_calculate_depth {
 402   $::lxdebug->enter_sub(2);
 403
 404   my ($tree, $tag) = @_;
 405
 406   my $node = $tree->{$tag};
 407
 408   return $::lxdebug->leave_sub(2) if (defined($node->{"depth"}));
 409
 410   my $max_depth = 0;
 411
 412   foreach $tag (@{$node->{"depends"}}) {
 413     _dbupdate2_calculate_depth($tree, $tag);
 414     my $value = $tree->{$tag}->{"depth"};
 415     $max_depth = $value if ($value > $max_depth);
 416   }
 417
 418   $node->{"depth"} = $max_depth + 1;
 419
 420   $::lxdebug->leave_sub(2);
 421 }
 422
 423 sub sort_dbupdate_controls {
 424   my $self = shift;
 425
 426   $self->parse_dbupdate_controls unless $self->{all_controls};
 427
 428   return sort { ($a->{depth} <=> $b->{depth}) || ($a->{priority} <=> $b->{priority}) || ($a->{tag} cmp $b->{tag}) } values %{ $self->{all_controls} };
 429 }
 430
 431 1;
 432 __END__
 433
 434 =pod
 435
 436 =encoding utf8
 437
 438 =head1 NAME
 439
 440 SL::DBUpgrade2 - Parse database upgrade files stored in
 441 C<sql/Pg-upgrade2> and C<sql/Pg-upgrade2-auth> (and also in
 442 C<SQL/Pg-upgrade>)
 443
 444 =head1 SYNOPSIS
 445
 446   use SL::User;
 447   use SL::DBUpgrade2;
 448
 449   # Apply outstanding updates to the authentication database
 450   my $scripts = SL::DBUpgrade2->new(
 451     form     => $::form,
 452     dbdriver => 'Pg',
 453     auth     => 1
 454   );
 455   $scripts->apply_admin_dbupgrade_scripts(1);
 456
 457   # Apply updates to a user database
 458   my $scripts = SL::DBUpgrade2->new(
 459     form     => $::form,
 460     dbdriver => $::form->{dbdriver},
 461     auth     => 1
 462   );
 463   User->dbupdate2($form, $scripts->parse_dbupdate_controls);
 464
 465 =head1 OVERVIEW
 466
 467 Database upgrade files are used to upgrade the database structure and
 468 content of both the authentication database and the user
 469 databases. They're applied when a user logs in. As long as the
 470 authentication database is not up to date users cannot log in in
 471 general, and the admin has to log in first in order to get his
 472 database updated.
 473
 474 Database scripts form a tree by specifying which upgrade file depends
 475 on which other upgrade file. This means that such files are always
 476 applied in a well-defined order.
 477
 478 Each script is run in a separate transaction. If a script fails the
 479 current transaction is rolled back and the whole upgrade process is
 480 stopped. The user/admin is required to fix the issue manually.
 481
 482 A list of applied upgrade scripts is maintained in a table called
 483 C<schema_info> for the user database and C<auth.schema_info>) for the
 484 authentication database. They contain the tags, the login name of the
 485 user having applied the script and the timestamp when the script was
 486 applied.
 487
 488 Database upgrade files come in two flavours: SQL files and Perl
 489 files. For both there are control fields that determine the order in
 490 which they're executed, what charset the scripts are written in
 491 etc. The control fields are tag/value pairs contained in comments.
 492
 493 =head1 OLD UPGRADE FILES
 494
 495 The files in C<sql/Pg-upgrade> are so old that I don't bother
 496 documenting them. They're handled by this class, too, but new files
 497 are only created as C<Pg-upgrade2> files.
 498
 499 =head1 CONTROL FIELDS
 500
 501 =head2 SYNTAX
 502
 503 Control fields for Perl files:
 504
 505   # @tag1: value1
 506   # @tag2: some more values
 507   sub do_stuff {
 508   }
 509   1;
 510
 511 Control fields for SQL files:
 512
 513   -- @tag1: value1
 514   -- @tag2: some more values
 515   ALTER TABLE ...;
 516
 517 =head2 TAGS AND THEIR MEANING
 518
 519 The following tags are recognized:
 520
 521 =over 4
 522
 523 =item tag
 524
 525 The name for this file. The C<tag> is also used for dependency
 526 resolution (see C<depends>).
 527
 528 This is mandatory.
 529
 530 =item description
 531
 532 A description presented to the user when the update is applied.
 533
 534 This is mandatory.
 535
 536 =item depends
 537
 538 A space-separated list of tags of scripts this particular script
 539 depends on. All other upgrades listed in C<depends> will be applied
 540 before the current one is applied.
 541
 542 =item charset
 543 =item encoding
 544
 545 The charset this file uses. Defaults to C<ISO-8859-15> if
 546 missing. Both terms are recognized.
 547
 548 =item priority
 549
 550 Ordering the scripts by their dependencies alone produces a lot of
 551 groups of scripts that could be applied at the same time (e.g. if both
 552 B and C depend only on A then B could be applied before C or the other
 553 way around). This field determines the order inside such a
 554 group. Scripts with lower priority fields are executed before scripts
 555 with higher priority fields.
 556
 557 If two scripts have equal priorities then their tag name decides.
 558
 559 The priority defaults to 1000.
 560
 561 =back
 562
 563 =head1 FUNCTIONS
 564
 565 =over 4
 566
 567 =item C<apply_admin_dbupgrade_scripts $called_from_admin>
 568
 569 Applies all unapplied upgrade files to the authentication/admin
 570 database. The parameter C<$called_from_admin> should be truish if the
 571 function is called from the web interface and falsish if it's called
 572 from e.g. a command line script like C<scripts/dbupgrade2_tool.pl>.
 573
 574 =item C<init %params>
 575
 576 Initializes the object. Is called directly from L<new> and should not
 577 be called again.
 578
 579 =item C<new %params>
 580
 581 Creates a new object. Possible parameters are:
 582
 583 =over 4
 584
 585 =item path
 586
 587 Path to the upgrade files to parse. Required.
 588
 589 =item form
 590
 591 C<SL::Form> object to use. Required.
 592
 593 =item dbdriver
 594
 595 Name of the database driver. Currently only C<Pg> for PostgreSQL is
 596 supported.
 597
 598 =item auth
 599
 600 Optional parameter defaulting to 0. If trueish then the scripts read
 601 are the ones applying to the authentication database.
 602
 603 =back
 604
 605 =item C<parse_dbupdate_controls>
 606
 607 Parses all files located in C<path> (see L<new>), ananlyzes their
 608 control fields, builds the tree, and signals errors if control fields
 609 are missing/wrong (e.g. a tag name listed in C<depends> is not
 610 found). Sets C<$Self-&gt;{all_controls}> to the list of database
 611 scripts.
 612
 613 =item C<process_file $dbh, $filename, $version_or_control, $db_charset>
 614
 615 Applies a single database upgrade file. Calls L<process_perl_script>
 616 for Perl update files and C<process_query> for SQL update
 617 files. Requires an open database handle(C<$dbh>), the file name
 618 (C<$filename>), a hash structure of the file's control fields as
 619 produced by L<parse_dbupdate_controls> (C<$version_or_control>) and
 620 the database charset (for on-the-fly charset recoding of the script if
 621 required, C<$db_charset>).
 622
 623 Returns the result of the actual function called.
 624
 625 =item C<process_perl_script $dbh, $filename, $version_or_control, $db_charset>
 626
 627 Applies a single Perl database upgrade file. Requires an open database
 628 handle(C<$dbh>), the file name (C<$filename>), a hash structure of the
 629 file's control fields as produced by L<parse_dbupdate_controls>
 630 (C<$version_or_control>) and the database charset (for on-the-fly
 631 charset recoding of the script if required, C<$db_charset>).
 632
 633 Perl scripts are executed via L<eval>. If L<eval> returns falsish then
 634 an error is expected. There are two special return values: If the
 635 script returns C<1> then the update was successful. Return code C<2>
 636 means "needs more interaction from the user; remove users/nologin and
 637 end current upgrade process". All other return codes are fatal errors.
 638
 639 Inside the Perl script several local variables exist that can be used:
 640
 641 =over 4
 642
 643 =item $dbup_locale
 644
 645 A locale object for translating messages
 646
 647 =item $dbh
 648
 649 The database handle (inside a transaction).
 650
 651 =item $::form
 652
 653 The global C<SL::Form> object.
 654
 655 =back
 656
 657 A Perl script can actually implement queries that fail while
 658 continueing the process by handling the transaction itself, e.g. with
 659 the following function:
 660
 661   sub do_query {
 662     my ($query, $may_fail) = @_;
 663
 664     if (!$dbh->do($query)) {
 665       die($dbup_locale->text("Database update error:") . "<br>$msg<br>" . $DBI::errstr) unless $may_fail;
 666       $dbh->rollback();
 667       $dbh->begin_work();
 668     }
 669   }
 670
 671 =item C<process_query $dbh, $filename, $version_or_control, $db_charset>
 672
 673 Applies a single SQL database upgrade file. Requires an open database
 674 handle(C<$dbh>), the file name (C<$filename>), a hash structure of the
 675 ofile's control fields as produced by L<parse_dbupdate_controls>
 676 (C<$version_or_control>) and the database charset (for on-the-fly
 677 charset recoding of the script if required, C<$db_charset>).
 678
 679 =item C<sort_dbupdate_controls>
 680
 681 Sorts the database upgrade scripts according to their C<tag> and
 682 C<priority> control fields. Returns a list of their hash
 683 representations that can be applied in order.
 684
 685 =item C<unapplied_upgrade_scripts $dbh>
 686
 687 Returns a list if upgrade scripts (their internal hash representation)
 688 that haven't been applied to a database yet. C<$dbh> is an open handle
 689 to the database that is checked.
 690
 691 Requires that the scripts have been parsed.
 692
 693 =item C<update2_available $dbh>
 694
 695 Returns trueish if at least one upgrade script hasn't been applied to
 696 a database yet. C<$dbh> is an open handle to the database that is
 697 checked.
 698
 699 Requires that the scripts have been parsed.
 700
 701 =back
 702
 703 =head1 BUGS
 704
 705 Nothing here yet.
 706
 707 =head1 AUTHOR
 708
 709 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
 710
 711 =cut