NAME¶
Lire::ReportParser - Lire::XMLParser which parses XML reports
SYNOPSIS¶
package MyParser;
use base qw/ Lire::ReportParser /;
sub parse_end {
return "Finished";
}
package main::
my $parser = new MyParser;
my $result = eval { $parser->parsefile( "report.xml" ) };
croak "Error parsing report.xml: $@" if $@
print $result, "\n";
DESCRIPTION¶
This is a
Lire::XMLParser(3pm) subclass which handle XML document
adhering to the Lire Report Markup Language format. It's primary purpose is to
write custom handlers for the Lire XML Report format.
USAGE¶
You create an instance of a subclass of Lire::ReportParser and use either one of
the
parse() or
parsefile() methods to process the XML reports.
You'll probably never use the Lire::ReportParser module directly; you'll
likely use one subclass which actually does something when processing the
document.
new( %args )¶
my $parser = new Lire::ReportParser::ReportBuilder();
The
new() method takes parameters in the form of 'key' => value pairs.
The available parameters are specific to each processor. There are no generic
parameters.
WRITING AN XML REPORT PROCESSOR¶
Using Lire::ReportParser, one can write an XML report processor.
The programming model is similar to the expat event-based interface or the
well-known SAX model. The principal difference with those models is that this
module offers hooks specifically tailored for Lire's XML reports. For example,
instead of having one generic element-start event, you have methods for each
specific type of element, making it easy to hook on only the elements you're
interested in. It also offers some functions that make it easy to determine
the context (always a difficulty in event-based programming).
If you are uncomfortable with that kind of programming, there is also an
object-oriented API available to the XML reports. That API is more similar to
DOM type of programming. Its principal drawback is that its less performant
since it has to parse the whole XML document in memory to build an object
representation. But if you need to "navigate" the document, it's a
lot better than the event-based API.
The main way of using that API to write a custom XML report handler is by
subclassing the Lire::ReportParser module and overriding the functions related
to the elements you are interested in.
There are 3 categories of methods you can override.
- Customization Methods
- Those are methods that customize the way the
Lire::ReportParser will operate. The most important one is the
new() "constructor".
- Generic element methods
- Those are methods that are invoked on each element before
the more specific or higher ones and can be used to hook before the other
events are synthesized.
HIGH-LEVEL EVENT METHODS¶
For each element defined, an
element_name_start() and an
element_name _end() method are invoked. For elements that
contains character data, an
element_name_char() method will also
be invoked altough, you probably want to hook onto the easier handle_
element_name() methods in these cases.
When you override any of those mehod (except the handle_
element_name()
one), you
must invoke the parent method also:
sub subreport_start {
my ( $self, $name, $attr ) = @_;
$self->SUPER::subreport_start( $name, $attr );
# Processor specific handling.
}
report_start( $name, $attr )¶
Called when the report element start tag is encountered.
The only defined attribute is "version". The current version is 2.0,
but older 1.0 report can still be parsed.
report_end( $name )¶
Called when the report element end tag is encountered.
handle_title( $title )¶
Method invoked after the "title" element was processed. The $title
parameter contains the content of the element. This can be a report's,
subreport's or section's title. You'll need to use the
in_element()
method to determine the context.
handle_description( $docbook_desc )¶
Unless the description_start and description_end events are overriden the
content of the description will be collected and will be available in the
handle_description() method.
handle_date( $date, $date_epoch )¶
Called after the "date" element was parsed. The formatted date is
available in the $date parameter, the date in number of seconds since the
epoch is available in the $date_epoch parameter.
This can be the report's or a subreport's date, you'll need to use the
in_element() method to determine the appropriate context.
handle_timespan( $timespan, $epoch_start, $epoch_end, $period
)¶
Called after the "timespan" element was parsed. The formatted timespan
is available in the $timespan parameter, starting and ending dates of the
timespan are available as number of seconds since the epoch in the
$epoch_start and $epoch_end parameters. The $period parameter contians the
timespan's period attribute.
This can be the timespan of the report or the subreport, you'll need to use the
in_element() method to determine the appropriate context.
section_start( $name, $attr )¶
Called when the opening tag of a "section" element is encountered.
section_end( $name )¶
Called when the closing tag of a "section" element is encountered.
missing_subreport_start( $name, $attr )¶
Called when the opening tag of a "missing-subreport" element is
encountered. The "superservice" attribute contains the
superservice's of the subreport, the "type" attribute contains the
report specification ID and the "reason" attribute will contains the
reason why the subreport is missing.
missing_subreport_end( $name )¶
Called when the closing tag of a "missing-subreport" element is
encountered.
subreport_start( $name, $attr )¶
Called when the opening tag of the "subreport" element is encountered.
The "superservice" attribute contains the subreport's superservice
and the "type" attribute contains the ID of the report specification
that was used to generate that subreport.
subreport_end( $name )¶
Called when the "subreport"'s closing tag is encountered.
table_start( $name, $attr )¶
Called when the opening tag of the "table" element is encountered. The
"show" attribute contains the maximum number of entries that should
be displayed (there may more entries than this number).
table_end( $name )¶
Called when the "table"'s closing tag is encountered.
table_info_start( $name, $attr )¶
Called when the "table-info"'s closing tag is encountered.
There should be no reason for subclasses to override this method. The
Lire::ReportParser takes care of parsing the "table-info" content
and offers that information through a Lire::Report::TableInfo object which is
accessible through the
current_table_info() method.
table_info_end( $name )¶
Called when the "table-info"'s closing tag is encountered. See
table_info_start() documentation for important comments.
group_info_start( $name, $attr )¶
Called when the "group-info"'s opening tag is encountered. See
table_info_start() documentation for important comments.
group_info_end( $name )¶
Called when the "group-info"'s closing tag is encountered. See
table_info_start() documentation for important comments.
column_info_start( $name, $attr )¶
Called when the "column-info"'s opening tag is encountered. See
table_info_start() documentation for important comments.
column_info_end( $name )¶
Called when the "column-info"'s closing tag is encountered. See
table_info_start() documentation for important comments.
group_summary_start( $name, $attr )¶
Called when the "group-summary"'s opening tag is encountered.
group_summary_end( $name )¶
Called when the "group-summary"'s closing tag is encountered.
group_start( $name, $attr )¶
Called when the opening tag of the "group" element is encountered.
"group" elements introduce a kind of nested table. The
"show" attribute contains the maximum number of entries that should
be displayed, altough more entries may be present in the report.
group_end( $name )¶
Called when the "group"'s closing tag is encountered.
entry_start( $name, $attr )¶
Called when the opening tag of an "entry" element is encountered.
entry_end( $name )¶
Called when the "entry"'s closing tag is encountered.
handle_name( $name_rec )¶
Called after a "name" element was parsed. The $name_rec parameter is
an hash reference which contains the different values of the name datum. Keys
that are defined in this hash:
- content
- That's the actual content of the name element. This
contains the name in a format suitable for display.
- value
- This contains the unformatted value of the name. For
example, when the name is a time string, this attribute will contains the
time in seconds since epoch.
- range
- For some names, the actual content express a range (time,
size, etc.). This attribute contains the length of the range.
- col_info
- The Lire::ColumnInfo object describing the column in which
this name appears.
handle_value( $value_rec )¶
Called after a "value" element was parsed. The $value_rec parameter is
an hash reference which contains the different values of the value datum. Keys
that are defined in this hash:
- content
- That's the actual content of the value element. This
contains the value in a format suitable for display.
- value
- This contains the unformatted value. For example, when
bytes are displayed using "1M" or "1.1G", this will
contains the value in bytes.
- total
- This is used by values that represent an average. It
contains the total which makes up the average.
- n
- This is used by values that represent an average. It
contains the total which was used in the division to compute the
average.
- col_info
- The Lire::ColumnInfo object describing the column in which
this name appears.
handle_summary_value( $value_rec )¶
Called after a "value" element located in the group-summary element
was parsed. The $value_rec parameter is identical than in the
handle_value() method.
handle_chart_configs( $configs )¶
If the Subreport contained chart configurations, an array reference of
Lire::Report::ChartConfig objects will be passed to this event handler.
CONTEXT METHODS¶
Finally, here a bunch of additional methods that can be used to query some
context information when processing elements.
current_subreport_count( )¶
Returns the number of subreport that are present to date in the report. That
number is equals to the number of processed "subreport" elements,
i.e. the current subreport isn't counted untill the closing tag was processed.
current_section_subreport_count( )¶
Returns the number of subreport that are present to date in the section. That
number is equals to the number of processed "subreport" elements,
i.e. the current subreport isn't counted untill the closing tag was processed.
current_date( )¶
Returns the content of the "date" element that applies to the current
element. This will either be the current subreport's date or the default one
taken from the "report" element.
The date is returned as an hash reference which will contain the formatted date
in the "date" key and the date in seconds since epoch in the
"time" key.
current_timespan( )¶
Returns the content of the "timespan" element that applies to the
current element. This will either be the current subreport's date or the
default one taken from the "report" element.
The timespan is returned as an hash reference which will contain the formatted
timespan in the "timespan" key. The starting and ending date of the
timespan are available as seconds since epoch in the "start" and
"end" keys. The "period" key contains the report's
timespan.
current_superservice( )¶
Useful in "subreport" context, it returns the superservice's of the
current subreport.
current_type( )¶
Useful in "subreport" context, it returns the ID of the report
specification that was used to generate the current subreport.
current_table_info()¶
Useful when processing "group" and "entry", this returns a
Lire::Report;:TableInfo object which describes the layout of the current
table.
current_group_entry_show( )¶
Useful in "table" and "group" context, it returns the
maximum number of entries that should be displayed.
show_current_entry( )¶
Useful in "entry" context , this can be used to test whether or not
the current "entry" should be displayed based on the current entry
index and the parent's "show" attribute.
current_table_entry_count( )¶
Useful in "table" context, it returns the number of entries that were
processed so far. This only reports the entries in the "table"
element, not counting the one in the nested "group".
SEE ALSO¶
Lire::Report(3pm), Lire::XMLParser(3pm)
Lire::ReportParser::AsciiDocBookFormatter(3pm),
Lire::ReportParser::AsciiWriter(3pm),
Lire::ReportParser::HTMLDocBookFormatter(3pm),
Lire::ReportParser::HTMLWriter(3pm),
Lire::ReportParser::ReportBuilder(3pm),
Lire::ReportParser::ExcelWriter(3pm),
Lire::Report::TableInfo(3pm)
AUTHOR¶
Francis J. Lacoste <flacoste@logreport.org>
VERSION¶
$Id: ReportParser.pm,v 1.52 2006/07/23 13:16:29 vanbaal Exp $
COPYRIGHT¶
Copyright (C) 2001-2004 Stichting LogReport Foundation LogReport@LogReport.org
This file is part of Lire.
Lire is free software; you can redistribute it and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
this program (see COPYING); if not, check with
http://www.gnu.org/copyleft/gpl.html.
POD ERRORS¶
Hey!
The above document had some coding errors, which are explained
below:
- Around line 138:
- You forgot a '=back' before '=head1'