File Coverage

=head1 NAME
 
OpenSRF::Utils::Config
 

=head1 SYNOPSIS

  use OpenSRF::Utils::Config;

  my $config_obj = OpenSRF::Utils::Config->load( config_file   => '/config/file.cnf' );

  my $attrs_href = $config_obj->bootstrap();

  $config_obj->bootstrap->loglevel(0);

  open FH, '>'.$config_obj->FILE() . '.new';
  print FH $config_obj;
  close FH;

=head1 DESCRIPTION

This module is mainly used by other OpenSRF modules to load an OpenSRF
configuration file.  OpenSRF configuration files are XML files that
contain a C<< <config> >> root element and an C<< <opensrf> >> child
element (in XPath notation, C</config/opensrf/>). Each child element
is converted into a hash key=>value pair. Elements that contain other
XML elements are pushed into arrays and added as an array reference to
the hash. Scalar values have whitespace trimmed from the left and
right sides.

Child elements of C<< <config> >> other than C<< <opensrf> >> are
currently ignored by this module.

=head1 EXAMPLE

Given an OpenSRF configuration file named F<opensrf_core.xml> with the
following content:

  <?xml version='1.0'?>
  <config>
    <opensrf>
      <router_name>router</router_name>

      <routers> 
	<router>localhost</router>
	<router>otherhost</router>
      </routers>

      <logfile>/var/log/osrfsys.log</logfile>
    </opensrf>
  </config>

... calling C<< OpenSRF::Utils::Config->load(config_file =>
'opensrf_core.xml') >> will create a hash with the following
structure:

  {
    router_name => 'router',
    routers => ['localhost', 'otherhost'],
    logfile => '/var/log/osrfsys.log'
  }

You can retrieve any of these values by name from the bootstrap
section of C<$config_obj>; for example:

  $config_obj->bootstrap->router_name

=head1 NOTES

For compatibility with a previous version of OpenSRF configuration
files, the F</config/opensrf/> section has a hardcoded name of
B<bootstrap>. However, future iterations of this module may extend the
ability of the module to parse the entire OpenSRF configuration file
and provide sections named after the sibling elements of
C</config/opensrf>.

Hashrefs of sections can be returned by calling a method of the object
of the same name as the section.  They can be set by passing a hashref
back to the same method.  Sections will B<NOT> be autovivicated,
though.


=head1 METHODS



=head2 OpenSRF::Utils::Config->load( config_file => '/some/config/file.cnf' )

Returns a OpenSRF::Utils::Config object representing the config file
that was loaded.  The most recently loaded config file (hopefully the
only one per app) is stored at $OpenSRF::Utils::ConfigCache. Use
OpenSRF::Utils::Config::current() to get at it.

=cut

=head1 SEE ALSO

	OpenSRF::Utils

=head1 LIMITATIONS

Elements containing heterogeneous child elements are treated as though they have the same element name;
for example:
  <routers>
    <router>localhost</router>
    <furniture>chair</furniture>
  </routers>

... will simply generate a key=>value pair of C<< routers => ['localhost', 'chair'] >>.

=head1 BUGS

No known bugs, but report any to open-ils-dev@list.georgialibraries.org or mrylander@gmail.com.

=head1 COPYRIGHT AND LICENSING

Copyright (C) 2000-2007, Mike Rylander
Copyright (C) 2007, Laurentian University, Dan Scott <dscott@laurentian.ca>

The OpenSRF::Utils::Config module is free software. You may distribute under the terms
of the GNU General Public License version 2 or greater.

=cut