1CGI::Ex::Conf(3)      User Contributed Perl Documentation     CGI::Ex::Conf(3)
2
3
4

NAME

6       CGI::Ex::Conf - Conf Reader/Writer for many different data format types
7

SYNOPSIS

9           use CGI::Ex::Conf qw(conf_read conf_write);
10
11           my $hash = conf_read("/tmp/foo.yaml");
12
13           conf_write("/tmp/foo.yaml", {key1 => $val1, key2 => $val2});
14
15
16           ### OOP interface
17
18           my $cob = CGI::Ex::Conf->new;
19
20           my $full_path_to_file = "/tmp/foo.val"; # supports ini, sto, val, pl, xml
21           my $hash = $cob->read($file);
22
23           local $cob->{default_ext} = 'conf'; # default anyway
24
25
26           my @paths = qw(/tmp, /home/pauls);
27           local $cob->{paths} = \@paths;
28           my $hash = $cob->read('My::NameSpace');
29           # will look in /tmp/My/NameSpace.conf and /home/pauls/My/NameSpace.conf
30
31
32           my $hash = $cob->read('My::NameSpace', {paths => ['/tmp']});
33           # will look in /tmp/My/NameSpace.conf
34
35
36           local $cob->{directive} = 'MERGE';
37           my $hash = $cob->read('FooSpace');
38           # OR #
39           my $hash = $cob->read('FooSpace', {directive => 'MERGE'});
40           # will return merged hashes from /tmp/FooSpace.conf and /home/pauls/FooSpace.conf
41           # immutable keys are preserved from originating files
42
43
44           local $cob->{directive} = 'FIRST';
45           my $hash = $cob->read('FooSpace');
46           # will return values from first found file in the path.
47
48
49           local $cob->{directive} = 'LAST'; # default behavior
50           my $hash = $cob->read('FooSpace');
51           # will return values from last found file in the path.
52
53
54           ### manipulate $hash
55           $cob->write('FooSpace'); # will write it out the changes
56

DESCRIPTION

58       There are half a million Conf readers out there.  Why not add one more.
59       Actually, this module provides a wrapper around the many file formats
60       and the config modules that can handle them.  It does not introduce any
61       formats of its own.
62
63       This module also provides a preload ability which is useful in
64       conjunction with mod_perl.
65
66       Oh - and it writes too.
67

METHODS

69       "read_ref"
70           Takes a file and optional argument hashref.  Figures out the type
71           of handler to use to read the file, reads it and returns the ref.
72           If you don't need the extended merge functionality, or key
73           fallback, or immutable keys, or path lookup ability - then use this
74           method.  Otherwise - use ->read.
75
76       "read"
77           First argument may be either a perl data structure, yaml string, a
78           full filename, or a file "namespace".
79
80           The second argument can be a hashref of override values (referred
81           to as $args below)..
82
83           If the first argument is a perl data structure, it will be copied
84           one level deep and returned (nested structures will contain the
85           same references).  A yaml string will be parsed and returned.  A
86           full filename will be read using the appropriate handler and
87           returned (a file beginning with a / or ./ or ../ is considered to
88           be a full filename).  A file "namespace" (ie "footer" or
89           "my::config" or "what/ever") will be turned into a filename by
90           looking for that namespace in the paths found either in
91           $args->{paths} or in $self->{paths} or in @DEFAULT_PATHS.
92           @DEFAULT_PATHS is empty by default as is $self->{paths} - read
93           makes no attempt to guess what directories to look in.  If the
94           namespace has no extension the extension listed in
95           $args->{default_ext} or $self->{default_ext} or $DEFAULT_EXT will
96           be used).
97
98             my $ref = $cob->read('My::NameSpace', {
99               paths => [qw(/tmp /usr/data)],
100               default_ext => 'pl',
101             });
102             # would look first for /tmp/My/NameSpace.pl
103             # and then /usr/data/My/NameSpace.pl
104
105             my $ref = $cob->read('foo.sto', {
106               paths => [qw(/tmp /usr/data)],
107               default_ext => 'pl',
108             });
109             # would look first for /tmp/foo.sto
110             # and then /usr/data/foo.sto
111
112           When a namespace is used and there are multiple possible paths,
113           there area a few options to control which file to look for.  A
114           directive of 'FIRST', 'MERGE', or 'LAST' may be specified in
115           $args->{directive} or $self->{directive} or the default value in
116           $DIRECTIVE will be used (default is 'LAST'). When 'FIRST' is
117           specified the first path that contains the namespace is returned.
118           If 'LAST' is used, the last found path that contains the namespace
119           is returned.  If 'MERGE' is used, the data structures are joined
120           together.  If they are arrayrefs, they are joined into one large
121           arrayref.  If they are hashes, they are layered on top of each
122           other with keys found in later paths overwriting those found in
123           earlier paths.  This allows for setting system defaults in a root
124           file, and then allow users to have custom overrides.
125
126           It is possible to make keys in a root file be immutable (non
127           overwritable) by adding a suffix of _immutable or _immu to the key
128           (ie {foo_immutable => 'bar'}).  If a value is found in the file
129           that matches $IMMUTABLE_KEY, the entire file is considered
130           immutable.  The immutable defaults may be overriden using
131           $IMMUTABLE_QR and $IMMUTABLE_KEY.
132
133           Errors during read die.  If the file does not exist undef is
134           returned.
135
136       "write_ref"
137           Takes a file and the reference to be written.  Figures out the type
138           of handler to use to write the file and writes it. If you used the
139           ->read_ref use this method.  Otherwise, use ->write.
140
141       "write"
142           Allows for writing back out the information read in by ->read.  If
143           multiple paths where used - the directive 'FIRST' will write the
144           changes to the first file in the path - otherwise the last path
145           will be used.  If ->read had found immutable keys, then those keys
146           are removed before writing.
147
148           Errors during write die.
149
150       "preload_files"
151           Arguments are file(s) and/or directory(s) to preload.
152           preload_files will loop through the arguments, find the files that
153           exist, read them in using the handler which matches the files
154           extension, and cache them by filename in %CACHE.  Directories are
155           spidered for file extensions which match those listed in
156           %EXT_READERS.  This is useful for a server environment where CPU
157           may be more precious than memory.
158
159       "in_cache"
160           Allow for testing if a particular filename is registered in the
161           %CACHE - typically from a preload_files call.  This is useful when
162           building wrappers around the conf_read and conf_write method calls.
163

FUNCTIONS

165       conf_read
166           Takes a filename.  Returns the read contents of that filename.  The
167           handler to use is based upon the extention on the file.
168
169               my $hash = conf_read('/tmp/foo.yaml');
170
171               my $hash = conf_read('/tmp/foo', {file_type => 'yaml'});
172
173           Takes a filename and a data structure.  Writes the data to the
174           filename.  The handler to use is based upon the extention on the
175           file.
176
177               conf_write('/tmp/foo.yaml', \%hash);
178
179               conf_write('/tmp/foo', \%hash, {file_type => 'yaml'});
180

FILETYPES

182       CGI::Ex::Conf supports the files found in %EXT_READERS by default.
183       Additional types may be added to %EXT_READERS, or a custom handler may
184       be passed via $args->{handler} or $self->{handler}.  If the custom
185       handler is a code ref, all files will be passed to it.  If it is a
186       hashref, it should contain keys which are extensions it supports, and
187       values which read those extensions.
188
189       Some file types have benefits over others.  Storable is very fast, but
190       is binary and not human readable.  YAML is readable but very slow.  I
191       would suggest using a readable format such as YAML and then using
192       preload_files to load in what you need at run time.  All preloaded
193       files are faster than any of the other types.
194
195       The following is the list of handlers that ships with CGI::Ex::Conf
196       (they will only work if the supporting module is installed on your
197       system):
198
199       "pl"
200           Should be a file containing a perl structure which is the last
201           thing returned.
202
203       "sto" and "storable"
204           Should be a file containing a structure stored in Storable format.
205           See Storable.
206
207       "yaml" and "conf" and "val"
208           Should be a file containing a yaml document.  Multiple documents
209           are returned as a single arrayref.  Also - any file without an
210           extension and custom handler will be read using YAML.  See YAML.
211
212       "ini"
213           Should be a windows style ini file.  See Config::IniHash
214
215       "xml"
216           Should be an xml file.  It will be read in by XMLin.  See
217           XML::Simple.
218
219       "json"
220           Should be a json file.  It will be read using the JSON library.
221           See JSON.
222
223       "html" and "htm"
224           This is actually a custom type intended for use with
225           CGI::Ex::Validate.  The configuration to be read is actually
226           validation that is stored inline with the html.  The handler will
227           look for any form elements or input elements with an attribute with
228           the same name as in $HTML_KEY.  It will also look for a javascript
229           variable by the same name as in $HTML_KEY.  All configuration items
230           done this way should be written in YAML.  For example, if $HTML_KEY
231           contained 'validation' it would find validation in:
232
233             <input type=text name=username validation="{required: 1}">
234             # automatically indented and "username:\n" prepended
235             # AND #
236             <form name=foo validation="
237             general no_confirm: 1
238             ">
239             # AND #
240             <script>
241             document.validation = "\n\
242             username: {required: 1}\n\
243             ";
244             </script>
245             # AND #
246             <script>
247             var validation = "\n\
248             username: {required: 1}\n\
249             ";
250             </script>
251
252           If the key $HTML_KEY is not set, the handler will always return
253           undef without even opening the file.
254

TODO

256       Make a similar write method that handles immutability.
257

LICENSE

259       This module may be distributed under the same terms as Perl itself.
260

AUTHOR

262       Paul Seamons <perl at seamons dot com>
263
264
265
266perl v5.12.1                      2010-02-25                  CGI::Ex::Conf(3)
Impressum