CPAN::Distroprefs -- read and match distroprefs

- NAME
- SYNOPSIS
- DESCRIPTION
- INTERFACE
- RESULTS
  - Common
    - type
    - file
    - ext
    - dir
    - abs
  - Errors
    - msg
  - Successes
    - prefs
- PREFS
  - - data
    - match_attributes
    - has_any_match
    - has_valid_subkeys
    - matches
- LICENSE

# NAME

CPAN::Distroprefs -- read and match distroprefs

# 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

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

# 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

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

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

Error results (warning and fatal) contain:

### msg

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

## 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()`.

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

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

CPAN::Distroprefs -- read and match distroprefs