Processing other formats

PerlPoint converters can process files in other formats. The simplest way to do this is to process a file entirely written in the other format.

Process files in other formats

To import an entire source file written in another format, simply precede the file name by IMPORT: (in capitals):

    > perlpoint ... IMPORT:example.format

With this call, PerlPoint tries to invoke a predefined filter for the format "FORMAT" (the capitalized file extension). By convention this filter needs to be installed in a module PerlPoint::Import::FORMAT, as function importFilter(). The API of this function is similar to those of user provided import filters, but the good thing is that several filter modules for common formats are available at CPAN. And, we bundle them with the binary distributions - all filters mentioned in this tutorial are bundled at the time of this writing. As a consequence, these filters are just available.

Using predefined filters when embedding and including

The predefined import filters can be used in documents as well. Embedding and including means to include source snippets in other languages into a PerlPoint source. The related tags are \EMBED and \INCLUDE.

To use predefined filters when embedding, all a document author has to do is to set the import flag.

     // import a snippet in another format
     \EMBED{import=format}
     ...
     \END_EMBED

This flag is supported by \INCLUDE as well:

     // include a file in another format
     \INCLUDE{import=format file="example"}

The two examples show that the import option accepts a string with the name of the source format. Like on the command line, the import filter is searched in a module PerlPoint::Import::FORMAT, with FORMAT being the capitalized value of the import option.

As an additional simplification, \INCLUDE also accepts numerical values for import. If the value is true, the extension of the included file is used as the name of the source format.

     // include a file in another format
     \INCLUDE{import=1 file="example.format"}

Please note that the language of the snippets (option lang for \EMBED, or type for \INCLUDE) is (implicitly) defined as pp, which causes the parser to treat the results as PerlPoint and to parse them. This fact is essential to get the filter results included into your document - depending on your filter options, other language settings would cause the parser to ignore the transformed snippets or to include them as they are.

User defined import filters

The most flexible way to transform other sources is by using user defined import filters. With this method, a filter is a piece of Perl code directly embedded into the document and wrapped into a function. The name of this function then can be used to transform an included file or an embedded part into PerlPoint, which afterwards is processed as usual. So, import filters provide a way of transparent on-the-fly-transformation from another format into PerlPoint.

Here is an example:

     // first we define the filter, in embedded Perl
     \EMBED{lang=perl}
  
       sub format2pp
        {
         // please see above for details
         // about the API interface
        }
  
     \END_EMBED
  
     // now we can use it to transform
     // embedded parts and included files
     \EMBED{ifilter=format2pp}
     ...
     \END_EMBED
  
     \INCLUDE{ifilter=format2pp file="example.format"}

When ifilter is used together with import, PerlPoint ignores import and runs the ifilter function.

Here is a list of formats that are supported by modules on CPAN, at the time of this writing:

• POD
• OpenOffice files (empty)