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.