local-lib5/man/man3/Data::OptList.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 "Data::OptList 3"
 132 .TH Data::OptList 3 "2009-01-16" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Data::OptList \- parse and validate simple name/value option pairs
 135 .SH "VERSION"
 136 .IX Header "VERSION"
 137 version 0.104
 138 .SH "SYNOPSIS"
 139 .IX Header "SYNOPSIS"
 140 .Vb 1
 141 \&  use Data::OptList;
 142 .Ve
 143 .PP
 144 .Vb 8
 145 \&  my $options = Data::Optlist::mkopt([
 146 \&    qw(key1 key2 key3 key4),
 147 \&    key5 => { ... },
 148 \&    key6 => [ ... ],
 149 \&    key7 => sub { ... },
 150 \&    key8 => { ... },
 151 \&    key8 => [ ... ],
 152 \&  ]);
 153 .Ve
 154 .PP
 155 \&...is the same thing, more or less, as:
 156 .PP
 157 .Vb 11
 158 \&  my $options = [
 159 \&    [ key1 => undef,        ],
 160 \&    [ key2 => undef,        ],
 161 \&    [ key3 => undef,        ],
 162 \&    [ key4 => undef,        ],
 163 \&    [ key5 => { ... },      ],
 164 \&    [ key6 => [ ... ],      ],
 165 \&    [ key7 => sub { ... },  ],
 166 \&    [ key8 => { ... },      ],
 167 \&    [ key8 => [ ... ],      ],
 168 \&  ]);
 169 .Ve
 170 .SH "DESCRIPTION"
 171 .IX Header "DESCRIPTION"
 172 Hashes are great for storing named data, but if you want more than one entry
 173 for a name, you have to use a list of pairs.  Even then, this is really boring
 174 to write:
 175 .PP
 176 .Vb 6
 177 \&  $values = [
 178 \&    foo => undef,
 179 \&    bar => undef,
 180 \&    baz => undef,
 181 \&    xyz => { ... },
 182 \&  ];
 183 .Ve
 184 .PP
 185 Just look at all those undefs!  Don't worry, we can get rid of those:
 186 .PP
 187 .Vb 4
 188 \&  $values = [
 189 \&    map { $_ => undef } qw(foo bar baz),
 190 \&    xyz => { ... },
 191 \&  ];
 192 .Ve
 193 .PP
 194 Aaaauuugh!  We've saved a little typing, but now it requires thought to read,
 195 and thinking is even worse than typing... and it's got a bug!  It looked right,
 196 didn't it?  Well, the \f(CW\*(C`xyz => { ... }\*(C'\fR gets consumed by the map, and we
 197 don't get the data we wanted.
 198 .PP
 199 With Data::OptList, you can do this instead:
 200 .PP
 201 .Vb 4
 202 \&  $values = Data::OptList::mkopt([
 203 \&    qw(foo bar baz),
 204 \&    xyz => { ... },
 205 \&  ]);
 206 .Ve
 207 .PP
 208 This works by assuming that any defined scalar is a name and any reference
 209 following a name is its value.
 210 .SH "FUNCTIONS"
 211 .IX Header "FUNCTIONS"
 212 .Sh "mkopt"
 213 .IX Subsection "mkopt"
 214 .Vb 6
 215 \&  my $opt_list = Data::OptList::mkopt(
 216 \&    $input,
 217 \&    $moniker,
 218 \&    $require_unique,
 219 \&    $must_be,
 220 \&  );
 221 .Ve
 222 .PP
 223 This produces an array of arrays; the inner arrays are name/value pairs.
 224 Values will be either \*(L"undef\*(R" or a reference.
 225 .PP
 226 Valid values for \f(CW$input\fR:
 227 .PP
 228 .Vb 6
 229 \& undef    \-> []
 230 \& hashref  \-> [ [ key1 => value1 ] ... ] # non\-ref values become undef
 231 \& arrayref \-> every value followed by a ref becomes a pair: [ value => ref   ]
 232 \&             every value followed by undef becomes a pair: [ value => undef ]
 233 \&             otherwise, it becomes [ value => undef ] like so:
 234 \&             [ "a", "b", [ 1, 2 ] ] \-> [ [ a => undef ], [ b => [ 1, 2 ] ] ]
 235 .Ve
 236 .PP
 237 \&\f(CW$moniker\fR is a name describing the data, which will be used in error
 238 messages.
 239 .PP
 240 If \f(CW$require_unique\fR is true, an error will be thrown if any name is given
 241 more than once.
 242 .PP
 243 \&\f(CW$must_be\fR is either a scalar or array of scalars; it defines what kind(s) of
 244 refs may be values.  If an invalid value is found, an exception is thrown.  If
 245 no value is passed for this argument, any reference is valid.  If \f(CW$must_be\fR
 246 specifies that values must be \s-1CODE\s0, \s-1HASH\s0, \s-1ARRAY\s0, or \s-1SCALAR\s0, then Params::Util
 247 is used to check whether the given value can provide that interface.
 248 Otherwise, it checks that the given value is an object of the kind.
 249 .PP
 250 In other words:
 251 .PP
 252 .Vb 1
 253 \&  [ qw(SCALAR HASH Object::Known) ]
 254 .Ve
 255 .PP
 256 Means:
 257 .PP
 258 .Vb 1
 259 \&  _SCALAR0($value) or _HASH($value) or _INSTANCE($value, 'Object::Known')
 260 .Ve
 261 .Sh "mkopt_hash"
 262 .IX Subsection "mkopt_hash"
 263 .Vb 1
 264 \&  my $opt_hash = Data::OptList::mkopt_hash($input, $moniker, $must_be);
 265 .Ve
 266 .PP
 267 Given valid \f(CW\*(C`\*(L"mkopt\*(R"\*(C'\fR input, this routine returns a reference to a hash.  It
 268 will throw an exception if any name has more than one value.
 269 .SH "EXPORTS"
 270 .IX Header "EXPORTS"
 271 Both \f(CW\*(C`mkopt\*(C'\fR and \f(CW\*(C`mkopt_hash\*(C'\fR may be exported on request.
 272 .SH "AUTHOR"
 273 .IX Header "AUTHOR"
 274 Ricardo \s-1SIGNES\s0, \f(CW\*(C`<rjbs@cpan.org>\*(C'\fR
 275 .SH "BUGS"
 276 .IX Header "BUGS"
 277 Please report any bugs or feature requests at <http://rt.cpan.org>. I will be
 278 notified, and then you'll automatically be notified of progress on your bug as
 279 I make changes.
 280 .SH "COPYRIGHT"
 281 .IX Header "COPYRIGHT"
 282 Copyright 2006\-2007, Ricardo \s-1SIGNES\s0.  This program is free software;  you can
 283 redistribute it and/or modify it under the same terms as Perl itself.