view release on metacpan or  search on metacpan

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

  this_one: too

=head1 CONFIGURATION LOGIC SUMMARY

=over

=item *

All configuration files are read and merged together with higher
precedence configuration files overriding lower precedence on a realm
by realm basis.

If identically named files exist in the C<conf_path> for any level
(user, realm, project, organization), only the first discovered file
is used. Put another way, the leftmost path in the C<conf_path> takes
precedence for any file name conflict.

=item *

The C<default> realm is merged into each realm (I<realm>'s values
taking precedence).

=item *

All C<default> realm environment variables override all values for
each I<realm> (excepting the C<overrides> realm).

=item *

All specific I<realm> environment variables override that realm's values.

=item *

The C<default> realm overrides section is used to override matching
keys in each I<realm>.

=item *

The specific I<realm> overrides section is used to override matching keys
in I<realm>.

=item *

Any command line options given override ALL matching keys for ALL realms.

=item *

# TODO: NOT YET IMPLEMENTED

Perform variable substitution

=back

=head1 METHODS

=cut

sub new {
    my ( $pkg ) = @_;

    my $self = bless( {
		       REGISTRY   => Activator::Registry->new(),
		       ARGV_EXTRA => {},
		       ARGV       => undef,
		       BAREWORDS  => undef,
		      }, $pkg);

    $self->_init_StrongSingleton();

    return $self;
}

=head2 get_config()

Process command line arguments, environment variables and
configuration files then return a hashref representing the merged
configuration. Recognized configuration items are removed from C<@ARGV>.

Usage:
  Activator::Config->get_config( \@ARGV, $realm, $project_is_arg );


C<$realm> is optional (default is 'default'). If undefined, it will be
determined from a command line option or environment variable.

C<$project_is_arg> is optional. Use any true value for this argument
if your script requries the project name as the last bareword
argument.

Examples:

  #
  # get options for default realm
  #
  my $config = Activator::Config->get_config( \@ARGV );

  #
  # get options for 'some' realm, ignoring --realm and ACT_CONFIG_realm
  #
  my $config = Activator::Config->get_config( \@ARGV, 'some' );

  #
  # don't ignore --realm and ACT_CONFIG_realm, use $barewords[-1] (the
  # last bareword argument) as the project
  #
  Activator::Config->get_config( \@ARGV, undef, 1 );

See L</get_args()> for a description of the way command line arguments
are processed.

If called repeatedly, this sub does NOT reprocess C<\@ARGV>. This
allows you to make multiple calls to get a reference to the config for
multiple realms if desired.

=cut

sub get_config {
    my ( $pkg, $argv, $realm, $project_is_arg ) = @_;
    my $self = &new( @_ );

    # get_args sets $self->{ARGV}