The parser call

And now, the parser can be called. Because it is implemented by a class, we first need to build an object, which is simple.

    # build parser
  
    my $parser=new PerlPoint::Parser;

The objects method run() invokes the parser to process all document sources. Various parameters control how this task is performed and need to be set according to the converter options. It should be sufficient to simply copy this call and to slightly adapt it.

    # call parser
  
    $parser->run(
                 stream          => \@streamData,
                 files           => \@ARGV,
  
                 filter          => 'perl|sdf|html',
  
                 safe            => exists $options{activeContents} ? $safe : undef,
  
                 activeBaseData  => {
                                     targetLanguage => 'SDF',
                                     userSettings   => {map {$_=>1} exists $options{set} ? @{$options{set}} : ()},
                                    },
  
                 predeclaredVars => {
                                     CONVERTER_NAME    => basename($0),
                                     CONVERTER_VERSION => do {no strict 'refs'; ${join('::', __PACKAGE__, 'VERSION')}},
                                    },
  
                 libpath         => exists $options{includelib} ? $options{includelib} : [],
  
                 docstreams2skip => exists $options{skipstream} ? $options{skipstream} : [],
  
                 docstreaming    => (exists $options{docstreaming} and ($options{docstreaming}==DSTREAM_HEADLINES or $options{docstreaming}==DSTREAM_IGNORE)) ? $options{docstreaming} : DSTREAM_DEFAULT,
  
                 vispro          => 1,
  
                 cache           =>   (exists $options{cache} ? CACHE_ON : CACHE_OFF)
                                    + (exists $options{cacheCleanup} ? CACHE_CLEANUP : 0),
  
                 display         =>   DISPLAY_ALL
                                    + (exists $options{noinfo} ? DISPLAY_NOINFO : 0)
                                    + (exists $options{nowarn} ? DISPLAY_NOWARN : 0),
  
                 trace           =>   TRACE_NOTHING
                                    + ((exists $options{trace} and $options{trace} &  1) ? TRACE_PARAGRAPHS : 0)
                                    + ((exists $options{trace} and $options{trace} &  2) ? TRACE_LEXER      : 0)
                                    + ((exists $options{trace} and $options{trace} &  4) ? TRACE_PARSER     : 0)
                                    + ((exists $options{trace} and $options{trace} &  8) ? TRACE_SEMANTIC   : 0)
                                    + ((exists $options{trace} and $options{trace} & 16) ? TRACE_ACTIVE     : 0),
                ) or exit(1);

So what happens here?

stream

passes a reference to an array which will be used to store the stream element in. It is suggested to pass an empty array (but currently new fields will be added, so existing entries will not be damaged).

files

passes an array of document source files to parse.

filter

declares which formats are allowed to be embedded or included. You can accept all formats which can be processed by the software which has to deal with the converter product, and "perl" to provide the full power of Active Contents. All formats not matching the filter will be ignored.

safe

pass the prepared variable $safe.

activeBaseData

sets up a hash reference which is made accessible to Active Contents as $main::PerlPoint. The keys targetLanguage and userSettings are provided by convention, but you may add whatever keys you need.

libpath

passes the library pathes a user specified via -includelib, see above for details. Please copy this code.

docstreams2skip

passes the names of document streams to skip which are specified via user option -skipstream, see above for details. Please copy this code.

docstreaming

specifies how document streams shall be handled. It is up to you which fashions of docstream handling your converter will provide. Nevertheless, two styles are supported directly by the parser (which makes them available in all converters), so please pass DSTREAM_HEADLINE and DSTREAM_IGNORE directly to the parser if they are specified by a user. DSTREAM_HEADLINES transforms stream entry points into headlines, while DSTREAM_IGNORE ignores all streams except the "main stream". In all other cases, please set the value of this parameter to DSTREAM_DEFAULT, which makes the parser supply all stream entry points in the intermediate data so your converter can deal with them itself. A final hint: for user convenience, your converter could allow to specify streaming modes by strings instead of by numbers. (And it is recommended to do so because the internal constants are subject to changes, but the user interface should be as stable as possible.) So please adapt this code appropriately.

vispro

if set to a true value, the parser will display runtime informations. Please copy this code.

cache

used to pass the cache settings. Please copy this code.

display

used to pass the display settings. Please copy this code.

trace

used to pass the trace settings. Please copy this code.

run() returns a true value if parsing was successful. It is recommended to evaluate this code and to stop processing in case of an error.

    # call parser
  
    $parser->run(...) or exit(1);