1General::Extended(3)  User Contributed Perl Documentation General::Extended(3)
2
3
4

NAME

6       Config::General::Extended - Extended access to Config files
7

SYNOPSIS

9        use Config::General;
10
11        $conf = new Config::General(
12           -ConfigFile     => 'configfile',
13           -ExtendedAccess => 1
14        );
15

DESCRIPTION

17       This is an internal module which makes it possible to use object
18       oriented methods to access parts of your config file.
19
20       Normally you don't call it directly.
21

METHODS

23       configfile('filename')
24           Set the filename to be used by save to "filename". It returns the
25           current configured filename if called without arguments.
26
27       obj('key')
28           Returns a new object (of Config::General::Extended Class) from the
29           given key.  Short example: Assume you have the following config:
30
31            <individual>
32                 <martin>
33                    age   23
34                 </martin>
35                 <joseph>
36                    age   56
37                 </joseph>
38            </individual>
39            <other>
40                 blah     blubber
41                 blah     gobble
42                 leer
43            </other>
44
45           and already read it in using Config::General::Extended::new(), then
46           you can get a new object from the "individual" block this way:
47
48            $individual = $conf->obj("individual");
49
50           Now if you call getall on $individual (just for reference) you
51           would get:
52
53            $VAR1 = (
54               martin => { age => 13 }
55                    );
56
57           Or, here is another use:
58
59            my $individual = $conf->obj("individual");
60            foreach my $person ($conf->keys("individual")) {
61               $man = $individual->obj($person);
62               print "$person is " . $man->value("age") . " years old\n";
63            }
64
65           See the discussion on hash() and value() below.
66
67           If the key from which you want to create a new object is empty, an
68           empty object will be returned. If you run the following on the
69           above config:
70
71            $obj = $conf->obj("other")->obj("leer");
72
73           Then $obj will be empty, just like if you have had run this:
74
75            $obj = new Config::General::Extended( () );
76
77           Read operations on this empty object will return nothing or even
78           fail.  But you can use an empty object for creating a new config
79           using write operations, i.e.:
80
81            $obj->someoption("value");
82
83           See the discussion on AUTOLOAD METHODS below.
84
85           If the key points to a list of hashes, a list of objects will be
86           returned. Given the following example config:
87
88            <option>
89              name = max
90            </option>
91            <option>
92              name = bea
93            </option>
94
95           you could write code like this to access the list the OOP way:
96
97            my $objlist = $conf->obj("option");
98            foreach my $option (@{$objlist}) {
99             print $option->name;
100            }
101
102           Please note that the list will be returned as a reference to an
103           array.
104
105           Empty elements or non-hash elements of the list, if any, will be
106           skipped.
107
108       hash('key')
109           This method returns a hash(if it is one!) from the config which is
110           referenced by "key". Given the sample config above you would get:
111
112            my %sub_hash = $conf->hash("individual");
113            print Dumper(\%sub_hash);
114            $VAR1 = {
115               martin => { age => 13 }
116                    };
117
118       array('key')
119           This the equivalent of hash() mentioned above, except that it
120           returns an array.  Again, we use the sample config mentioned above:
121
122            $other = $conf->obj("other");
123            my @blahs = $other->array("blah");
124            print Dumper(\@blahs);
125            $VAR1 = [ "blubber", "gobble" ];
126
127       value('key')
128           This method returns the scalar value of a given key. Given the
129           following sample config:
130
131            name  = arthur
132            age   = 23
133
134           you could do something like that:
135
136            print $conf->value("name") . " is " . $conf->value("age") . " years old\n";
137
138           You can use this method also to set the value of "key" to something
139           if you give over a hash reference, array reference or a scalar in
140           addition to the key. An example:
141
142            $conf->value("key", \%somehash);
143            # or
144            $conf->value("key", \@somearray);
145            # or
146            $conf->value("key", $somescalar);
147
148           Please note, that this method does not complain about existing
149           values within "key"!
150
151       is_hash('key') is_array('key') is_scalar('key')
152           As seen above, you can access parts of your current config using
153           hash, array or scalar methods. But you are right if you guess, that
154           this might become problematic, if for example you call hash() on a
155           key which is in real not a hash but a scalar. Under normal
156           circumstances perl would refuse this and die.
157
158           To avoid such behavior you can use one of the methods is_hash()
159           is_array() is_scalar() to check if the value of "key" is really
160           what you expect it to be.
161
162           An example(based on the config example from above):
163
164            if($conf->is_hash("individual") {
165               $individual = $conf->obj("individual");
166            }
167            else {
168               die "You need to configure a "individual" block!\n";
169            }
170
171       exists('key')
172           This method returns just true if the given key exists in the
173           config.
174
175       keys('key')
176           Returns an array of the keys under the specified "key". If you use
177           the example config above you yould do that:
178
179            print Dumper($conf->keys("individual");
180            $VAR1 = [ "martin", "joseph" ];
181
182           If no key name was supplied, then the keys of the object itself
183           will be returned.
184
185           You can use this method in foreach loops as seen in an example
186           above(obj() ).
187
188       delete ('key')
189           This method removes the given key and all associated data from the
190           internal hash structure. If 'key' contained data, then this data
191           will be returned, otherwise undef will be returned.
192

AUTOLOAD METHODS

194       Another usefull feature is implemented in this class using the AUTOLOAD
195       feature of perl. If you know the keynames of a block within your
196       config, you can access to the values of each individual key using the
197       method notation. See the following example and you will get it:
198
199       We assume the following config:
200
201        <person>
202           name    = Moser
203           prename = Peter
204           birth   = 12.10.1972
205        </person>
206
207       Now we read it in and process it:
208
209        my $conf = new Config::General::Extended("configfile");
210        my $person = $conf->obj("person");
211        print $person->prename . " " . $person->name . " is " . $person->age . " years old\n";
212
213       This notation supports only scalar values! You need to make sure, that
214       the block <person> does not contain any subblock or multiple identical
215       options(which will become an array after parsing)!
216
217       If you access a non-existent key this way, Config::General will croak
218       an error.  You can turn this behavior off by setting -StrictObjects to
219       0 or "no". In this case undef will be returned.
220
221       Of course you can use this kind of methods for writing data too:
222
223        $person->name("Neustein");
224
225       This changes the value of the "name" key to "Neustein". This feature
226       behaves exactly like value(), which means you can assign hash or array
227       references as well and that existing values under the given key will be
228       overwritten.
229
231       Copyright (c) 2000-2010 Thomas Linden
232
233       This library is free software; you can redistribute it and/or modify it
234       under the same terms as Perl itself.
235

BUGS

237       none known yet.
238

AUTHOR

240       Thomas Linden <tlinden |AT| cpan.org>
241

VERSION

243       2.05
244
245
246
247perl v5.12.2                      2010-12-01              General::Extended(3)
Impressum