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 find(@list)
194 Given a list of nodes, ->find will search for a tree that branches
195 in just this way, returning the Config::General::Extended object it
196 finds at the bottom if it exists. You can also search partway down
197 the tree and ->find should return where you left off.
198 For example, given the values find (qw (A B C)) and the following
200 tree (</end> tags omitted for brevity):
201 <A>
203 <FOO>
204 ...
205 <B>
206 <BAZ>
207 ...
208 <C>
209 BAR = shoo
210 find() will find the object at C with the value BAR = shoo and
212 return it.
213
215 Another useful feature is implemented in this class using the AUTOLOAD
216 feature of perl. If you know the keynames of a block within your
217 config, you can access to the values of each individual key using the
218 method notation. See the following example and you will get it:
219 We assume the following config:
221 <person>
223 name = Moser
224 prename = Peter
225 birth = 12.10.1972
226 </person>
227 Now we read it in and process it:
229 my $conf = Config::General::Extended->new("configfile");
231 my $person = $conf->obj("person");
232 print $person->prename . " " . $person->name . " is " . $person->age . " years old\n";
233 This notation supports only scalar values! You need to make sure, that
235 the block <person> does not contain any subblock or multiple identical
236 options(which will become an array after parsing)!
237 If you access a non-existent key this way, Config::General will croak
239 an error. You can turn this behavior off by setting -StrictObjects to
240 0 or "no". In this case undef will be returned.
241 Of course you can use this kind of methods for writing data too:
243 $person->name("Neustein");
245 This changes the value of the "name" key to "Neustein". This feature
247 behaves exactly like value(), which means you can assign hash or array
248 references as well and that existing values under the given key will be
249 overwritten.
250
252 Copyright (c) 2000-2014 Thomas Linden
253 This library is free software; you can redistribute it and/or modify it
255 under the same terms as Perl itself.
256
258 none known yet.
259
261 Thomas Linden <tlinden |AT| cpan.org>
262
264 2.07
265perl v5.32.0 2020-07-28 General::Extended(3)