CPAN::Distroprefs(3pm) Perl Programmers Reference Guide CPAN::Distroprefs(3pm)

# [NAME](#NAME)

CPAN::Distroprefs -- read and match distroprefs

# [SYNOPSIS](#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;
            }
        }
    }
```

# [DESCRIPTION](#DESCRIPTION)

This module encapsulates reading Distroprefs and matching them against CPAN distributions.

# [INTERFACE](#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. Within the tree directories matching "m/^\[.\_]/" are pruned.

%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',
        ...
    }
```

Each time "$finder->next" is called, the iterator returns one of two possible values:

- a CPAN::Distroprefs::Result object
- "undef", indicating that no prefs files remain to be found

# [RESULTS](#RESULTS)

find() returns CPAN::Distroprefs::Result objects to indicate success or failure when reading a prefs file.

## [Common](#Common)

All results share some common attributes:

*type*

"success", "warning", or "fatal"

*file*

the file from which these prefs were read, or to which this error refers (relative filename)

*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

## [Errors](#Errors)

Error results (warning and fatal) contain:

*msg*

the error message (usually either $! or a YAML error)

## [Successes](#Successes)

Success results contain:

*prefs*

an arrayref of CPAN::Distroprefs::Pref objects

# [PREFS](#PREFS)

CPAN::Distroprefs::Pref objects represent individual distroprefs documents. They are constructed automatically as part of "success" results from find().

*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*

```
  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)

# [LICENSE](#LICENSE)

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

2026-10-21 perl v5.44.0

---

Document: CPAN::Distroprefs(3pm) from perl 5.44.0-r2 (Chainguard OS)
Source: https://github.com/Perl/perl5.git