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

CPAN::Distroprefs(3p) Perl Programmers Reference Guide CPAN::Distroprefs(3p) #

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

NNAAMMEE #

 CPAN::Distroprefs -- read and match distroprefs

SSYYNNOOPPSSIISS #

     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;
             }
         }
     }

DDEESSCCRRIIPPTTIIOONN #

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

IINNTTEERRFFAACCEE #

     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

RREESSUULLTTSS #

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

CCoommmmoonn All results share some common attributes:

 _t_y_p_e

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

 _f_i_l_e

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

 _e_x_t

 the file's extension, which determines how to load it

 _d_i_r

 the directory the file was read from

 _a_b_s

 the absolute path to the file

EErrrroorrss Error results (warning and fatal) contain:

 _m_s_g

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

SSuucccceesssseess Success results contain:

 _p_r_e_f_s

 an arrayref of CPAN::Distroprefs::Pref objects

PPRREEFFSS #

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

 _d_a_t_a

 the pref information as a hashref, suitable for e.g. passing to Kwalify

 _m_a_t_c_h___a_t_t_r_i_b_u_t_e_s

 returns a list of the valid match attributes (see the Distroprefs section
 in CPAN)

 currently: "env perl perlconfig distribution module"

 _h_a_s___a_n_y___m_a_t_c_h

 true if this pref has a 'match' attribute at all

 _h_a_s___v_a_l_i_d___s_u_b_k_e_y_s

 true if this pref has a 'match' attribute and at least one valid match
 attribute

 _m_a_t_c_h_e_s

   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)

LLIICCEENNSSEE #

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

perl v5.36.3 2017-02-05 CPAN::Distroprefs(3p)