view release on metacpan or  search on metacpan

lib/CGI/Ex/Conf.pm  view on Meta::CPAN

    # 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

=head1 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.

=head1 METHODS

=over 4

=item C<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.

=item C<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.

=item C<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.

=item C<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.

=item C<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