Provided by: lire-devel-doc_2.1.1-2.1_all bug

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.