CPANDB::Module(3pm)

💖 NAME 💖

CPANDB::Module — it's the CPANDB class for the module table, bestie. That's the whole vibe. It's the Perl class you use to talk to that one specific table in the CPANDB database. 🦋

---

✨ DESCRIPTION ✨

TO BE COMPLETED

Yeah… that's literally what the docs say. Not me making it up. The description is a WIP, it's giving "placeholder era". Moving on. 💀

---

🎀 METHODS 🎀

🌸 base

# Returns 'CPANDB'
my $namespace = CPANDB::Module->base;

So, lowkey, most of the time you only ever touch one table class, and you only ever work with one ORLite package. That's the normal, chill life. 🫶

But — and this is the part nobody tells you — if you somehow need to juggle multiple ORLite packages at the same time and you do not wanna hardcode the root namespace over and over like a menace, you can just ask an object or a table class what its root namespace is. That's what base does. Iconic, honestly. 👑

🌸 table

# Returns 'module'
print CPANDB::Module->table;

For all your simple little operations you should not need the table's name, fr fr. But every now and then you're doing something programmatic and you need it, so table hands it to you. That's it. That's the method. Slay. ✨

🌸 load

my $object = CPANDB::Module->load( $module );

So if your table has a single-column primary key, a load method gets generated in the class automatically. And if there's no primary key? Then the method just… does not get created. Doesn't exist. Ghosted. 🙈

load is your shortcut for grabbing exactly one object by the value of the primary key. It's a shortcut, okay, which means it only makes sense in cases where your code trusts that the record already exists.

It returns a CPANDB::Module object, or throws an exception if the object does not exist. No in-between, no vibes, just object or exception. 😭

🌸 select

# Get all objects in list context
my @list = CPANDB::Module->select;

# Get a subset of objects in scalar context
my $array_ref = CPANDB::Module->select(
    'where module > ? order by module',
    1000,
);

select runs a classic, textbook SQL SELECT query on the module table. Very demure, very mindful. 💅

You can pass it an optional argument: a SQL phrase that gets tacked on right after the FROM module part of the query, followed by the variables you want bound to the ? placeholders in that phrase. And like — any SQL that SQLite is compatible with is fair game in that parameter. Go off. 🔥

Call it in list context and you get a list of CPANDB::Module objects. Call it in scalar context and you get a reference to an ARRAY of CPANDB::Module objects. Both valid, both cute.

And if something goes wrong it throws an exception — typically straight from the DBI layer, so, y'know, blame DBI. 😌

🌸 iterate

CPANDB::Module->iterate( sub {
    print $_->module . "\n";
} );

Okay this one is genuinely the moment. iterate lets you process huge tables one record at a time without having to load them all into memory first. No more "oops I ate all the RAM". 🧚

This plays so well to SQLite's strengths — it does the work of streaming an arbitrarily large stream of records off disk, while you keep the full power of Perl for processing each record. Best of both worlds, no cap.

The last argument to iterate must be a subroutine reference. It gets called for every element in the list, with the object handed to you in the topic variable $_. 🎀

Which means that code fragment up there is functionally equivalent to this next one — the only difference being an O(1) memory cost instead of O(n):

foreach ( CPANDB::Module->select ) {
    print $_->module . "\n";
}

You can filter the list with SQL exactly the same way you can with select:

CPANDB::Module->iterate(
    'order by ?', 'module',
    sub {
        print $_->module . "\n";
    }
);

And you can also call it in raw form from the root namespace when you want better control. That form also unlocks arbitrarily complex queries — including joins. Just know that in raw form, rows come to you as ARRAY references instead of objects. Different format, same energy.

CPANDB->iterate(
    'select name from module order by module',
    sub {
        print $_->[0] . "\n";
    }
);

🌸 count

# How many objects are in the table
my $rows = CPANDB::Module->count;

# How many objects
my $small = CPANDB::Module->count(
    'where module > ?',
    1000,
);

count runs a SELECT COUNT(*) query on the module table. Number go up, we love to see it. 🔢

Same deal as the others: optional argument = a SQL phrase added after the FROM module section, followed by variables to bind to the placeholders in that phrase. Any SQL compatible with SQLite can be used in the parameter.

It returns the number of objects matching the condition.

And yes, it throws an exception on error, typically directly from the DBI layer. The DBI layer is always there. Watching. 🙈

---

👑 ACCESSORS 👑

🌸 module

if ( $object->module ) {
    print "Object has been inserted\n";
} else {
    print "Object has not been inserted\n";
}

Returns true, or throws an exception on error. Simple as that.

REMAINING ACCESSORS TO BE COMPLETED

Not me. That's the doc. The rest of the accessors are still cooking. 🍓

---

🦋 SQL 🦋

The module table was originally created with this exact SQL command, and I mean exact — character for character, no edits, no notes:

CREATE TABLE module (
    module TEXT NOT NULL PRIMARY KEY,
    version TEXT NULL,
    distribution TEXT NOT NULL,
    FOREIGN KEY (distribution) REFERENCES distribution (distribution)
)

Look at that schema. module is TEXT NOT NULL PRIMARY KEY, version is TEXT NULL (nullable bestie, it's allowed to be nothing), distribution is TEXT NOT NULL, and there's a FOREIGN KEY pointing distribution at distribution (distribution). Structurally gorgeous. 🌈

---

💜 SUPPORT 💜

CPANDB::Module is part of the CPANDB API.

See the documentation for CPANDB for more information. That's where the rest of the lore lives. iykyk. 📚

---

⭐ AUTHOR ⭐

Adam Kennedy <adamk@cpan.org>

---

🌸 COPYRIGHT 🌸

Copyright 2009 - 2012 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

---

okay that's the whole page, you ate that, no crumbs left 💅

this was perl v5.36.0, dated 2023-10-01, and the page you just read is CPANDB::Module(3pm) from the User Contributed Perl Documentation. mwah, go forth and query responsibly 🫶✨