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

VERSION

9       version 2.54
10

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

FUNCTIONS

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

FILETYPES

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

TODO

259       Make a similar write method that handles immutability.
260

LICENSE

262       This module may be distributed under the same terms as Perl itself.
263

AUTHOR

265       Paul Seamons <perl at seamons dot com>
266
267
268
269perl v5.36.0                      2023-01-20                  CGI::Ex::Conf(3)
Impressum