CPANDB...bution(3pm)

💖 NAME 💖

CPANDB::Distribution — it's the CPANDB class for the distribution table, bestie. That's the whole name, no cap.

---

✨ DESCRIPTION ✨

TO BE COMPLETED

...yeah. That's literally what it says. The author left us on read. 🫠 We move.

---

🎀 METHODS 🎀

base

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

Okay so normally you're gonna be living your life working directly with one table class, and only with one ORLite package. That's the vibe. 👑

But if for some reason you gotta juggle multiple ORLite packages at the same time and you don't wanna hardcode the root namespace every single time, you can pull the root namespace off an object or a table class using the base method. Slay.

table

# Returns 'distribution'
print CPANDB::Distribution->table;

Real talk, you should not need the table name for any simple operations. But from time to time you might need it programmatically — and if you do, the table method has you. It hands you the table name. 💅

load

my $object = CPANDB::Distribution->load( $distribution );

If your table has a single column primary key, a load method gets generated in the class. If there's no primary key, the method does not get created. Periodt.

So what does load do? It's a shortcut mechanism for fetching a single object based on the value of the primary key. But — and listen — it should only be used in cases where your code trusts that the record already exists. No vibe checks here, it just goes for it.

It returns a CPANDB::Distribution object, or it throws an exception if the object does not exist. 😭

select

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

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

The select method runs a classic SQL SELECT query on the distribution table. Very demure, very mindful.

It takes an optional argument: a SQL phrase that gets added after the FROM distribution part of the query, followed by variables to be bound to the placeholders in that SQL phrase. Any SQL that's compatible with SQLite can be used in the parameter. Go off. 🔥

Returns a list of CPANDB::Distribution objects when called in list context, or a reference to an ARRAY of CPANDB::Distribution objects when called in scalar context.

Throws an exception on error, typically straight from the DBI layer. 💀

iterate

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

The iterate method lets you process large tables one record at a time without having to load them all into memory first. It's giving efficiency. 🌸

This plays so well to SQLite's strengths — it lets SQLite do the work of loading an arbitrarily large stream of records from disk, while you keep the full power of Perl for processing those records.

The last argument to iterate must be a subroutine reference that gets called for each element in the list, with the object provided in the topic variable $_.

So that iterate code fragment above is functionally equivalent to this next one — except with an O(1) memory cost instead of O(n). Iconic.

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

You can filter the list via SQL in exactly the same way you can with select. 🦋

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

You can also use it in raw form from the root namespace for better control. Using this form also allows for arbitrarily complex queries, including joins. Instead of being objects, rows are provided as ARRAY references when you use it in this form.

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

count

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

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

The count method executes a SELECT COUNT(*) query on the distribution table. Math era. 🧮✨

It takes an optional argument: a SQL phrase that gets added after the FROM distribution part of the query, followed by variables to be bound to the placeholders in the SQL phrase. Any SQL that's compatible with SQLite can be used in the parameter.

Returns the number of objects that match the condition.

Throws an exception on error, typically directly from the DBI layer. 🙈

---

🌈 ACCESSORS 🌈

distribution

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

Returns true, or throws an exception on error.

REMAINING ACCESSORS TO BE COMPLETED — yeah bestie, more to come. They left it hanging. 😭

---

💜 SQL 💜

The distribution table was originally created with this exact SQL command. Copying it verbatim because that's the whole point:

CREATE TABLE distribution (
    distribution TEXT NOT NULL PRIMARY KEY,
    version TEXT NULL,
    author TEXT NOT NULL,
    meta INTEGER NOT NULL,
    license TEXT NULL,
    release TEXT NOT NULL,
    uploaded TEXT NULL,
    pass INTEGER NULL,
    fail INTEGER NULL,
    unknown INTEGER NULL,
    na INTEGER NULL,
    rating TEXT NULL,
    ratings INTEGER NOT NULL,
    weight INTEGER NOT NULL,
    volatility INTEGER NOT NULL,
    FOREIGN KEY (author) REFERENCES author (author)
)

---

🫶 SUPPORT 🫶

CPANDB::Distribution is part of the CPANDB API.

See the documentation for CPANDB for more information. 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 it, no crumbs 💅

This was Perl v5.36.0, dated 2023-10-01, from the User Contributed Perl Documentation — mwah, go forth and query responsibly. 🦋✨