CGI::Ex::Conf(3) User Contributed Perl Documentation CGI::Ex::Conf(3)NAMECGI::Ex::Conf - Conf Reader/Writer for many different data format types
SYNOPSIS
use CGI::Ex::Conf qw(conf_read conf_write);
my $hash = conf_read("/tmp/foo.yaml");
conf_write("/tmp/foo.yaml", {key1 => $val1, key2 => $val2});
### OOP interface
my $cob = CGI::Ex::Conf->new;
my $full_path_to_file = "/tmp/foo.val"; # supports ini, sto, val, pl, xml
my $hash = $cob->read($file);
local $cob->{default_ext} = 'conf'; # default anyway
my @paths = qw(/tmp, /home/pauls);
local $cob->{paths} = \@paths;
my $hash = $cob->read('My::NameSpace');
# will look in /tmp/My/NameSpace.conf and /home/pauls/My/NameSpace.conf
my $hash = $cob->read('My::NameSpace', {paths => ['/tmp']});
# will look in /tmp/My/NameSpace.conf
local $cob->{directive} = 'MERGE';
my $hash = $cob->read('FooSpace');
# OR #
my $hash = $cob->read('FooSpace', {directive => 'MERGE'});
# will return merged hashes from /tmp/FooSpace.conf and /home/pauls/FooSpace.conf
# immutable keys are preserved from originating files
local $cob->{directive} = 'FIRST';
my $hash = $cob->read('FooSpace');
# will return values from first found file in the path.
local $cob->{directive} = 'LAST'; # default behavior
my $hash = $cob->read('FooSpace');
# will return values from last found file in the path.
### manipulate $hash
$cob->write('FooSpace'); # will write it out the changes
DESCRIPTION
There are half a million Conf readers out there. Why not add one more.
Actually, this module provides a wrapper around the many file formats
and the config modules that can handle them. It does not introduce any
formats of its own.
This module also provides a preload ability which is useful in
conjunction with mod_perl.
Oh - and it writes too.
METHODS
"read_ref"
Takes a file and optional argument hashref. Figures out the type
of handler to use to read the file, reads it and returns the ref.
If you don't need the extended merge functionality, or key
fallback, or immutable keys, or path lookup ability - then use this
method. Otherwise - use ->read.
"read"
First argument may be either a perl data structure, yaml string, a
full filename, or a file "namespace".
The second argument can be a hashref of override values (referred
to as $args below)..
If the first argument is a perl data structure, it will be copied
one level deep and returned (nested structures will contain the
same references). A yaml string will be parsed and returned. A
full filename will be read using the appropriate handler and
returned (a file beginning with a / or ./ or ../ is considered to
be a full filename). A file "namespace" (ie "footer" or
"my::config" or "what/ever") will be turned into a filename by
looking for that namespace in the paths found either in
$args->{paths} or in $self->{paths} or in @DEFAULT_PATHS.
@DEFAULT_PATHS is empty by default as is $self->{paths} - read
makes no attempt to guess what directories to look in. If the
namespace has no extension the extension listed in
$args->{default_ext} or $self->{default_ext} or $DEFAULT_EXT will
be used).
my $ref = $cob->read('My::NameSpace', {
paths => [qw(/tmp /usr/data)],
default_ext => 'pl',
});
# would look first for /tmp/My/NameSpace.pl
# and then /usr/data/My/NameSpace.pl
my $ref = $cob->read('foo.sto', {
paths => [qw(/tmp /usr/data)],
default_ext => 'pl',
});
# would look first for /tmp/foo.sto
# and then /usr/data/foo.sto
When a namespace is used and there are multiple possible paths,
there area a few options to control which file to look for. A
directive of 'FIRST', 'MERGE', or 'LAST' may be specified in
$args->{directive} or $self->{directive} or the default value in
$DIRECTIVE will be used (default is 'LAST'). When 'FIRST' is
specified the first path that contains the namespace is returned.
If 'LAST' is used, the last found path that contains the namespace
is returned. If 'MERGE' is used, the data structures are joined
together. If they are arrayrefs, they are joined into one large
arrayref. If they are hashes, they are layered on top of each
other with keys found in later paths overwriting those found in
earlier paths. This allows for setting system defaults in a root
file, and then allow users to have custom overrides.
It is possible to make keys in a root file be immutable (non
overwritable) by adding a suffix of _immutable or _immu to the key
(ie {foo_immutable => 'bar'}). If a value is found in the file
that matches $IMMUTABLE_KEY, the entire file is considered
immutable. The immutable defaults may be overriden using
$IMMUTABLE_QR and $IMMUTABLE_KEY.
Errors during read die. If the file does not exist undef is
returned.
"write_ref"
Takes a file and the reference to be written. Figures out the type
of handler to use to write the file and writes it. If you used the
->read_ref use this method. Otherwise, use ->write.
"write"
Allows for writing back out the information read in by ->read. If
multiple paths where used - the directive 'FIRST' will write the
changes to the first file in the path - otherwise the last path
will be used. If ->read had found immutable keys, then those keys
are removed before writing.
Errors during write die.
"preload_files"
Arguments are file(s) and/or directory(s) to preload.
preload_files will loop through the arguments, find the files that
exist, read them in using the handler which matches the files
extension, and cache them by filename in %CACHE. Directories are
spidered for file extensions which match those listed in
%EXT_READERS. This is useful for a server environment where CPU
may be more precious than memory.
"in_cache"
Allow for testing if a particular filename is registered in the
%CACHE - typically from a preload_files call. This is useful when
building wrappers around the conf_read and conf_write method calls.
FUNCTIONS
conf_read
Takes a filename. Returns the read contents of that filename. The
handler to use is based upon the extention on the file.
my $hash = conf_read('/tmp/foo.yaml');
my $hash = conf_read('/tmp/foo', {file_type => 'yaml'});
Takes a filename and a data structure. Writes the data to the
filename. The handler to use is based upon the extention on the
file.
conf_write('/tmp/foo.yaml', \%hash);
conf_write('/tmp/foo', \%hash, {file_type => 'yaml'});
FILETYPESCGI::Ex::Conf supports the files found in %EXT_READERS by default.
Additional types may be added to %EXT_READERS, or a custom handler may
be passed via $args->{handler} or $self->{handler}. If the custom
handler is a code ref, all files will be passed to it. If it is a
hashref, it should contain keys which are extensions it supports, and
values which read those extensions.
Some file types have benefits over others. Storable is very fast, but
is binary and not human readable. YAML is readable but very slow. I
would suggest using a readable format such as YAML and then using
preload_files to load in what you need at run time. All preloaded
files are faster than any of the other types.
The following is the list of handlers that ships with CGI::Ex::Conf
(they will only work if the supporting module is installed on your
system):
"pl"
Should be a file containing a perl structure which is the last
thing returned.
"sto" and "storable"
Should be a file containing a structure stored in Storable format.
See Storable.
"yaml" and "conf" and "val"
Should be a file containing a yaml document. Multiple documents
are returned as a single arrayref. Also - any file without an
extension and custom handler will be read using YAML. See YAML.
"ini"
Should be a windows style ini file. See Config::IniHash
"xml"
Should be an xml file. It will be read in by XMLin. See
XML::Simple.
"json"
Should be a json file. It will be read using the JSON library.
See JSON.
"html" and "htm"
This is actually a custom type intended for use with
CGI::Ex::Validate. The configuration to be read is actually
validation that is stored inline with the html. The handler will
look for any form elements or input elements with an attribute with
the same name as in $HTML_KEY. It will also look for a javascript
variable by the same name as in $HTML_KEY. All configuration items
done this way should be written in YAML. For example, if $HTML_KEY
contained 'validation' it would find validation in:
<input type=text name=username validation="{required: 1}">
# automatically indented and "username:\n" prepended
# AND #
<form name=foo validation="
general no_confirm: 1
">
# AND #
<script>
document.validation = "\n\
username: {required: 1}\n\
";
</script>
# AND #
<script>
var validation = "\n\
username: {required: 1}\n\
";
</script>
If the key $HTML_KEY is not set, the handler will always return
undef without even opening the file.
TODO
Make a similar write method that handles immutability.
LICENSE
This module may be distributed under the same terms as Perl itself.
AUTHOR
Paul Seamons <perl at seamons dot com>
perl v5.14.1 2010-02-25 CGI::Ex::Conf(3)