CPANDB::Requires(3pm)

💖 CPANDB::Requires — the manual, but make it cute

okay bestie, gather round, because today we're talking about CPANDB::Requires, a CPANDB class for the requires table. This is from the User Contributed Perl Documentation collection, and yes, we're gonna get through the whole thing together. No skipping. 🫶

---

✨ NAME ✨

CPANDB::Requires — it's the CPANDB class for the requires table, periodt. 💅

---

🌸 DESCRIPTION 🌸

TO BE COMPLETED

yeah. that's it. that's the whole description. it's giving "we'll finish it later" energy 😭 iconic honestly, but that's genuinely all the docs say, so we move.

---

🎀 METHODS 🎀

🦋 base

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

so normally? you're just working with one table class directly, and only with one ORLite package. that's the chill path. 😌

but — but — if for some reason you need to juggle multiple ORLite packages at the same time without hardcoding the root namespace over and over like a menace, you can pull the root namespace straight out of an object or a table class using the base method. slay. ✨

🦋 table

# Returns 'requires'
print CPANDB::Requires->table;

ngl you should not need the name of the table for any simple operations. but every so often you need it programmatically, and when that day comes, the table method is right there to hand you the table name. 💁‍♀️

🦋 load

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

here's the vibe: 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 is literally not created. no key, no method, no exceptions. 🚫

the load method is a shortcut for fetching one single object based on the value of the primary key. however — and this is important bestie — it should only be used when your code trusts that the record already exists. like, you're not checking. you're just assuming. risky but okay. 🙈

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

🦋 select

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

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

the select method runs a classic SQL SELECT query on the requires table. very demure, very mindful. 🎀

it takes an optional argument of a SQL phrase that gets added after the FROM requires section of the query, followed by the variables to be bound to the placeholders in that SQL phrase. any SQL that's compatible with SQLite can be used in the parameter. anything. go wild. 🔥

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

and if something goes wrong? it throws an exception, typically straight from the DBI layer. 💀

🦋 iterate

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

THIS ONE. okay. the iterate method lets you process large tables one record at a time without having to load them all into memory in advance. it's the main character of memory efficiency. 👑

this plays so well to the strength of SQLite, letting it do the work of loading an arbitrarily large stream of records from disk while retaining the full power of Perl when processing those records. best of both worlds, fr fr. 🌈

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 $_.

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

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

you can filter the list via SQL the same way you can with select:

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

you can also use it in raw form from the root namespace for better control. this form also lets you use arbitrarily complex queries, including joins. and instead of being objects, rows are provided as ARRAY references when used in this form. 👀

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

🦋 count

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

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

the count method runs a SELECT COUNT(*) query on the requires table. it's giving "how many though?" energy. 🔢

it takes an optional argument of a SQL phrase added after the FROM requires section 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. same deal as before. ✨

returns the number of objects that match the condition.

and yes, it 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

and that's genuinely where the docs stop. unfinished, but iconic. 😭

---

🌈 SQL 🌈

the requires table was originally created with this exact SQL command. copy it, don't touch it, it's precious:

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

---

🫶 SUPPORT 🫶

CPANDB::Requires is part of the CPANDB API.

see the documentation for CPANDB for more information. go read it, bestie, it's good for you. 📚

---

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

---

and that's the whole page, bestie!! 💖 this one's from perl v5.36.0, dated 2023-10-01 — so go forth, query that requires table, and remember: O(1) memory is a lifestyle. mwah 💋✨🎀