NAME

CGI::Ex::Conf - CGI Extended Conf Reader

SYNOPSIS

  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.
  

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.

METHODS

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

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

FILETYPES

CGI::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.

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.

AUTHOR

Paul Seamons

LICENSE

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