view release on metacpan or  search on metacpan

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

package Activator::Config;

use Data::Dumper;
use Activator::Registry;
use Activator::Log qw( :levels );
use Scalar::Util qw( reftype );
use Exception::Class::TryCatch;
use base 'Class::StrongSingleton';

=head1 NAME

C<Activator::Config> - provides a merged configuration to a script
combining command line options, environment variables, and
configuration files.

=head1 SYNOPSIS

  use Activator::Config;

  my $config = Activator::Config->get_config( \@ARGV);  # default realm
  my $config = Activator::Config->get_config( \@ARGV, $otherrealm);

  #### Get a hashref of command line arguments, and an arrayref of bareword arguments
  my ( $config, $args ) = Activator::Config->get_args( \@ARGV );

=head1 DESCRIPTION

This module allows a script or application to have a complex
configuration combining options from command line, environment
variables, and YAML configuration files.

For a script or application, one creates any number of YAML
configuration files. These files will be deterministically merged into
one hash. You can then pass this to an application or write it to file.

This module is not an options validator. It uses command line options
as overrides to existing keys in configuration files and DOES NOT
validate them. Unrecognized command line options are ignored and
C<@ARGV> is modified to remove recognized options, leaving barewords
and unrecognized options in place and the same order for a real
options validator (like L<Getopt::Long>). If you do use another
options module, make sure you call C<get_config()> BEFORE you call
their processor, so that C<@ARGV> will be in an appropriate state.

Environment variables can be used to act as a default to command line
options, and/or override any top level configuration file key which is
a scalar.

This module is cool because:

=over

=item *

You can generate merged, complex configuration heirarchies that are
context sensitive very easily.

=item *

You can pass as complex a config as you like to any script or
application, and override any scalar configuration option with your
environment variables or from the command line.

=item *

It supports realms, allowing you to have default configurations for
development, QA, production, or any number of arbitrary realms you
desire. That is, with a simple command line flag, you can switch
your configuration context.

=back

=head2 Configuration Source Precedence

The precedence heirarchy for configuration from highest to lowest is:

=over

=item *

command line options

=item *

environment variables

=item *

forced overrides from config files

=item *

merged settings from YAML configuration files

=back

=head1 COMMAND LINE ARGUMENTS