Debian Codegraph @

upstream/debian-unstable/man3/CPAN::Distroprefs.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "CPAN::Distroprefs 3perl"
58 .TH CPAN::Distroprefs 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 CPAN::Distroprefs \-\- read and match distroprefs
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use CPAN::Distroprefs;
69 \&
70 \& my %info = (... distribution/environment info ...);
71 \&
72 \& my $finder = CPAN::Distroprefs\->find($prefs_dir, \e%ext_map);
73 \&
74 \& while (my $result = $finder\->next) {
75 \&
76 \& die $result\->as_string if $result\->is_fatal;
77 \&
78 \& warn($result\->as_string), next if $result\->is_warning;
79 \&
80 \& for my $pref (@{ $result\->prefs }) {
81 \& if ($pref\->matches(\e%info)) {
82 \& return $pref;
83 \& }
84 \& }
85 \& }
86 .Ve
87 .SH DESCRIPTION
88 .IX Header "DESCRIPTION"
89 This module encapsulates reading Distroprefs and matching them against CPAN distributions.
90 .SH INTERFACE
91 .IX Header "INTERFACE"
92 .Vb 1
93 \& my $finder = CPAN::Distroprefs\->find($dir, \e%ext_map);
94 \&
95 \& while (my $result = $finder\->next) { ... }
96 .Ve
97 .PP
98 Build an iterator which finds distroprefs files in the tree below the
99 given directory. Within the tree directories matching \f(CW\*(C`m/^[._]/\*(C'\fR are
100 pruned.
101 .PP
102 \&\f(CW%ext_map\fR is a hashref whose keys are file extensions and whose values are
103 modules used to load matching files:
104 .PP
105 .Vb 5
106 \& {
107 \& \*(Aqyml\*(Aq => \*(AqYAML::Syck\*(Aq,
108 \& \*(Aqdd\*(Aq => \*(AqData::Dumper\*(Aq,
109 \& ...
110 \& }
111 .Ve
112 .PP
113 Each time \f(CW\*(C`$finder\->next\*(C'\fR is called, the iterator returns one of two
114 possible values:
115 .IP \(bu 4
116 a CPAN::Distroprefs::Result object
117 .IP \(bu 4
118 \&\f(CW\*(C`undef\*(C'\fR, indicating that no prefs files remain to be found
119 .SH RESULTS
120 .IX Header "RESULTS"
121 \&\f(CWfind()\fR returns CPAN::Distroprefs::Result objects to
122 indicate success or failure when reading a prefs file.
123 .SS Common
124 .IX Subsection "Common"
125 All results share some common attributes:
126 .PP
127 \fItype\fR
128 .IX Subsection "type"
129 .PP
130 \&\f(CW\*(C`success\*(C'\fR, \f(CW\*(C`warning\*(C'\fR, or \f(CW\*(C`fatal\*(C'\fR
131 .PP
132 \fIfile\fR
133 .IX Subsection "file"
134 .PP
135 the file from which these prefs were read, or to which this error refers (relative filename)
136 .PP
137 \fIext\fR
138 .IX Subsection "ext"
139 .PP
140 the file's extension, which determines how to load it
141 .PP
142 \fIdir\fR
143 .IX Subsection "dir"
144 .PP
145 the directory the file was read from
146 .PP
147 \fIabs\fR
148 .IX Subsection "abs"
149 .PP
150 the absolute path to the file
151 .SS Errors
152 .IX Subsection "Errors"
153 Error results (warning and fatal) contain:
154 .PP
155 \fImsg\fR
156 .IX Subsection "msg"
157 .PP
158 the error message (usually either \f(CW$!\fR or a YAML error)
159 .SS Successes
160 .IX Subsection "Successes"
161 Success results contain:
162 .PP
163 \fIprefs\fR
164 .IX Subsection "prefs"
165 .PP
166 an arrayref of CPAN::Distroprefs::Pref objects
167 .SH PREFS
168 .IX Header "PREFS"
169 CPAN::Distroprefs::Pref objects represent individual distroprefs documents.
170 They are constructed automatically as part of \f(CW\*(C`success\*(C'\fR results from \f(CWfind()\fR.
171 .PP
172 \fIdata\fR
173 .IX Subsection "data"
174 .PP
175 the pref information as a hashref, suitable for e.g. passing to Kwalify
176 .PP
177 \fImatch_attributes\fR
178 .IX Subsection "match_attributes"
179 .PP
180 returns a list of the valid match attributes (see the Distroprefs section in CPAN)
181 .PP
182 currently: \f(CW\*(C`env perl perlconfig distribution module\*(C'\fR
183 .PP
184 \fIhas_any_match\fR
185 .IX Subsection "has_any_match"
186 .PP
187 true if this pref has a 'match' attribute at all
188 .PP
189 \fIhas_valid_subkeys\fR
190 .IX Subsection "has_valid_subkeys"
191 .PP
192 true if this pref has a 'match' attribute and at least one valid match attribute
193 .PP
194 \fImatches\fR
195 .IX Subsection "matches"
196 .PP
197 .Vb 1
198 \& if ($pref\->matches(\e%arg)) { ... }
199 .Ve
200 .PP
201 true if this pref matches the passed-in hashref, which must have a value for
202 each of the \f(CW\*(C`match_attributes\*(C'\fR (above)
203 .SH LICENSE
204 .IX Header "LICENSE"
205 This program is free software; you can redistribute it and/or modify it under
206 the same terms as Perl itself.