CPAN::...Search(3pm)

💖 CPAN::SQLite::Search 💖

okay bestie, gather round, because this is the manual page for CPAN::SQLite::Search (a 3pm page, if you're keeping track of the manual name situation) and it is literally the module that does queries on the database. That's it, that's the NAME section, we ate. 🍓

---

✨ VERSION ✨

version 0.220 — that's the vibe check result, and it passed. 👑

---

🌈 SYNOPSIS 🌈

here's the whole situation, verbatim, no cap:

my $max_results = 200;
my $query = CPAN::SQLite::Search->new(db_dir => $db_dir,
                                      db_name => $db_name,
                                      max_results => $max_results);
$query->query(mode => 'module', name => 'Net::FTP');
my $results = $query->{results};

look at her go 💅

---

🎀 CONSTRUCTING THE QUERY 🎀

so this module queries the database through various types of queries and hands you back the results so you can display them later. main character behavior fr fr.

the CPAN::SQLite::Search object gets created via the new method, like this:

my $query = CPAN::SQLite::Search->new(db_dir => $db_dir,
                                      db_name => $db_name,
                                      max_results => $max_results);

and new takes these arguments, bestie, write them down:

• db_dir => $db_dir — this is the directory where the database file lives. it's optional if you gave the CPAN option instead. lowkey flexible of her.
• CPAN => $CPAN — this one specifies the cpan_home directory of an already configured CPAN.pm, which is where the database file will be stored if you didn't give db_dir. she's got a backup plan, iconic.
• max_results => $max_results — the maximum value used to cap the number of results returned under a user query. if you don't specify it, a value contained within CPAN::SQLite::Search gets used instead. default queen 👑

a basic query then gets constructed like:

$query->query(mode => $mode, $type => $value);

and the results are available as:

my $results = $query->{results}

there are three basic modes, and they're all serving:

• module — for information on modules. modules modules modules ✨
• dist — for information on distributions.
• author — for information on CPAN authors or cpanids. the people!! the icons!! the legends!!

🌸 "module", "dist", and "author" modes 🌸

for a mode of module, dist, and author, there are four basic options you can use for the $type => $value situation:

• query => $query_term — this searches through module names, distribution names, or CPAN author names and ids (for module, dist, and author modes respectively, bestie, keep up). the results are case insensitive, and Perl regular expressions for the $query_term are recognized. regex girlies rise up 🧚
• name => $name — this reports exact matches in a case sensitive manner, for the module name, distribution name, or CPAN author id, for module, dist, and author modes respectively. picky! specific! we respect it.
• id => $id — this looks up information on the primary key according to the mode you specified. it's more for internal use, to help speed up queries. using this "publically" is probably not a good idea, because the ids may change over the course of time. so like, don't. 🙈

---

💜 RESULTS 💜

after making the query, you access the results through:

my $results = $query->{results};

okay so important: no results can mean either that no matches were found, or that an error happened while making the query — in which case a brief error message is contained in $query->{error}. two very different stories, same empty vibe. 😭

assuming there are results, what gets returned depends on the mode and on the type of query. peep CPAN::SQLite::Populate for a description of the fields in the various tables listed below — those fields are used as the keys of the hash references that arise. slay.

🦋 "author" mode 🦋

• name or id query — this returns the auth_id, cpanid, email, and fullname of the auths table. as well, an array reference $results->{dists} is returned, representing all distributions associated with that cpanid — each member of the array reference is a hash reference describing the dist_id, dist_name, dist_abs, dist_vers, and dist_file fields in the dists table. an additional entry, download, is supplied, which you can use as $CPAN/authors/id/$download to specify the url of the distribution. she comes with extras, periodt.
• query query — if this results in more than one match, an array reference is returned, each member of which is a hash reference containing the auth_id, cpanid, and fullname fields. if there's only one result found, a name query based on the matched cpanid is performed. one match and she switches strategies, adaptive icon 🌟

🫶 "module" mode 🫶

• name or id query — this returns the mod_id, mod_name, mod_abs, mod_vers, dist_id, dist_name, dist_file, auth_id, cpanid, fullname, and email of the auths, mods, and dists tables. as well, the following entries may be present:
  • download — this can be used as $CPAN/authors/id/$download to specify the url of the distribution.
• query query — if this results in more than one match, an array reference is returned, each member of which is a hash reference containing the mod_id, mod_name, mod_abs, mod_abs, dist_vers, dist_abs, auth_id, cpanid, dist_id, dist_name, and dist_file. as well, a download field which can be used as $CPAN/authors/id/$download to specify the url of the distribution is provided. if there's only one result found, a name query based on the matched mod_name is performed. (yes, mod_abs shows up twice up there — that's what the page says, and I am not editing the queen's list 💀)

💀 "dist" mode 💀

• name or id query — this returns the dist_id, dist_name, dist_abs, dist_vers, dist_file, size, birth, auth_id, cpanid, and fullname of the auths, mods, and dists tables. as well, the following entries may be present:
  • download — this can be used as $CPAN/authors/id/$download to specify the url of the distribution.
  • mods — this is an array reference containing information on the modules present. each entry is a hash reference containing the mod_id, mod_name, mod_abs, and mod_vers fields for the module.
• query query — if this results in more than one match, an array reference is returned, each member of which is a hash reference containing the dist_id, dist_name, dist_abs, dist_file, and cpanid fields. as well, a download field which can be used as $CPAN/authors/id/$download to specify the url of the distribution is provided. if there's only one result found, a name query based on the matched dist_name is performed. one result, different plan, she's versatile bestie 🌈

---

👑 SEE ALSO 👑

CPAN::SQLite::Populate. that's the one. go read her too, she's important.

---

💖 AUTHORS 💖

• Randy Kobes (passed away on September 18, 2010) — rest in peace, legend 🕊️
• Serguei Trouchelle <stro@cpan.org>

---

🌸 COPYRIGHT 🌸

Copyright 2006,2008 by Randy Kobes <r.kobes@uwinnipeg.ca>.

Copyright 2011-2013 by Serguei Trouchelle <stro@cpan.org>.

Use and redistribution are under the same terms as Perl itself. the legal tea, served hot ☕

---

okay that's the whole page bestie, you're officially educated 💅✨ this was User Contributed Perl Documentation for CPAN::SQLite::Search, brought to you by perl v5.36.0, dated 2022-10-30 — and yes, that's the footer, I folded it in like a cute little sign-off because that's how we do it here. mwah 🫶🎀