Import Filter Definition

An import filter is Active Contents: it is defined as a Perl function that a document author can refer to. The definition of this function can be stored in any part of the processed document source that is processed before a use of the filter. Typically one embeds it at the beginning of the document, or better yet store it in a definition file that can be smartly included.

Let's say we use embedding. Here is an example definition:

    \EMBED{lang=perl}
  
       # define an import filter
       sub format2pp
        {
         ...
        }
  
       # define a short filter alias
       *f2pp=\&format2pp;
  
    \END_EMBED

This code defines a filter format2pp(), with an alias f2pp(). The alias is just there to make use handy for document authors, to allow quicker typing.

What are these three dots? This, of course, is the code that transforms the source format into valid PerlPoint. This can be code of any complexity, it has more to do with the formats than with PerlPoint. The only conventions are that it gets the content of the included file in @main::_ifilterText and the name of the file in $main::_ifilterFile 3, and that it emits the produced PerlPoint as one string.

Here is an example implementation showing the interfaces, with the transformation performed by a function transform that is defined elsewhere.

    \EMBED{lang=perl}
  
       # define an import filter
       sub format2pp
        {
         # get source and sourcefile name
         my ($source, $sourcefile)=(
                                    join('',
                                         "nnn",
                                         @main::_ifilterText
                                        ),
                                    $main::_ifilterFile
                                   );
  
         # transform the source into PerlPoint
         my $perlpoint=transform();
  
         # provide the PerlPoint produced
         $perlpoint;
        }
  
       # define a short filter alias
       *f2pp=\&format2pp;
  
    \END_EMBED

That's the complete definition interface. Again, this defininition is required only once, I suggest to store it in a file and to include it via \INCLUDE, with smart=1.

The next chapter shows how users can make use of the filter.

3: Why global variables when we call a function? Well, the answer is that when the interface was designed it should be as simple as possible for users, which should not have to deal with parameters - they just use the filter name in a tag option. In theory, this option could be a complete function call, but this would require Perl knowledge and knowledge about variables which hold the content and name, so finally we would have no better situation but a less transparent interface.