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 = Config::General->new(
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 = Config::General::Extended->new( () );
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 could 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
193       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
199           For example, given the values find (qw (A B C)) and the following
200           tree (</end> tags omitted for brevity):
201
202            <A>
203                   <FOO>
204                           ...
205                   <B>
206                           <BAZ>
207                                   ...
208                           <C>
209                                   BAR = shoo
210
211           find() will find the object at C with the value BAR = shoo and
212           return it.
213

AUTOLOAD METHODS

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
220       We assume the following config:
221
222        <person>
223           name    = Moser
224           prename = Peter
225           birth   = 12.10.1972
226        </person>
227
228       Now we read it in and process it:
229
230        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
234       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
238       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
242       Of course you can use this kind of methods for writing data too:
243
244        $person->name("Neustein");
245
246       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
254       This library is free software; you can redistribute it and/or modify it
255       under the same terms as Perl itself.
256

BUGS

258       none known yet.
259

AUTHOR

261       Thomas Linden <tlinden |AT| cpan.org>
262

VERSION

264       2.07
265
266
267
268perl v5.28.0                      2015-10-22              General::Extended(3)
Impressum