view release on metacpan or  search on metacpan

lib/Config/Merge.pm  view on Meta::CPAN

   $config       = My::Config::object;
   -------------------------------------------------------

ADVANCED USAGE

   OO style
   -------------------------------------------------------
   my $config    = Config::Merge->new(
       path      => '/path/to/config',
       skip      => sub {} | regex | {} ,
       is_local  => sub {} | regex | {} ,
       load_as   => sub {} | regex ,
       sort      => sub {} ,
       debug     => 1 | 0
   );
   -------------------------------------------------------

   Functional style
   -------------------------------------------------------
   use Config::Merge(
       'My::Config' => '/path/to/config',
       {
           skip      => sub {} | regex | {} ,
           is_local  => sub {} | regex | {} ,
           load_as   => sub {} | regex ,
           sort      => sub {} ,
           debug     => 1 | 0
       }
   );

   # Also, you can subclass these:

     package My::Config;
     sub skip {
         ...
     }

   -------------------------------------------------------

=head1 DESCRIPTION

Config::Merge is a configuration module which has six goals:

=over

=item * Flexible storage

Store all configuration in your format(s) of choice (YAML, JSON, INI, XML, Perl,
Config::General / Apache-style config) broken down into individual files in
a configuration directory tree, for easy maintenance.
 See L</"CONFIG TREE LAYOUT">

=item * Flexible access

Provide a simple, easy to read, concise way of accessing the configuration
values (similar to L<Template>). See L</"ACCESSING CONFIG DATA">

=item * Minimal maintenance

Specify the location of the configuration files only once per
application, so that it requires minimal effort to relocate.
See L</"USING Config::Merge">

=item * Easy to alter development environment

Provide a way for overriding configuration values on a development
machine, so that differences between the dev environment and
the live environment do not get copied over accidentally.
See L</"OVERRIDING CONFIG LOCALLY">

=item * Minimise memory use

Load all config at startup so that (eg in the mod_perl environment) the
data is shared between all child processes. See L</"MINIMISING MEMORY USE">

=item * Flexible implementation

You may want to use a different schema for your configuration files,
so you can pass in (or subclass) methods for determining how your
files are merged.  See L</"ADVANCED USAGE">.

=back

=head1 USING C<Config::Merge>

There are two ways to use C<Config::Merge>:

=over

=item OO STYLE

   use Config::Merge();
   my $config    = Config::Merge->new('/path/to/config');

   @hosts        = $config->('db.hosts.session');
   $hosts_ref    = $config->('db.hosts.session');
   @cloned_hosts = $config->clone('db.hosts.session');

Also, see L</"ADVANCED USAGE">.

=item YOUR OWN CONFIG CLASS (functional style)

The following code:

   # On startup
   use Config::Merge('My::Config' => '/path/to/config');

=over

=item *

auto-generates the class C<My::Config>

=item *

loads the configuration data in C<'/path/to/config'>

=item *

creates the subs C<My::Config::C>, C<My::Config::clone>
and C<My::Config::object>.