Lire::ReportParser - Lire::XMLParser which parses XML reports

    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";

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.

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.

    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.

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.

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.
    }

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. Called after a CWvalue element was parsed. The CW$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. Called after a CWvalue element located in the group-summary element was parsed. The CW$value_rec parameter is identical than in the handle_value() method. If the Subreport contained chart configurations, an array reference of Lire::Report::ChartConfig objects will be passed to this event handler.

Finally, here a bunch of additional methods that can be used to query some context information when processing elements.

Returns the number of subreport that are present to date in the report. That number is equals to the number of processed CWsubreport elements, i.e. the current subreport isn't counted untill the closing tag was processed.

Returns the number of subreport that are present to date in the section. That number is equals to the number of processed CWsubreport elements, i.e. the current subreport isn't counted untill the closing tag was processed.

Returns the content of the CWdate element that applies to the current element. This will either be the current subreport's date or the default one taken from the CWreport element. The date is returned as an hash reference which will contain the formatted date in the CWdate key and the date in seconds since epoch in the CWtime key.

Returns the content of the CWtimespan element that applies to the current element. This will either be the current subreport's date or the default one taken from the CWreport element. The timespan is returned as an hash reference which will contain the formatted timespan in the CWtimespan key. The starting and ending date of the timespan are available as seconds since epoch in the CWstart and CWend keys. The CWperiod key contains the report's timespan.

Useful in CWsubreport context, it returns the superservice's of the current subreport.

Useful in CWsubreport context, it returns the ID of the report specification that was used to generate the current subreport.

Useful when processing CWgroup and CWentry, this returns a Lire::Report;:TableInfo object which describes the layout of the current table.

Useful in CWtable and CWgroup context, it returns the maximum number of entries that should be displayed.

Useful in CWentry context , this can be used to test whether or not the current CWentry should be displayed based on the current entry index and the parent's CWshow attribute.

Useful in CWtable context, it returns the number of entries that were processed so far. This only reports the entries in the CWtable element, not counting the one in the nested CWgroup.

 Lire::Report(3), Lire::XMLParser(3)
 Lire::ReportParser::AsciiDocBookFormatter(3),
 Lire::ReportParser::AsciiWriter(3),
 Lire::ReportParser::HTMLDocBookFormatter(3),
 Lire::ReportParser::HTMLWriter(3),
 Lire::ReportParser::ReportBuilder(3),
 Lire::ReportParser::ExcelWriter(3),
 Lire::Report::TableInfo(3)

  Francis J. Lacoste <flacoste@logreport.org>

$Id: ReportParser.pm,v 1.51 2004/07/21 16:11:27 flacoste Exp $

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 or write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.