--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "General::Extended 3"
+.TH General::Extended 3 "2009-07-15" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Config::General::Extended \- Extended access to Config files
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use Config::General;
+.Ve
+.PP
+.Vb 4
+\& $conf = new Config::General(
+\& \-ConfigFile => 'configfile',
+\& \-ExtendedAccess => 1
+\& );
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+This is an internal module which makes it possible to use object
+oriented methods to access parts of your config file.
+.PP
+Normally you don't call it directly.
+.SH "METHODS"
+.IX Header "METHODS"
+.IP "configfile('filename')" 4
+.IX Item "configfile('filename')"
+Set the filename to be used by \fBsave\fR to \*(L"filename\*(R". It returns the current
+configured filename if called without arguments.
+.IP "obj('key')" 4
+.IX Item "obj('key')"
+Returns a new object (of Config::General::Extended Class) from the given key.
+Short example:
+Assume you have the following config:
+.Sp
+.Vb 13
+\& <individual>
+\& <martin>
+\& age 23
+\& </martin>
+\& <joseph>
+\& age 56
+\& </joseph>
+\& </individual>
+\& <other>
+\& blah blubber
+\& blah gobble
+\& leer
+\& </other>
+.Ve
+.Sp
+and already read it in using \fB\f(BIConfig::General::Extended::new()\fB\fR, then you can get a
+new object from the \*(L"individual\*(R" block this way:
+.Sp
+.Vb 1
+\& $individual = $conf\->obj("individual");
+.Ve
+.Sp
+Now if you call \fBgetall\fR on \fI$individual\fR (just for reference) you would get:
+.Sp
+.Vb 3
+\& $VAR1 = (
+\& martin => { age => 13 }
+\& );
+.Ve
+.Sp
+Or, here is another use:
+.Sp
+.Vb 5
+\& my $individual = $conf\->obj("individual");
+\& foreach my $person ($conf\->keys("individual")) {
+\& $man = $individual\->obj($person);
+\& print "$person is " . $man\->value("age") . " years old\en";
+\& }
+.Ve
+.Sp
+See the discussion on \fB\f(BIhash()\fB\fR and \fB\f(BIvalue()\fB\fR below.
+.Sp
+If the key from which you want to create a new object is empty, an empty
+object will be returned. If you run the following on the above config:
+.Sp
+.Vb 1
+\& $obj = $conf\->obj("other")\->obj("leer");
+.Ve
+.Sp
+Then \f(CW$obj\fR will be empty, just like if you have had run this:
+.Sp
+.Vb 1
+\& $obj = new Config::General::Extended( () );
+.Ve
+.Sp
+Read operations on this empty object will return nothing or even fail.
+But you can use an empty object for \fIcreating\fR a new config using write
+operations, i.e.:
+.Sp
+.Vb 1
+\& $obj\->someoption("value");
+.Ve
+.Sp
+See the discussion on \fB\s-1AUTOLOAD\s0 \s-1METHODS\s0\fR below.
+.Sp
+If the key points to a list of hashes, a list of objects will be
+returned. Given the following example config:
+.Sp
+.Vb 6
+\& <option>
+\& name = max
+\& </option>
+\& <option>
+\& name = bea
+\& </option>
+.Ve
+.Sp
+you could write code like this to access the list the \s-1OOP\s0 way:
+.Sp
+.Vb 4
+\& my $objlist = $conf\->obj("option");
+\& foreach my $option (@{$objlist}) {
+\& print $option\->name;
+\& }
+.Ve
+.Sp
+Please note that the list will be returned as a reference to an array.
+.Sp
+Empty elements or non-hash elements of the list, if any, will be skipped.
+.IP "hash('key')" 4
+.IX Item "hash('key')"
+This method returns a hash(if it \fBis\fR one!) from the config which is referenced by
+\&\*(L"key\*(R". Given the sample config above you would get:
+.Sp
+.Vb 5
+\& my %sub_hash = $conf\->hash("individual");
+\& print Dumper(\e%sub_hash);
+\& $VAR1 = {
+\& martin => { age => 13 }
+\& };
+.Ve
+.IP "array('key')" 4
+.IX Item "array('key')"
+This the equivalent of \fB\f(BIhash()\fB\fR mentioned above, except that it returns an array.
+Again, we use the sample config mentioned above:
+.Sp
+.Vb 4
+\& $other = $conf\->obj("other");
+\& my @blahs = $other\->array("blah");
+\& print Dumper(\e@blahs);
+\& $VAR1 = [ "blubber", "gobble" ];
+.Ve
+.IP "value('key')" 4
+.IX Item "value('key')"
+This method returns the scalar value of a given key. Given the following sample
+config:
+.Sp
+.Vb 2
+\& name = arthur
+\& age = 23
+.Ve
+.Sp
+you could do something like that:
+.Sp
+.Vb 1
+\& print $conf\->value("name") . " is " . $conf\->value("age") . " years old\en";
+.Ve
+.Sp
+You can use this method also to set the value of \*(L"key\*(R" to something if you give over
+a hash reference, array reference or a scalar in addition to the key. An example:
+.Sp
+.Vb 5
+\& $conf\->value("key", \e%somehash);
+\& # or
+\& $conf\->value("key", \e@somearray);
+\& # or
+\& $conf\->value("key", $somescalar);
+.Ve
+.Sp
+Please note, that this method does not complain about existing values within \*(L"key\*(R"!
+.IP "is_hash('key') is_array('key') is_scalar('key')" 4
+.IX Item "is_hash('key') is_array('key') is_scalar('key')"
+As seen above, you can access parts of your current config using hash, array or scalar
+methods. But you are right if you guess, that this might become problematic, if
+for example you call \fB\f(BIhash()\fB\fR on a key which is in real not a hash but a scalar. Under
+normal circumstances perl would refuse this and die.
+.Sp
+To avoid such behavior you can use one of the methods \fIis_hash()\fR \fIis_array()\fR \fIis_scalar()\fR to
+check if the value of \*(L"key\*(R" is really what you expect it to be.
+.Sp
+An example(based on the config example from above):
+.Sp
+.Vb 6
+\& if($conf\->is_hash("individual") {
+\& $individual = $conf\->obj("individual");
+\& }
+\& else {
+\& die "You need to configure a "individual" block!\en";
+\& }
+.Ve
+.IP "exists('key')" 4
+.IX Item "exists('key')"
+This method returns just true if the given key exists in the config.
+.IP "keys('key')" 4
+.IX Item "keys('key')"
+Returns an array of the keys under the specified \*(L"key\*(R". If you use the example
+config above you yould do that:
+.Sp
+.Vb 2
+\& print Dumper($conf\->keys("individual");
+\& $VAR1 = [ "martin", "joseph" ];
+.Ve
+.Sp
+If no key name was supplied, then the keys of the object itself will be returned.
+.Sp
+You can use this method in \fBforeach\fR loops as seen in an example above(\fIobj()\fR ).
+.IP "delete ('key')" 4
+.IX Item "delete ('key')"
+This method removes the given key and all associated data from the internal
+hash structure. If 'key' contained data, then this data will be returned,
+otherwise undef will be returned.
+.SH "AUTOLOAD METHODS"
+.IX Header "AUTOLOAD METHODS"
+Another usefull feature is implemented in this class using the \fB\s-1AUTOLOAD\s0\fR feature
+of perl. If you know the keynames of a block within your config, you can access to
+the values of each individual key using the method notation. See the following example
+and you will get it:
+.PP
+We assume the following config:
+.PP
+.Vb 5
+\& <person>
+\& name = Moser
+\& prename = Peter
+\& birth = 12.10.1972
+\& </person>
+.Ve
+.PP
+Now we read it in and process it:
+.PP
+.Vb 3
+\& my $conf = new Config::General::Extended("configfile");
+\& my $person = $conf\->obj("person");
+\& print $person\->prename . " " . $person\->name . " is " . $person\->age . " years old\en";
+.Ve
+.PP
+This notation supports only scalar values! You need to make sure, that the block
+<person> does not contain any subblock or multiple identical options(which will become
+an array after parsing)!
+.PP
+If you access a non-existent key this way, Config::General will croak an error.
+You can turn this behavior off by setting \fB\-StrictObjects\fR to 0 or \*(L"no\*(R". In
+this case undef will be returned.
+.PP
+Of course you can use this kind of methods for writing data too:
+.PP
+.Vb 1
+\& $person\->name("Neustein");
+.Ve
+.PP
+This changes the value of the \*(L"name\*(R" key to \*(L"Neustein\*(R". This feature behaves exactly like
+\&\fB\f(BIvalue()\fB\fR, which means you can assign hash or array references as well and that existing
+values under the given key will be overwritten.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 2000\-2008 Thomas Linden
+.PP
+This library is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+.SH "BUGS"
+.IX Header "BUGS"
+none known yet.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Thomas Linden <tlinden |AT| cpan.org>
+.SH "VERSION"
+.IX Header "VERSION"
+2.03
projects / catagits/Gitalist.git / blobdiff