ReportOperator(3pm)

📦 version 2.1.1, in arch rolling

💅 NAME 💅

Lire::ReportOperator — the base class for all the operators that can be used to compute reports. It's the momager of the operator family, fr fr. 👑

So like, the manual page you're reading rn is from LogReport's Lire Documentation, and it's giving "backstage pass to the operator squad" energy. 🎀

✨ SYNOPSIS ✨

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

That's it, that's the whole vibe check. Three little getters and you're in. 🦋

🌸 DESCRIPTION 🌸

okay so Lire::ReportOperator is the base class for every operator that can be used to compute the data that shows up in Lire's reports. Bestie, this class is the blueprint — it only provides the behavior that's common to all operators, no more, no less. 💖

Currently, the operators defined in Lire come in two main varieties:

  • first, there are aggregators — operators that can split DLF records into multiple groups
  • second, there are group operators — operators that can compute data based on a group of DLF records

And the family tree is: aggregators are subclasses of Lire::Aggregator, and group operations are subclasses of Lire::Aggregate. Slay, inheritance. 🌈

💜 METHODS 💜

🔥 op()

Returns the XML element's name which refers to this operator. That's it, that's the whole function. 💅

🔥 report_spec()

Returns the Lire::ReportSpec object in which this operator is. Yep, you're in that report spec. 👑

🔥 parent()

Returns the parent of this operator. Heads up: this will be undefined for the top-level aggregator in the report specification — it's the main character, it has no parent, periodt. Also important: only Lire::Aggregator can have children and as such be a parent. 🧚

🔥 last_parent()

Returns our top-level parent. Like, the ultimate ancestor. The final boss. 😭

🔥 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. It's literally the whole point — this name is used to identify the values generated by this operator in the generated report. iykyk. ⭐

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

🔥 has_label()

Returns true if this operator has an explicit label assigned. Simple as that. ✅

🔥 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. Cute little setter behavior, obsessed. 🎀

🫶 METHODS FOR SUBCLASSES 🫶

Subclasses must use a hash to represent their instance data. No vibes-based storage, bestie, a hash. And they should call init() from their constructor method. 💖

🌟 init( %params )

Lire::Report is an abstract class which shouldn't be instanciated directly. (Spelling is theirs, don't @ me 💀.) 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 🚨 (no skipping, this one's required).
  • 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. 🎁

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.

⚠️ tiny doc quirk alert: the next line talks about $indent, bestie — yes, even though the signature says $prefix. $indent is an integer which gives the number of spaces which should be used as indentation when writing the XML. That's literally what the page says. 🙈

🌟 build_query( $query )

That's the heading. That's... literally all the page gives us on this one. 💀 No description, no params blurb, nothing. It exists, it takes $query, we move on. 😭

🧚 MERGING API 🧚

The methods here should be implemented to support merging of data generated by this operator from two reports. Two reports, one operator, let's go. 🔥

💫 init_merge()

This method is called once before merging of XML reports is started. One single call. Make it count. ⭐

💫 end_merge()

This method is once after all the XML reports were merged. (Yep, the original sentence is missing a word there — "is called once" is obviously the vibe. 🫶)

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

Now — 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. Depending on what your 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 );

Look at that, a little import for your troubles. 🎀

💫 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. Match made in heaven. 💖

💫 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. Patient king behavior. 👑

💫 add_entry_value( $entry, $data )

This method will be called once for each group created in by the aggregator. (Yes, "created in by". We're keeping it. 🙈)

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. That's where the math happens, bestie. 🔥

💫 group_data_value($data)

Returns the "value" from one data item created by a init_group_data() method.

🚨 reminder: this is a function, not a method. Do not call it as a method. The docs said what they said. 💅

🌈 SEE ALSO 🌈

Go read those if you wanna complete the lore. 📚

🎀 AUTHOR 🎀

Francis J. Lacoste <flacoste@logreport.org> — thank you for your service, legend. 🫶

⭐ 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. 🚨 (yes, that's the legal all-caps part, bestie — it means it)

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.

and that's the whole page, babe 💖 this was ReportOperator(3pm) from Lire 2.1.1, dated 2025-09-28 — literally stamped and dated and ready for your reading pleasure. now go build some operators, ily, bye 🦋✨

📦 where this page comes from