local-lib5/man/man3/CPAN::Distroprefs.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "CPAN::Distroprefs 3"
 132 .TH CPAN::Distroprefs 3 "2009-05-01" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 CPAN::Distroprefs \-\- read and match distroprefs
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    use CPAN::Distroprefs;
 139 .Ve
 140 .PP
 141 .Vb 1
 142 \&    my %info = (... distribution/environment info ...);
 143 .Ve
 144 .PP
 145 .Vb 1
 146 \&    my $finder = CPAN::Distroprefs\->find($prefs_dir, \e%ext_map);
 147 .Ve
 148 .PP
 149 .Vb 1
 150 \&    while (my $result = $finder\->next) {
 151 .Ve
 152 .PP
 153 .Vb 1
 154 \&        die $result\->as_string if $result\->is_fatal;
 155 .Ve
 156 .PP
 157 .Vb 1
 158 \&        warn($result\->as_string), next if $result\->is_warning;
 159 .Ve
 160 .PP
 161 .Vb 6
 162 \&        for my $pref (@{ $result\->prefs }) {
 163 \&            if ($pref\->matches(\e%info)) {
 164 \&                return $pref;
 165 \&            }
 166 \&        }
 167 \&    }
 168 .Ve
 169 .SH "DESCRIPTION"
 170 .IX Header "DESCRIPTION"
 171 This module encapsulates reading Distroprefs and matching them against \s-1CPAN\s0 distributions.
 172 .SH "INTERFACE"
 173 .IX Header "INTERFACE"
 174 .Vb 1
 175 \&    my $finder = CPAN::Distroprefs\->find($dir, \e%ext_map);
 176 .Ve
 177 .PP
 178 .Vb 1
 179 \&    while (my $result = $finder\->next) { ... }
 180 .Ve
 181 .PP
 182 Build an iterator which finds distroprefs files in the given directory.
 183 .PP
 184 \&\f(CW%ext_map\fR is a hashref whose keys are file extensions and whose values are
 185 modules used to load matching files:
 186 .PP
 187 .Vb 5
 188 \&    {
 189 \&        'yml' => 'YAML::Syck',
 190 \&        'dd'  => 'Data::Dumper',
 191 \&        ...
 192 \&    }
 193 .Ve
 194 .PP
 195 Each time \f(CW\*(C`$finder\->next\*(C'\fR is called, the iterator returns one of two
 196 possible values:
 197 .IP "* a CPAN::Distroprefs::Result object" 4
 198 .IX Item "a CPAN::Distroprefs::Result object"
 199 .PD 0
 200 .ie n .IP "* ""undef"", indicating that no prefs files remain to be found" 4
 201 .el .IP "* \f(CWundef\fR, indicating that no prefs files remain to be found" 4
 202 .IX Item "undef, indicating that no prefs files remain to be found"
 203 .PD
 204 .SH "RESULTS"
 205 .IX Header "RESULTS"
 206 \&\f(CW\*(C`find()\*(C'\fR returns CPAN::Distroprefs::Result objects to
 207 indicate success or failure when reading a prefs file.
 208 .Sh "Common"
 209 .IX Subsection "Common"
 210 All results share some common attributes:
 211 .PP
 212 \fItype\fR
 213 .IX Subsection "type"
 214 .PP
 215 \&\f(CW\*(C`success\*(C'\fR, \f(CW\*(C`warning\*(C'\fR, or \f(CW\*(C`fatal\*(C'\fR
 216 .PP
 217 \fIfile\fR
 218 .IX Subsection "file"
 219 .PP
 220 the file from which these prefs were read, or to which this error refers (relative filename)
 221 .PP
 222 \fIext\fR
 223 .IX Subsection "ext"
 224 .PP
 225 the file's extension, which determines how to load it
 226 .PP
 227 \fIdir\fR
 228 .IX Subsection "dir"
 229 .PP
 230 the directory the file was read from
 231 .PP
 232 \fIabs\fR
 233 .IX Subsection "abs"
 234 .PP
 235 the absolute path to the file
 236 .Sh "Errors"
 237 .IX Subsection "Errors"
 238 Error results (warning and fatal) contain:
 239 .PP
 240 \fImsg\fR
 241 .IX Subsection "msg"
 242 .PP
 243 the error message (usually either \f(CW$!\fR or a \s-1YAML\s0 error)
 244 .Sh "Successes"
 245 .IX Subsection "Successes"
 246 Success results contain:
 247 .PP
 248 \fIprefs\fR
 249 .IX Subsection "prefs"
 250 .PP
 251 an arrayref of CPAN::Distroprefs::Pref objects
 252 .SH "PREFS"
 253 .IX Header "PREFS"
 254 CPAN::Distroprefs::Pref objects represent individual distroprefs documents.
 255 They are constructed automatically as part of \f(CW\*(C`success\*(C'\fR results from \f(CW\*(C`find()\*(C'\fR.
 256 .PP
 257 \fIdata\fR
 258 .IX Subsection "data"
 259 .PP
 260 the pref information as a hashref, suitable for e.g. passing to Kwalify
 261 .PP
 262 \fImatch_attributes\fR
 263 .IX Subsection "match_attributes"
 264 .PP
 265 returns a list of the valid match attributes (see the Distroprefs section in \s-1CPAN\s0)
 266 .PP
 267 currently: \f(CW\*(C`env perl perlconfig distribution module\*(C'\fR
 268 .PP
 269 \fIhas_any_match\fR
 270 .IX Subsection "has_any_match"
 271 .PP
 272 true if this pref has a 'match' attribute at all
 273 .PP
 274 \fIhas_valid_subkeys\fR
 275 .IX Subsection "has_valid_subkeys"
 276 .PP
 277 true if this pref has a 'match' attribute and at least one valid match attribute
 278 .PP
 279 \fImatches\fR
 280 .IX Subsection "matches"
 281 .PP
 282 .Vb 1
 283 \&  if ($pref\->matches(\e%arg)) { ... }
 284 .Ve
 285 .PP
 286 true if this pref matches the passed-in hashref, which must have a value for
 287 each of the \f(CW\*(C`match_attributes\*(C'\fR (above)
 288 .SH "LICENSE"
 289 .IX Header "LICENSE"
 290 This program is free software; you can redistribute it and/or modify it under
 291 the same terms as Perl itself.