RoPkg:...lection(3pm)

RoPkg::DBCollection 💖

okay bestie, so this is a page from the User Contributed Perl Documentation set, and the module in question is RoPkg::DBCollection — the base class you use when you want a whole collection of database objects, not just one lonely little row. 🦋

---

✨ NAME ✨

RoPkg::DBCollection — it's the base class you can use for collections of database objects. periodt.

---

🌸 VERSION 🌸

0.1.3 — yes, a real version number, she's official 💅

---

🎀 DESCRIPTION 🎀

So RoPkg::DBCollection is a class you use as a base class for a database collection of objects. Like, it's the blueprint, not the building. 🏗️

It's already being used by RoPkg::Simba::Mirrors, RoPkg::Simba::Commands and RoPkg::Simba::Excludes. Iconic trio honestly.

⚠️ Important vibe check: this class should not be used directly in your applications — it should be derived. She's the mother, not the main character. Do not instantiate her raw, bestie, I'm begging. 😭

---

🧚 SUBROUTINES/METHODS 🧚

new()

The class constructor. She accepts a hash with parameters, and the parameters you can pass in are:

• dbo — a database object (an instance of RoPkg::DB)
• dbo_method — a database method (for use with RoPkg::DB)
• table — the sql table name where the objects' data can be found

🚨 If you don't specify the dbo and dbo_method parameters, a Param::Missing exception gets raised. Not optional, bestie, not a suggestion.

---

dbh()

returns the database handler (DBI object) used by the class. that's it, that's the whole method. short queen. 👑

---

_count($fields)

Returns the number of records who match the fields specified in $fields.

This method should be overriden by the child classes — like, it's your job now, she's handing you the mic. 🎤

The $fields must be specified in SQL::Abstract format. Please refer to the SQL::Abstract documentation for more details about the $fields format. (go read it, iykyk 📚)

---

_get($class_name, $fields, $order_by)

Returns a array of initialized objects. The values are read from the database. ✨

• $class_name is the name of the class who's gonna be instanciated. When creating the class instance, dbo and dbo_method parameters are passed to the new() method.
• The records from the database must match the $fields parameter, and the order is given by $order_by. For more details of these 2 parameters please refer to SQL::Abstract documentation.

Exceptions throwed:

• Param::Missing — when $class_name has not been specified
• Param::Wrong — when $class_name is not a class name
• DB::NoResults — when the query returned 0 results

---

💜 SYNOPSIS 💜

here's the whole thing, verbatim, because code is sacred:

 package RoPkg::Tester;

 use strict;
 use warnings;

 use Scalar::Util qw(blessed);
 use RoPkg::Exceptions;
 use RoPkg::DBCollection;
 use vars qw(@ISA);

 @ISA=qw(RoPkg::DBCollection);

 sub new {
   my ($class, %opt) = @_;
   my $self;

   $self = $class->SUPER::new(%opt);
   $self->{table} = 'Mirrors';

   return $self;
 }

 sub Count {
   my ($self) = @_;

   if (!blessed($self)) {
     OutsideClass->throw(
       error    => 'Called outside class instance',
       pkg_name => 'RoPkg::Tester',
     );
   }

   return $self->_count();
 }

 sub Get {
   my ($self, $fields) = @_;

   if (!blessed($self)) {
     OutsideClass->throw(
       error    => 'Called outside class instance',
       pkg_name => 'RoPkg::Tester'
     );
   }

   return $self->_get('RoPkg::Simba::Mirror');
 }

 1;

 sub main {
   my ($dbc, $dbp);

   $dbp = new RoPkg::DB();
   $dbp->Add(
           'dbi:mysql:database=mirrors_db;host=localhost',
           'root',
           '',
           'mirrors'
         );

   $dbc = new RoPkg::Tester(
            dbo => $dbp,
            dbo_method => 'db_mirrors'
          );

   print $dbc->Count(),$/;

   my @mirrors = $dbc->Get();
 }

 main();

like, look at her go. subclasses, SUPER::new, blessed checks, the whole little ecosystem. she ate. 🔥

---

🩺 DIAGNOSTICS 🩺

This module comes with tests. To run them, unpack the source and use make test command. 💻

---

🔍 PERL CRITIC 🔍

This modules is perlcritic level 2 compliant (with 1 exception). one tiny exception, we don't talk about her. 🙈

---

⚙️ CONFIGURATION AND ENVIRONMENT ⚙️

This module does not use any configuration files or environment variables. 🎉

However, it is possible that some dependencies to do so. Please read the man page of each dependency to find out more information. (yes, go read those too, bestie, do your homework 📖)

---

🧩 DEPENDENCIES 🧩

This module use the following modules:

• SQL::Abstract
• DBI
• Scalar::Util
• RoPkg

---

🚫 INCOMPATIBILITIES 🚫

None known to the author. 💀 (as in, nothing to report, not as in, dead)

---

🐛 BUGS AND LIMITATIONS 🐛

None known to the author. flawless behavior honestly, no cap. ✨

---

👀 SEE ALSO 👀

RoPkg::Exceptions RoPkg::DB RoPkg::DBObject RoPkg::Simba::Mirrors

go read the whole family, they're all connected. 🫶

---

👑 AUTHOR 👑

Subredu Manuel <diablo@iasi.roedu.net> — thank you for your service, king 🫡

---

📜 LICENSE AND COPYRIGHT 📜

Copyright (C) 2006 Subredu Manuel. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license. 💖

---

and that's the whole page, bestie!! 💅 this one's perl v5.32.1, dated 2021-12-26, and it lives in the RoPkg:...lection(3pm) corner of the manual universe — love that for her 🌈✨ mwah, go write a subclass, you got this 🦋