NAME

       Lire::ReportOperator - Base class for all operators that can be used to compute reports

SYNOPSIS

           print $op->name(), "\n";
           print $op->op(), "\n";
           print $op->label(), "\n";

DESCRIPTION

       The Lire::ReportOperator is the base class for all operators that can be used to compute
       the data appearing in Lire's reports. This class only provides the behavior common to all
       operators.

       Currently, the operators defined in Lire come into two main varieties: first, there are
       aggregators which are operators that can split DLF records into multiple groups, second
       there are group operators that can compute data based on a group of DLF records.
       Aggregators are subclasses of Lire::Aggregator and group operations are subclasses of
       Lire::Aggregate.

METHODS

   op()
       Returns the XML element's name which refers to this operator.

   report_spec()
       Returns the Lire::ReportSpec object in which this operator is.

   parent()
       Returns the parent of this operator. This will be undefined for the top-level aggregator
       in the report specification. Only Lire::Aggregator can have children and as such be a
       parent.

   last_parent()
       Returns our top-level parent.

   name( [$new_name] )
       Returns the name of this operator in the current report specification.  The operator's
       name is an identifier that must be unique in a given report specification. This name will
       be used to identify the values generated by this operator in the generated report.

       If $new_name is set, this operator's name will be changed to this new value.

   has_label()
       Returns true if this operator has an explicit label assigned.

   label( [$new_label] )
       Returns what should be used as column's label for the data generated by this operator.

       If the second argument is set, the column label will be set to this new value.

METHODS FOR SUBCLASSES

       Subclasses must use a hash to represent their instance data. They should call init() from
       their constructor method.

   init( %params )
       Lire::Report is an abstract class which shouldn't be instanciated directly. Subclasses
       should call the init() method in their constructor. This method initializes the attributes
       common to all operators. The %params keys that should be defined are:

       op  The operator's kind. That's the XML element's name. It's a mandatory parameter.

       parent
           This operator's parent. This must be present unless the element is the top-level
           aggregator.

       report_spec
           The report specification in which this operator is added.

       label
           This operator's label. This is an optional information.

       This method returns the object.

   print( $fh, $prefix )
       This is the method which is called to write an XML representation of this operator.

       $fh is the file handle onto which to output the XML representation.  $indent is an integer
       which gives the number of spaces which should be used as indentation when writing the XML.

   build_query( $query )

MERGING API

       The methods should be implemented to support merging of data generated by this operator
       from two reports.

   init_merge()
       This method is called once before merging of XML reports is started.

   end_merge()
       This method is once after all the XML reports were merged.

   init_group_data()
       This method should return a data structure that will be passed the call to
       update_group_data() and merge_group_data(). There will be one such data structure for
       every group that exists in the aggregator containing this operator.

       There are a few restrictions placed on this data structure in order to assure that it can
       be sorted by aggregator that need to sort their entries. If the data structure is

       SCALAR
           That value can be used for sorting purpose.

       SCALAR REFERENCE
           The scalar value will be used as sorting key.

       ARRAY REFERENCE
           The first item in the array reference will be used as sorting key.

       HASH REFERENCE
           The "sort_value" items in the hash will be used as sorting key.

       OBJECT REFERENCE
           The value returned by the sort_value() method will be used as sorting key.

       A function group_data_value() can be used to extract the sorting key value according to
       these rules. It can be imported:

           use Lire::ReportOperator qw/group_data_value/;

           my $v = group_data_value( $data );

   merge_group_data( $value, $data )
       This method will be called once for each value generated by this operator in the XML
       reports to be merged.

       The $value parameter can be either an hash reference or a Lire::Report::Group object. It
       will be the same things that was generated by this operator.

       $data is the group data structure returned by init_group_data() for the group where this
       $value should be merged.

   end_group_data( $data )
       This method will be called once for every group that was created by the aggregator
       containing this operator. The $data parameter is the data structure that was returned by
       init_group_data() for the current group.

       One possible use of this method would be, for example, for the avg operator to compute the
       actual average since it cannot be done until all the records are processed.

   add_entry_value( $entry, $data )
       This method will be called once for each group created in by the aggregator. In this
       method, the operator should add the appropriate name and value for this entry. $entry is
       the Lire::Report::Entry object to which the names and/or values should be added. $data is
       the data structure returned by init_group_data() corresponding for the current group.

       For example, its in this method that the sum operator will add the value containing the
       sum for the current entry.

   group_data_value($data)
       Returns the "value" from one data item created by a init_group_data() method. This is a
       function not a method.

SEE ALSO

       Lire::ReportSpec(3pm), Lire::Aggregate(3pm), Lire::Aggregator(3pm).

AUTHOR

         Francis J. Lacoste <flacoste@logreport.org>

VERSION

       $Id: ReportOperator.pm,v 1.21 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.