You are using a browser which doesn't fully support Cascading Style Sheets. This site will look much better in a browser that supports web standards, but its content is accessible to any browser or Internet device.

Document parts produced on the fly

The typical PerlPoint document workflow is that one writes down a document and then converts it with perlpoint, to the format of his choice. In a sense, such a document is static, everything needs to be written down explicitly. But with Active Contents this picture changes, as now we get the chance to run arbitrary Perl code to produce the PerlPoint source, instead of writing it ourselves.

The key to this feature are the \EMBED and \INCLUDE tags. \EMBED allows to declare a special document section that is written not in PerlPoint, but in another language which is specified by a tag option. Usually this part is passed through to the backend unchanged, which allows to include snippets in the target format. But if the source language is Perl the behaviour changes. With embedded Perl, perlpoint runs this Perl code behind the scenes and treats its results as PerlPoint, which is then processed as usual in place of the original section. The \INCLUDE tag works the same way, except that it loads the Perl code from an external file.

Let's have a look at an example, which simply replies the current date in fancy colors.

    \EMBED{lang=perl}
  
    # load modules
    use POSIX qw(strftime);
  
    # supply the current date, in fancy colors
    strftime('\RED<%B> \GREEN<%d>, \BLUE<%Y>', localtime);
  
    \END_EMBED

The PerlPoint source produced by this section is something like "\RED<Thuesday> \GREEN<9>, \BLUE<2006>". Of course this example is simple, but if you know Perl you know you can do a lot of things this way. Data can be retrieved, extracted, mixed, shaked, or depend on several conditions before they are finally condensed into a PerlPoint form, and this means that the part of a document composed by embedded Perl is highly dynamic as the code is run when the source is processed.

The code can contain anything that is valid perl, except for the character sequence "\END_EMBED". A typical solution is to compose this sequence from two parts, e.g. with join: join('_', '\\END', 'EMBED').

With \INCLUDE, everything works similar except that the source is written to a plain Perl file, and then loaded via \INCLUDE:

    \INCLUDE{type=perl file="dateInColors.pl"}

As seen in the example for \EMBED, embedded sections are not enclosed into a tag, instead they are enclosed into \EMBED and \END_EMBED, which allows both to write the Perl code in as many lines (and empty lines) as necessary, and to embed it into a single paragraph. So, while the example above used several lines and produces a text paragraph, the following is valid as well and becomes a part of the paragraph it is embedded into:

    This paragraph was processed at
    \EMBED{lang=perl}use POSIX qw(strftime);
    strftime('\RED<%B> \GREEN<%d>, \BLUE<%Y>',
    localtime);\END_EMBED.

And this means that macros can be become dynamic, too:

    // define macro
    +DATE_IN_COLORS:\EMBED{lang=perl
                       use POSIX qw(strftime);
                       strftime('\RED<%B> \GREEN<%d>, \BLUE<%Y>', localtime)
                    \END_EMBED
  
    // use macro
    This paragraph was processed at \DATE_IN_COLORS.

Yes, such definitions quickly grow in size, and they do not make a PerlPoint source handier for readers and co-writers, especially if they are no programmers. But remember: you can always hide the definitions in central files and all that is to do to make these definitions available is to include them by a line like

    // load macro definitions
    \INCLUDE{type=pp src="macros.pp" smart=1}