1General::Extended(3) User Contributed Perl Documentation General::Extended(3)
2
6 Config::General::Extended - Extended access to Config files
7
9 use Config::General;
10 $conf = Config::General->new(
12 -ConfigFile => 'configfile',
13 -ExtendedAccess => 1
14 );
15
17 This is an internal module which makes it possible to use object
18 oriented methods to access parts of your config file.
19 Normally you don't call it directly.
21
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 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 <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 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 $individual = $conf->obj("individual");
49 Now if you call getall on $individual (just for reference) you
51 would get:
52 $VAR1 = (
54 martin => { age => 13 }
55 );
56 Or, here is another use:
58 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 See the discussion on hash() and value() below.
66 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 $obj = $conf->obj("other")->obj("leer");
72 Then $obj will be empty, just like if you have had run this:
74 $obj = Config::General::Extended->new( () );
76 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 $obj->someoption("value");
82 See the discussion on AUTOLOAD METHODS below.
84 If the key points to a list of hashes, a list of objects will be
86 returned. Given the following example config:
87 <option>
89 name = max
90 </option>
91 <option>
92 name = bea
93 </option>
94 you could write code like this to access the list the OOP way:
96 my $objlist = $conf->obj("option");
98 foreach my $option (@{$objlist}) {
99 print $option->name;
100 }
101 Please note that the list will be returned as a reference to an
103 array.
104 Empty elements or non-hash elements of the list, if any, will be
106 skipped.
107 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 my %sub_hash = $conf->hash("individual");
113 print Dumper(\%sub_hash);
114 $VAR1 = {
115 martin => { age => 13 }
116 };
117 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 $other = $conf->obj("other");
123 my @blahs = $other->array("blah");
124 print Dumper(\@blahs);
125 $VAR1 = [ "blubber", "gobble" ];
126 value('key')
128 This method returns the scalar value of a given key. Given the
129 following sample config:
130 name = arthur
132 age = 23
133 you could do something like that:
135 print $conf->value("name") . " is " . $conf->value("age") . " years old\n";
137 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 $conf->value("key", \%somehash);
143 # or
144 $conf->value("key", \@somearray);
145 # or
146 $conf->value("key", $somescalar);
147 Please note, that this method does not complain about existing
149 values within "key"!
150 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 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 An example(based on the config example from above):
163 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 exists('key')
172 This method returns just true if the given key exists in the
173 config.
174 keys('key')
176 Returns an array of the keys under the specified "key". If you use
177 the example config above you could do that:
178 print Dumper($conf->keys("individual");
180 $VAR1 = [ "martin", "joseph" ];
181 If no key name was supplied, then the keys of the object itself
183 will be returned.
184 You can use this method in foreach loops as seen in an example
186 above(obj() ).
187 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
194 Another useful 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 We assume the following config:
200 <person>
202 name = Moser
203 prename = Peter
204 birth = 12.10.1972
205 </person>
206 Now we read it in and process it:
208 my $conf = Config::General::Extended->new("configfile");
210 my $person = $conf->obj("person");
211 print $person->prename . " " . $person->name . " is " . $person->age . " years old\n";
212 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 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 Of course you can use this kind of methods for writing data too:
222 $person->name("Neustein");
224 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-2013 Thomas Linden
232 This library is free software; you can redistribute it and/or modify it
234 under the same terms as Perl itself.
235
237 none known yet.
238
240 Thomas Linden <tlinden |AT| cpan.org>
241
243 2.06
244perl v5.10.1 2013-07-03 General::Extended(3)