man Lire::ReportOperator (3): 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.

AUTHOR

  Francis J. Lacoste <[email protected]>

VERSION

$Id: ReportOperator.pm,v 1.21 2006/07/23 13:16:29 vanbaal Exp $

COPYRIGHT

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.