local-lib5/man/man3/Config::General::Extended.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 "General::Extended 3"
 132 .TH General::Extended 3 "2009-07-15" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Config::General::Extended \- Extended access to Config files
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \& use Config::General;
 139 .Ve
 140 .PP
 141 .Vb 4
 142 \& $conf = new Config::General(
 143 \&    \-ConfigFile     => 'configfile',
 144 \&    \-ExtendedAccess => 1
 145 \& );
 146 .Ve
 147 .SH "DESCRIPTION"
 148 .IX Header "DESCRIPTION"
 149 This is an internal module which makes it possible to use object
 150 oriented methods to access parts of your config file.
 151 .PP
 152 Normally you don't call it directly.
 153 .SH "METHODS"
 154 .IX Header "METHODS"
 155 .IP "configfile('filename')" 4
 156 .IX Item "configfile('filename')"
 157 Set the filename to be used by \fBsave\fR to \*(L"filename\*(R". It returns the current
 158 configured filename if called without arguments.
 159 .IP "obj('key')" 4
 160 .IX Item "obj('key')"
 161 Returns a new object (of Config::General::Extended Class) from the given key.
 162 Short example:
 163 Assume you have the following config:
 164 .Sp
 165 .Vb 13
 166 \& <individual>
 167 \&      <martin>
 168 \&         age   23
 169 \&      </martin>
 170 \&      <joseph>
 171 \&         age   56
 172 \&      </joseph>
 173 \& </individual>
 174 \& <other>
 175 \&      blah     blubber
 176 \&      blah     gobble
 177 \&      leer
 178 \& </other>
 179 .Ve
 180 .Sp
 181 and already read it in using \fB\f(BIConfig::General::Extended::new()\fB\fR, then you can get a
 182 new object from the \*(L"individual\*(R" block this way:
 183 .Sp
 184 .Vb 1
 185 \& $individual = $conf\->obj("individual");
 186 .Ve
 187 .Sp
 188 Now if you call \fBgetall\fR on \fI$individual\fR (just for reference) you would get:
 189 .Sp
 190 .Vb 3
 191 \& $VAR1 = (
 192 \&    martin => { age => 13 }
 193 \&         );
 194 .Ve
 195 .Sp
 196 Or, here is another use:
 197 .Sp
 198 .Vb 5
 199 \& my $individual = $conf\->obj("individual");
 200 \& foreach my $person ($conf\->keys("individual")) {
 201 \&    $man = $individual\->obj($person);
 202 \&    print "$person is " . $man\->value("age") . " years old\en";
 203 \& }
 204 .Ve
 205 .Sp
 206 See the discussion on \fB\f(BIhash()\fB\fR and \fB\f(BIvalue()\fB\fR below.
 207 .Sp
 208 If the key from which you want to create a new object is empty, an empty
 209 object will be returned. If you run the following on the above config:
 210 .Sp
 211 .Vb 1
 212 \& $obj = $conf\->obj("other")\->obj("leer");
 213 .Ve
 214 .Sp
 215 Then \f(CW$obj\fR will be empty, just like if you have had run this:
 216 .Sp
 217 .Vb 1
 218 \& $obj = new Config::General::Extended( () );
 219 .Ve
 220 .Sp
 221 Read operations on this empty object will return nothing or even fail.
 222 But you can use an empty object for \fIcreating\fR a new config using write
 223 operations, i.e.:
 224 .Sp
 225 .Vb 1
 226 \& $obj\->someoption("value");
 227 .Ve
 228 .Sp
 229 See the discussion on \fB\s-1AUTOLOAD\s0 \s-1METHODS\s0\fR below.
 230 .Sp
 231 If the key points to a list of hashes, a list of objects will be
 232 returned. Given the following example config:
 233 .Sp
 234 .Vb 6
 235 \& <option>
 236 \&   name = max
 237 \& </option>
 238 \& <option>
 239 \&   name = bea
 240 \& </option>
 241 .Ve
 242 .Sp
 243 you could write code like this to access the list the \s-1OOP\s0 way:
 244 .Sp
 245 .Vb 4
 246 \& my $objlist = $conf\->obj("option");
 247 \& foreach my $option (@{$objlist}) {
 248 \&  print $option\->name;
 249 \& }
 250 .Ve
 251 .Sp
 252 Please note that the list will be returned as a reference to an array.
 253 .Sp
 254 Empty elements or non-hash elements of the list, if any, will be skipped.
 255 .IP "hash('key')" 4
 256 .IX Item "hash('key')"
 257 This method returns a hash(if it \fBis\fR one!) from the config which is referenced by
 258 \&\*(L"key\*(R". Given the sample config above you would get:
 259 .Sp
 260 .Vb 5
 261 \& my %sub_hash = $conf\->hash("individual");
 262 \& print Dumper(\e%sub_hash);
 263 \& $VAR1 = {
 264 \&    martin => { age => 13 }
 265 \&         };
 266 .Ve
 267 .IP "array('key')" 4
 268 .IX Item "array('key')"
 269 This the equivalent of \fB\f(BIhash()\fB\fR mentioned above, except that it returns an array.
 270 Again, we use the sample config mentioned above:
 271 .Sp
 272 .Vb 4
 273 \& $other = $conf\->obj("other");
 274 \& my @blahs = $other\->array("blah");
 275 \& print Dumper(\e@blahs);
 276 \& $VAR1 = [ "blubber", "gobble" ];
 277 .Ve
 278 .IP "value('key')" 4
 279 .IX Item "value('key')"
 280 This method returns the scalar value of a given key. Given the following sample
 281 config:
 282 .Sp
 283 .Vb 2
 284 \& name  = arthur
 285 \& age   = 23
 286 .Ve
 287 .Sp
 288 you could do something like that:
 289 .Sp
 290 .Vb 1
 291 \& print $conf\->value("name") . " is " . $conf\->value("age") . " years old\en";
 292 .Ve
 293 .Sp
 294 You can use this method also to set the value of \*(L"key\*(R" to something if you give over
 295 a hash reference, array reference or a scalar in addition to the key. An example:
 296 .Sp
 297 .Vb 5
 298 \& $conf\->value("key", \e%somehash);
 299 \& # or
 300 \& $conf\->value("key", \e@somearray);
 301 \& # or
 302 \& $conf\->value("key", $somescalar);
 303 .Ve
 304 .Sp
 305 Please note, that this method does not complain about existing values within \*(L"key\*(R"!
 306 .IP "is_hash('key') is_array('key') is_scalar('key')" 4
 307 .IX Item "is_hash('key') is_array('key') is_scalar('key')"
 308 As seen above, you can access parts of your current config using hash, array or scalar
 309 methods. But you are right if you guess, that this might become problematic, if
 310 for example you call \fB\f(BIhash()\fB\fR on a key which is in real not a hash but a scalar. Under
 311 normal circumstances perl would refuse this and die.
 312 .Sp
 313 To avoid such behavior you can use one of the methods \fIis_hash()\fR \fIis_array()\fR \fIis_scalar()\fR to
 314 check if the value of \*(L"key\*(R" is really what you expect it to be.
 315 .Sp
 316 An example(based on the config example from above):
 317 .Sp
 318 .Vb 6
 319 \& if($conf\->is_hash("individual") {
 320 \&    $individual = $conf\->obj("individual");
 321 \& }
 322 \& else {
 323 \&    die "You need to configure a "individual" block!\en";
 324 \& }
 325 .Ve
 326 .IP "exists('key')" 4
 327 .IX Item "exists('key')"
 328 This method returns just true if the given key exists in the config.
 329 .IP "keys('key')" 4
 330 .IX Item "keys('key')"
 331 Returns an array of the keys under the specified \*(L"key\*(R". If you use the example
 332 config above you yould do that:
 333 .Sp
 334 .Vb 2
 335 \& print Dumper($conf\->keys("individual");
 336 \& $VAR1 = [ "martin", "joseph" ];
 337 .Ve
 338 .Sp
 339 If no key name was supplied, then the keys of the object itself will be returned.
 340 .Sp
 341 You can use this method in \fBforeach\fR loops as seen in an example above(\fIobj()\fR ).
 342 .IP "delete ('key')" 4
 343 .IX Item "delete ('key')"
 344 This method removes the given key and all associated data from the internal
 345 hash structure. If 'key' contained data, then this data will be returned,
 346 otherwise undef will be returned.
 347 .SH "AUTOLOAD METHODS"
 348 .IX Header "AUTOLOAD METHODS"
 349 Another usefull feature is implemented in this class using the \fB\s-1AUTOLOAD\s0\fR feature
 350 of perl. If you know the keynames of a block within your config, you can access to
 351 the values of each individual key using the method notation. See the following example
 352 and you will get it:
 353 .PP
 354 We assume the following config:
 355 .PP
 356 .Vb 5
 357 \& <person>
 358 \&    name    = Moser
 359 \&    prename = Peter
 360 \&    birth   = 12.10.1972
 361 \& </person>
 362 .Ve
 363 .PP
 364 Now we read it in and process it:
 365 .PP
 366 .Vb 3
 367 \& my $conf = new Config::General::Extended("configfile");
 368 \& my $person = $conf\->obj("person");
 369 \& print $person\->prename . " " . $person\->name . " is " . $person\->age . " years old\en";
 370 .Ve
 371 .PP
 372 This notation supports only scalar values! You need to make sure, that the block
 373 <person> does not contain any subblock or multiple identical options(which will become
 374 an array after parsing)!
 375 .PP
 376 If you access a non-existent key this way, Config::General will croak an error.
 377 You can turn this behavior off by setting \fB\-StrictObjects\fR to 0 or \*(L"no\*(R". In
 378 this case undef will be returned.
 379 .PP
 380 Of course you can use this kind of methods for writing data too:
 381 .PP
 382 .Vb 1
 383 \& $person\->name("Neustein");
 384 .Ve
 385 .PP
 386 This changes the value of the \*(L"name\*(R" key to \*(L"Neustein\*(R". This feature behaves exactly like
 387 \&\fB\f(BIvalue()\fB\fR, which means you can assign hash or array references as well and that existing
 388 values under the given key will be overwritten.
 389 .SH "COPYRIGHT"
 390 .IX Header "COPYRIGHT"
 391 Copyright (c) 2000\-2008 Thomas Linden
 392 .PP
 393 This library is free software; you can redistribute it and/or
 394 modify it under the same terms as Perl itself.
 395 .SH "BUGS"
 396 .IX Header "BUGS"
 397 none known yet.
 398 .SH "AUTHOR"
 399 .IX Header "AUTHOR"
 400 Thomas Linden <tlinden |AT| cpan.org>
 401 .SH "VERSION"
 402 .IX Header "VERSION"
 403 2.03