1CPAN::Distroprefs(3)  User Contributed Perl Documentation CPAN::Distroprefs(3)
2
3
4

NAME

6       CPAN::Distroprefs -- read and match distroprefs
7

SYNOPSIS

9           use CPAN::Distroprefs;
10
11           my %info = (... distribution/environment info ...);
12
13           my $finder = CPAN::Distroprefs->find($prefs_dir, \%ext_map);
14
15           while (my $result = $finder->next) {
16
17               die $result->as_string if $result->is_fatal;
18
19               warn($result->as_string), next if $result->is_warning;
20
21               for my $pref (@{ $result->prefs }) {
22                   if ($pref->matches(\%info)) {
23                       return $pref;
24                   }
25               }
26           }
27

DESCRIPTION

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

INTERFACE

33           my $finder = CPAN::Distroprefs->find($dir, \%ext_map);
34
35           while (my $result = $finder->next) { ... }
36
37       Build an iterator which finds distroprefs files in the tree below the
38       given directory. Within the tree directories matching "m/^[._]/" are
39       pruned.
40
41       %ext_map is a hashref whose keys are file extensions and whose values
42       are modules used to load matching files:
43
44           {
45               'yml' => 'YAML::Syck',
46               'dd'  => 'Data::Dumper',
47               ...
48           }
49
50       Each time "$finder->next" is called, the iterator returns one of two
51       possible values:
52
53       •   a CPAN::Distroprefs::Result object
54
55       •   "undef", indicating that no prefs files remain to be found
56

RESULTS

58       "find()" returns CPAN::Distroprefs::Result objects to indicate success
59       or failure when reading a prefs file.
60
61   Common
62       All results share some common attributes:
63
64       type
65
66       "success", "warning", or "fatal"
67
68       file
69
70       the file from which these prefs were read, or to which this error
71       refers (relative filename)
72
73       ext
74
75       the file's extension, which determines how to load it
76
77       dir
78
79       the directory the file was read from
80
81       abs
82
83       the absolute path to the file
84
85   Errors
86       Error results (warning and fatal) contain:
87
88       msg
89
90       the error message (usually either $! or a YAML error)
91
92   Successes
93       Success results contain:
94
95       prefs
96
97       an arrayref of CPAN::Distroprefs::Pref objects
98

PREFS

100       CPAN::Distroprefs::Pref objects represent individual distroprefs
101       documents.  They are constructed automatically as part of "success"
102       results from "find()".
103
104       data
105
106       the pref information as a hashref, suitable for e.g. passing to Kwalify
107
108       match_attributes
109
110       returns a list of the valid match attributes (see the Distroprefs
111       section in CPAN)
112
113       currently: "env perl perlconfig distribution module"
114
115       has_any_match
116
117       true if this pref has a 'match' attribute at all
118
119       has_valid_subkeys
120
121       true if this pref has a 'match' attribute and at least one valid match
122       attribute
123
124       matches
125
126         if ($pref->matches(\%arg)) { ... }
127
128       true if this pref matches the passed-in hashref, which must have a
129       value for each of the "match_attributes" (above)
130

LICENSE

132       This program is free software; you can redistribute it and/or modify it
133       under the same terms as Perl itself.
134
135
136
137perl v5.36.0                      2022-07-22              CPAN::Distroprefs(3)