trusty (3) Lire::ReportOperator.3pm.gz

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

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