CPANDB...ndency(3pm)

✨ CPANDB::Dependency — the dependency table glow-up ✨

okay bestie, gather round 💖 this is the manual page for CPANDB::Dependency, a 3pm Perl module page (yes, section 3pm, that's the library-manual section, iykyk). It's the CPANDB class for the dependency table. Let's get into it 🦋

---

🌸 NAME 🌸

CPANDB::Dependency — the CPANDB class for the dependency table. that's it, that's the name, no cap 💅

---

🎀 DESCRIPTION 🎀

TO BE COMPLETED

literally it just says that. the description is a work in progress, bestie 😭 we love an unfinished icon.

---

💅 METHODS 💅

🫶 base

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

so, like, normally you're only ever working directly with a table class, and only with one ORLite package. that's the vibe. one package, one table class, iconic, no drama ✨

BUT — and this is the part where it gets spicy 🔥 — if for some reason you need to work with multiple ORLite packages at the same time without hardcoding the root namespace every single time, you can use the "base" method to figure out the root namespace from an object or a table class. so instead of being like "hmm what's the namespace" forty times, you just ask the object. slay.

🦋 table

# Returns 'dependency'
print CPANDB::Dependency->table;

for simple operations you genuinely should not need the name of the table, fr fr. but every now and then you might need it programmatically — and when that day comes, the "table" method is right there to hand you the table name. it's giving "you'll know when you need it" 💜

⭐ load

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

here's the tea: if your table has a single column primary key, a "load" method gets generated in the class. if there is no primary key, the method is not created — like, it simply does not exist, don't go looking for it 🫠

so what does "load" do? it's the shortcut mechanism for fetching a single object based on the value of the primary key. cute, right? BUT — and listen closely bestie — it should only be used for cases where your code trusts the record to already exist. it is not here to gently check for you, it is here to assume. main character energy, honestly.

it returns a CPANDB::Dependency object, or throws an exception if the object does not exist. so like, if it's not there, it's not quietly returning undef, it's throwing hands 😭

🌈 select

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

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

the "select" method runs a totally typical SQL SELECT query on the dependency table. classic. periodt.

it takes an optional argument — a SQL phrase that gets added after the FROM dependency section of the query — followed by the variables to be bound to the placeholders in that SQL phrase. and get this: any SQL that is compatible with SQLite can be used in the parameter. go off, SQLite 💖

so the returns? list of CPANDB::Dependency objects when you call it in list context, or a reference to an ARRAY of CPANDB::Dependency objects when you call it in scalar context. both valid, both cute.

and it throws an exception on error, typically directly from the DBI layer. that's just the DBI being the DBI, ngl.

🧚 iterate

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

okay this one is genuinely my fave 🥹 the "iterate" method lets you process large tables one record at a time without having to load them all into memory in advance. like, you don't have to hold the entire table in your head. self-care.

this plays so well to the strength of SQLite — it lets SQLite do the work of loading an arbitrarily large stream of records from disk while you keep the full power of Perl when processing those records. it's a collab. it's a crossover episode. 💜

the last argument to "iterate" must be a subroutine reference, and it gets called for each element in the list, with the object provided in the topic variable $_. so $_ is your bestie in there.

this makes the "iterate" code fragment above functionally equivalent to the following — except with an O(1) memory cost instead of O(n). which is, frankly, the whole point 🔥

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

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

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

AND you can also use it in raw form from the root namespace for better control 👑 using this form also unlocks arbitrarily complex queries, including joins. but heads up: instead of being objects, rows are provided as ARRAY references when you use it in this form. so adjust accordingly, bestie.

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

🌸 count

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

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

the "count" method runs a SELECT COUNT(*) query on the dependency table. it's the "how many though" method, and honestly? we need it.

it takes an optional argument — a SQL phrase added after the FROM dependency section of the query — followed by variables to be bound to the placeholders in the SQL phrase. and again: any SQL that is compatible with SQLite can be used in the parameter. same energy as select, same flexibility ✨

returns the number of objects that match the condition. a number. just a number. iconic.

and it throws an exception on error, typically directly from the DBI layer. the DBI stays dramatic 💀

---

💖 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. that's the whole deal. true or chaos, pick your fighter 💅

REMAINING ACCESSORS TO BE COMPLETED

yep. the rest of the accessors are still cooking 🫠 we'll get there. eventually. probably.

---

👑 SQL 👑

the dependency table was originally created with this exact SQL command — no edits, no notes, this is the original recipe:

CREATE TABLE dependency (
    distribution TEXT NOT NULL,
    dependency TEXT NOT NULL,
    phase TEXT NOT NULL,
    core REAL NULL,
    PRIMARY KEY (distribution,
    dependency,
    phase),
    FOREIGN KEY (distribution) REFERENCES distribution (distribution),
    FOREIGN KEY (dependency) REFERENCES distribution (distribution)
)

look at those foreign keys pointing back at distribution (distribution). twice. it's committed, it's loyal, it's got range 💜

---

🌈 SUPPORT 🌈

CPANDB::Dependency is part of the CPANDB API.

see the documentation for CPANDB for more info. that's where the lore lives, bestie 📚

---

🎀 AUTHOR 🎀

Adam Kennedy <adamk@cpan.org>

(the icon who wrote this 💅)

---

✨ 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 and that's the whole page, start to finish, no skips 🫶 this was documented for perl v5.36.0 and it's dated 2023-10-01 — so like, shoutout to the past for leaving us this, and shoutout to you for reading the whole thing. go build something cute with it. bye bestie 💖🦋🌸