PerlPoint Applications

As PerlPoint sources can contain sections that are produced on the fly it is easy to produce a document with dynamic parts - parts that are constructed in the moment the source is processed to produce the final document.

If not only parts of the source but more or less the entire document is not fix but the result of a program call there are two possibilities. The traditional approach would be to write a program, let it generate a PerlPoint source, and finally to process that source with a PerlPoint generator. The second way is to embed the application code into a PerlPoint source and run a PerlPoint generator to process the source. During processing, the code will be executed and produces the intermediate PerlPoint that then is transformed into the final document. A document designed the second way is called a "PerlPoint application".

Well, "PerlPoint application" is kind of a principle name. There are no rules how many percent of a document source need to be dynamic to call it an "application". More or less it's a certain view to a document that illustrates the general way it works: a program is hidden in a document sourcefile and is run implicitly when the source is processed. The advantage over the traditional approach is that one does not need glue scripts or makefiles (that might not be portable) to first produce a static source and to process that source in a second step.

Here is a very simple example. The document source consists of a few static parts, but the main part is dynamic. Its simple task is to get a list of friends from a database and to produce a chapter for each of them.

    // a list of friends, with informations
    // retrieved from a database
  
    =Friends
  
    This list was generated from a database.
    Edit the database for better informations.
    Do not edit this source.
  
    \LOCALTOC
  
    \EMBED{lang=perl}
  
      # load modules
      use DBI;
      use DBD::...;
      use Local::Routines;   # databaseConnect() etc.
  
      # define variables
      my ($perlpoint)=('');
  
      # connect to the database
      my $dbh=databaseConnect;
  
      # retrieve data of all friends
      my $sql=<<EOQ;
  
        select friend_id,
               full_name,
               birthday,
               city,
               street
        from   friends
  
    EOQ
  
      # get friends
      my $friends=$dbh->selectall_hashref($sql, 'FRIEND_ID');
      die $DBI::errstr if $DBI::errstr;
  
      # traverse the list
      foreach my $friendId (keys %$friends)
       {
        # get a list of interests
        $sql=<<EOQ;
  
             select interest
             from interests where friend_id=$friendId
             order by interest
  
    EOQ
  
        # get interests
        my $interests=$dbh->selectall_arrayref($sql);
        die $DBI::errstr if $DBI::errstr;
  
        # now that we have all data we need we can
        # write a page
        $perlpoint.=<<EOT;
  
    ==$friends{$friendId}{FULL_NAME}
  
    $friends{$friendId}{FULL_NAME}, born $friends{$friendId}{BIRTHDAY}
    and living in $friends{$friendId}{CITY}, $friends{$friendId}{STREET},
    likes
  
    EOT
  
        # add a list of interests
        $perlpoint.="* $_->[0]\n\n" for @$interests;
       }
  
      # disconnect from database
      databaseDisconnect;
  
      # supply the PerlPoint source
      $perlpoint;
  
    \END_EMBED

PerlPointCD is an example of an existing real live application. It traverses subdirectories to collect documents for a conference CD (in various formats which are imported automatically), together with author informations, abstracts, bonus tracks and images. All these documents are organized in a PerlPoint source which finally is transformed into a sequence of XHTML pages and several download directories. It's used successfully for the CDs of the German Perl Workshop for years.