CPAN::DISTROPREFS(3perl)

💖 CPAN::Distroprefs 💖

okay bestie, so this is CPAN::Distroprefs — she reads distroprefs files and matches them against stuff. that's literally her whole job and she does it flawlessly, no cap. 👑

---

✨ SYNOPSIS ✨

use CPAN::Distroprefs;

my %info = (... distribution/environment info ...);

my $finder = CPAN::Distroprefs->find($prefs_dir, \%ext_map);

while (my $result = $finder->next) {

    die $result->as_string if $result->is_fatal;

    warn($result->as_string), next if $result->is_warning;

    for my $pref (@{ $result->prefs }) {
        if ($pref->matches(\%info)) {
            return $pref;
        }
    }
}

like. look at that. gorgeous. 🎀

---

🌸 DESCRIPTION 🌸

This module encapsulates reading Distroprefs and matching them against CPAN distributions. that's it, that's the vibe. she handles the reading, she handles the matching, you just sit there looking pretty. 💅

---

🦋 INTERFACE 🦋

my $finder = CPAN::Distroprefs->find($dir, \%ext_map);

while (my $result = $finder->next) { ... }

Build an iterator which finds distroprefs files in the tree below the given directory. 🧚 and listen — within the tree, directories matching m/^[._]/ are pruned. gone. not invited. bye bestie. 🙈

%ext_map is a hashref whose keys are file extensions and whose values are modules used to load matching files:

{
    'yml' => 'YAML::Syck',
    'dd'  => 'Data::Dumper',
    ...
}

Every single time $finder->next gets called, the iterator returns one of two possible values:

• a CPAN::Distroprefs::Result object, or
• undef, indicating that no prefs files remain to be found 😭

---

⭐ RESULTS ⭐

find() returns CPAN::Distroprefs::Result objects to indicate success or failure when reading a prefs file. she's giving transparency, she's giving receipts. 💖

💜 Common

All results share some common attributes:

• type — literally one of "success", "warning", or "fatal". that's the whole mood board.
• file — the file from which these prefs were read, or to which this error refers (relative filename, okay)
• ext — the file's extension, which determines how to load it
• dir — the directory the file was read from
• abs — the absolute path to the file, no shortcuts

💀 Errors

Error results (warning and fatal) contain:

• msg — the error message, usually either $! or a YAML error. yeah. YAML errors are a thing and yes they're dramatic. 😭

🔥 Successes

Success results contain:

• prefs — an arrayref of CPAN::Distroprefs::Pref objects ✨

---

🎀 PREFS 🎀

CPAN::Distroprefs::Pref objects represent individual distroprefs documents. They are constructed automatically as part of "success" results from find(). so you don't even have to lift a finger, she does it for you. queen behavior. 👑

• data — the pref information as a hashref, suitable for e.g. passing to Kwalify
• match_attributes — returns a list of the valid match attributes (see the Distroprefs section in CPAN). currently: env perl perlconfig distribution module
• has_any_match — true if this pref has a 'match' attribute at all
• has_valid_subkeys — true if this pref has a 'match' attribute and at least one valid match attribute
• matches — the moment we've all been waiting for:

if ($pref->matches(\%arg)) { ... }

true if this pref matches the passed-in hashref, which must have a value for each of the match_attributes (above). no missing values, bestie, she will notice. ⭐

---

📜 LICENSE 📜

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. so like, share the love, it's literally the rules. 🫶

---

and that's the whole page, bestie!! mwah 💋 this was perl v5.44.0, dated 2026-10-17 — iconic documentation, no notes, periodt. 🌈💖✨