NAME
PerlPoint::Backend - frame class to transform PerlPoint::Parser output
VERSION
This manual describes version 0.07.
SYNOPSIS
# load the module:
use PerlPoint::Backend;
# build the backend
my ($backend)=new PerlPoint::Backend(name=>'synopsis');
# register handlers
$backend->register(DIRECTIVE_BLOCK, \&handleBlock);
$backend->register(DIRECTIVE_COMMENT, \&handleComment);
$backend->register(DIRECTIVE_DOCUMENT, \&handleDocument);
$backend->register(DIRECTIVE_HEADLINE, \&handleHeadline);
$backend->register(DIRECTIVE_POINT, \&handlePoint);
$backend->register(DIRECTIVE_SIMPLE, \&handleSimple);
$backend->register(DIRECTIVE_TAG, \&handleTag);
$backend->register(DIRECTIVE_TEXT, \&handleText);
$backend->register(DIRECTIVE_VERBATIM, \&handleVerbatim);
# finally run the backend
$backend->run(\@streamData);DESCRIPTION
After an ASCII text is parsed by an PerlPoint::Parser object, the original text is transformed into stream data hold in a Perl array. To process this intermediate stream further (mostly to generate output in a certain document description language), a program has to walk through the stream and to process its tokens.
Well, PerlPoint::Backend provides a class which encapsulates this walk in objects which deal with the stream, while the translator programmer is focussed on generating the final representation of the original text. This is done by registering handlers which will be called when their target objects are discovered in the intermediate stream.
METHODS
new()
The constructor builds and prepares a new backend object. You may have more than one object at a certain time, they work independently.
Parameters: All parameters except of the class parameter are named (pass them by hash).
- class
-
The class name.
- name
-
Because there can be more than exactly one backend object, your object should be named. This is not necessarily a need but helpful reading traces.
- trace
-
This parameter is optional. It is intended to activate trace code while the object methods run. You may pass any of the "TRACE_..." constants declared in PerlPoint::Constants, combined by addition as in the following example:
trace => TRACE_NOTHING+TRACE_BACKEND,In fact, only TRACE_NOTHING and TRACE_BACKEND take effect to backend objects.
If you omit this parameter or pass TRACE_NOTHING, no traces will be displayed.
- display
-
This parameter is optional. It controls the display of runtime messages like informations or warnings in all object methods. By default, all messages are displayed. You can suppress these informations partially or completely by passing one or more of the "DISPLAY_..." variables declared in PerlPoint::Constants.
Constants can be combined by addition.
Returns: the new object.
Example:
my ($parser)=new PerlPoint::Backend(name=>'example');register()
After building a new object by new() the object can be prepared by calls of the register method.
If the object walks through the data stream generated by PerlPoint::Parser, it will find several directives. A directive is a data struture flagging that a certain document part (or even formatting) starts or is completed. E.g. a headline is represented by headline start directive followed by tokens for the headline contents followed by a headline completion directive.
By using this method, you can register directive specific functions which should be called when the related directives are discovered. The idea is that such a function can produce a target language construct representing exactly the same document token that is modelled by the directive. E.g. if your target language is HTML and you register a headline handler and a headline start is found, this handler can generate a "<HEAD>" tag. This is quite simple.
According to this design, the object will pass the following data to a registered function:
- directive
-
the directive detected, this should be the same the function was registered for. See PerlPoint::Constants for a list of directives.
- start/stop flag
-
The document stream generated by the parser is strictly synchronous. Everything except of plain strings is represented by an open directive and a close directive, which may embed other parts of the document. A headline begins, something is in, then it is complete. It's the same for every tag or paragraph and even for the whole document.
So well, because of this structure, a handler registered for a certain directive is called for opening directives as well as for closing directives. To decide which case is true, a callback receives this parameter. It's always one of the constants DIRECTIVE_START or DIRECTIVE_COMPLETED.
For simple strings (words, spaces etc.) and line number hints, the callback will always be called with DIRECTIVE_START.
- directive values, if available
-
Certain directives provide additional data such as the headline level or the original documents name which are passed to their callbacks additionally. See the following list:
To express this by a prototype, all registered functions should have an interface of "$$:@".
Parameters:
- object
-
a backend object as made by new();
- directive
-
the directive this handler is registered for. See PerlPoint::Constants for a list of directives.
- handler
-
the function to be called if a pointed directive is entered while the run() method walks through the document stream.
Returns: no certain value;
Example:
$backend->register(DIRECTIVE_HEADLINE, \&handleHeadline);where handleHeadline could be something like
sub handleDocument
{
my ($directive, $startStop, $level)=@_;
confess "Something is wrong\n"
unless $directive==DIRECTIVE_HEADLINE;
if ($startStop==DIRECTIVE_START)
{print "<head$level>";}
else
{print "</head>";}
}SEE ALSO
- PerlPoint::Parser
-
A parser for Perl Point ASCII texts.
- PerlPoint::Constants
-
Public PerlPoint::... module constants.
AUTHOR
Jochen Stenzel (perl@jochen-stenzel.de), 1999-2000. All rights reserved.
This module is free software, you can redistribute it and/or modify it under the terms of the Artistic License distributed with Perl version 5.003 or (at your option) any later version. Please refer to the Artistic License that came with your Perl distribution for more details.
The Artistic License should have been included in your distribution of Perl. It resides in the file named "Artistic" at the top-level of the Perl source tree (where Perl was downloaded/unpacked - ask your system administrator if you dont know where this is). Alternatively, the current version of the Artistic License distributed with Perl can be viewed on-line on the World-Wide Web (WWW) from the following URL: http://www.perl.com/perl/misc/Artistic.html
DISCLAIMER
This software is distributed in the hope that it will be useful, but is provided "AS IS" WITHOUT WARRANTY OF ANY KIND, either expressed or implied, INCLUDING, without limitation, the implied warranties of MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE.
The ENTIRE RISK as to the quality and performance of the software IS WITH YOU (the holder of the software). Should the software prove defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE, MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even if they arise from known or unknown flaws in the software).
Please refer to the Artistic License that came with your Perl distribution for more details.