1CGI::Ex::Conf(3) User Contributed Perl Documentation CGI::Ex::Conf(3)
2
6 CGI::Ex::Conf - Conf Reader/Writer for many different data format types
7
9 use CGI::Ex::Conf qw(conf_read conf_write);
10 my $hash = conf_read("/tmp/foo.yaml");
12 conf_write("/tmp/foo.yaml", {key1 => $val1, key2 => $val2});
14 ### OOP interface
16 my $cob = CGI::Ex::Conf->new;
18 my $full_path_to_file = "/tmp/foo.val"; # supports ini, sto, val, pl, xml
20 my $hash = $cob->read($file);
21 local $cob->{default_ext} = 'conf'; # default anyway
23 my @paths = qw(/tmp, /home/pauls);
25 local $cob->{paths} = \@paths;
26 my $hash = $cob->read('My::NameSpace');
27 # will look in /tmp/My/NameSpace.conf and /home/pauls/My/NameSpace.conf
28 my $hash = $cob->read('My::NameSpace', {paths => ['/tmp']});
30 # will look in /tmp/My/NameSpace.conf
31 local $cob->{directive} = 'MERGE';
33 my $hash = $cob->read('FooSpace');
34 # OR #
35 my $hash = $cob->read('FooSpace', {directive => 'MERGE'});
36 # will return merged hashes from /tmp/FooSpace.conf and /home/pauls/FooSpace.conf
37 # immutable keys are preserved from originating files
38 local $cob->{directive} = 'FIRST';
40 my $hash = $cob->read('FooSpace');
41 # will return values from first found file in the path.
42 local $cob->{directive} = 'LAST'; # default behavior
44 my $hash = $cob->read('FooSpace');
45 # will return values from last found file in the path.
46 ### manipulate $hash
48 $cob->write('FooSpace'); # will write it out the changes
49
51 There are half a million Conf readers out there. Why not add one more.
52 Actually, this module provides a wrapper around the many file formats
53 and the config modules that can handle them. It does not introduce any
54 formats of its own.
55 This module also provides a preload ability which is useful in conjunc‐
57 tion with mod_perl.
58 Oh - and it writes too.
60
62 "read_ref"
63 Takes a file and optional argument hashref. Figures out the type
64 of handler to use to read the file, reads it and returns the ref.
65 If you don't need the extended merge functionality, or key fall‐
66 back, or immutable keys, or path lookup ability - then use this
67 method. Otherwise - use ->read.
68 "read"
70 First argument may be either a perl data structure, yaml string, a
71 full filename, or a file "namespace".
72 The second argument can be a hashref of override values (referred
74 to as $args below)..
75 If the first argument is a perl data structure, it will be copied
77 one level deep and returned (nested structures will contain the
78 same references). A yaml string will be parsed and returned. A
79 full filename will be read using the appropriate handler and
80 returned (a file beginning with a / or ./ or ../ is considered to
81 be a full filename). A file "namespace" (ie "footer" or "my::con‐
82 fig" or "what/ever") will be turned into a filename by looking for
83 that namespace in the paths found either in $args->{paths} or in
84 $self->{paths} or in @DEFAULT_PATHS. @DEFAULT_PATHS is empty by
85 default as is $self->{paths} - read makes no attempt to guess what
86 directories to look in. If the namespace has no extension the
87 extension listed in $args->{default_ext} or $self->{default_ext} or
88 $DEFAULT_EXT will be used).
89 my $ref = $cob->read('My::NameSpace', {
91 paths => [qw(/tmp /usr/data)],
92 default_ext => 'pl',
93 });
94 # would look first for /tmp/My/NameSpace.pl
95 # and then /usr/data/My/NameSpace.pl
96 my $ref = $cob->read('foo.sto', {
98 paths => [qw(/tmp /usr/data)],
99 default_ext => 'pl',
100 });
101 # would look first for /tmp/foo.sto
102 # and then /usr/data/foo.sto
103 When a namespace is used and there are multiple possible paths,
105 there area a few options to control which file to look for. A
106 directive of 'FIRST', 'MERGE', or 'LAST' may be specified in
107 $args->{directive} or $self->{directive} or the default value in
108 $DIRECTIVE will be used (default is 'LAST'). When 'FIRST' is speci‐
109 fied the first path that contains the namespace is returned. If
110 'LAST' is used, the last found path that contains the namespace is
111 returned. If 'MERGE' is used, the data structures are joined
112 together. If they are arrayrefs, they are joined into one large
113 arrayref. If they are hashes, they are layered on top of each
114 other with keys found in later paths overwriting those found in
115 earlier paths. This allows for setting system defaults in a root
116 file, and then allow users to have custom overrides.
117 It is possible to make keys in a root file be immutable (non over‐
119 writable) by adding a suffix of _immutable or _immu to the key (ie
120 {foo_immutable => 'bar'}). If a value is found in the file that
121 matches $IMMUTABLE_KEY, the entire file is considered immutable.
122 The immutable defaults may be overriden using $IMMUTABLE_QR and
123 $IMMUTABLE_KEY.
124 Errors during read die. If the file does not exist undef is
126 returned.
127 "write_ref"
129 Takes a file and the reference to be written. Figures out the type
130 of handler to use to write the file and writes it. If you used the
131 ->read_ref use this method. Otherwise, use ->write.
132 "write"
134 Allows for writing back out the information read in by ->read. If
135 multiple paths where used - the directive 'FIRST' will write the
136 changes to the first file in the path - otherwise the last path
137 will be used. If ->read had found immutable keys, then those keys
138 are removed before writing.
139 Errors during write die.
141 "preload_files"
143 Arguments are file(s) and/or directory(s) to preload.
144 preload_files will loop through the arguments, find the files that
145 exist, read them in using the handler which matches the files
146 extension, and cache them by filename in %CACHE. Directories are
147 spidered for file extensions which match those listed in %EXT_READ‐
148 ERS. This is useful for a server environment where CPU may be more
149 precious than memory.
150 "in_cache"
152 Allow for testing if a particular filename is registered in the
153 %CACHE - typically from a preload_files call. This is useful when
154 building wrappers around the conf_read and conf_write method calls.
155
157 conf_read
158 Takes a filename. Returns the read contents of that filename. The
159 handler to use is based upon the extention on the file.
160 my $hash = conf_read('/tmp/foo.yaml');
162 my $hash = conf_read('/tmp/foo', {file_type => 'yaml'});
164 Takes a filename and a data structure. Writes the data to the
166 filename. The handler to use is based upon the extention on the
167 file.
168 conf_write('/tmp/foo.yaml', \%hash);
170 conf_write('/tmp/foo', \%hash, {file_type => 'yaml'});
172
174 CGI::Ex::Conf supports the files found in %EXT_READERS by default.
175 Additional types may be added to %EXT_READERS, or a custom handler may
176 be passed via $args->{handler} or $self->{handler}. If the custom han‐
177 dler is a code ref, all files will be passed to it. If it is a
178 hashref, it should contain keys which are extensions it supports, and
179 values which read those extensions.
180 Some file types have benefits over others. Storable is very fast, but
182 is binary and not human readable. YAML is readable but very slow. I
183 would suggest using a readable format such as YAML and then using
184 preload_files to load in what you need at run time. All preloaded
185 files are faster than any of the other types.
186 The following is the list of handlers that ships with CGI::Ex::Conf
188 (they will only work if the supporting module is installed on your sys‐
189 tem):
190 "pl"
192 Should be a file containing a perl structure which is the last
193 thing returned.
194 "sto" and "storable"
196 Should be a file containing a structure stored in Storable format.
197 See Storable.
198 "yaml" and "conf" and "val"
200 Should be a file containing a yaml document. Multiple documents
201 are returned as a single arrayref. Also - any file without an
202 extension and custom handler will be read using YAML. See YAML.
203 "ini"
205 Should be a windows style ini file. See Config::IniHash
206 "xml"
208 Should be an xml file. It will be read in by XMLin. See XML::Sim‐
209 ple.
210 "json"
212 Should be a json file. It will be read using the JSON library.
213 See JSON.
214 "html" and "htm"
216 This is actually a custom type intended for use with CGI::Ex::Vali‐
217 date. The configuration to be read is actually validation that is
218 stored inline with the html. The handler will look for any form
219 elements or input elements with an attribute with the same name as
220 in $HTML_KEY. It will also look for a javascript variable by the
221 same name as in $HTML_KEY. All configuration items done this way
222 should be written in YAML. For example, if $HTML_KEY contained
223 'validation' it would find validation in:
224 <input type=text name=username validation="{required: 1}">
226 # automatically indented and "username:\n" prepended
227 # AND #
228 <form name=foo validation="
229 general no_confirm: 1
230 ">
231 # AND #
232 <script>
233 document.validation = "\n\
234 username: {required: 1}\n\
235 ";
236 </script>
237 # AND #
238 <script>
239 var validation = "\n\
240 username: {required: 1}\n\
241 ";
242 </script>
243 If the key $HTML_KEY is not set, the handler will always return
245 undef without even opening the file.
246
248 Make a similar write method that handles immutability.
249
251 This module may be distributed under the same terms as Perl itself.
252
254 Paul Seamons <perl at seamons dot com>
255perl v5.8.8 2007-10-18 CGI::Ex::Conf(3)