view release on metacpan or  search on metacpan

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

package Activator::Options;

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

THIS MODULE DEPRECATED. USE L<Activator::Config> instead.


C<Activator::Options> - process options for a script combining command
line, environment variables, and configuration files.

=head1 SYNOPSIS

  use Activator::Options;

  my $opts = Activator::Options->get_opts( \@ARGV);  # default realm
  my $opts = Activator::Options->get_opts( \@ARGV, $otherrealm);

  #### Get a hashref of command line arguments, and an arrayref of barewords
  my ( $argv, $barewords ) = Activator::Options->get_args( \@ARGV );

=head1 DESCRIPTION

This module allows a script to obtain options from command line,
envirnoment variables, and YAML configuration files.

=head2 Prcedence Heirarchy

The precedence heirarchy 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

=head2 Configuration File Heirarchy

In order to facilite the varied ways in which software is developed,
deployed, and used, the following heirarchy lists the configuration
file heirarchy suported from highest to lowest:

  $ENV{USER}.yml - user specific settings

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

Note that you must fully qualify any deeply nested references.

=head1 METHODS

=head2 new()

Constructor: implements singleton. Not very useful. Use L<get_opts()>.

=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_opts()

Usage:

  Activator::Options->get_opts( \@ARGV );         # default realm
  Activator::Options->get_opts( \@ARGV, $realm );

Strip recognized options from C<@ARGV> and return the configuration
hash C<$opts> for C<$realm> based on C<@ARGV>. C<$realm> is optional
(default is 'default'), and if not specified either the command line
argument (C<--realm>) or environment variable
(C<ACT_OPT_E<lt>realmE<gt>> unless C<ACT_OPT_skip_env> is set) will be
used. Not specifying a realm via one of these mechanisms is a fatal
error.

Examples:

  #### get options for default realm
  my $opts = Activator::Options->get_opts( \@ARGV );

  #### get options for 'some' realm
  my $opts = Activator::Options->get_opts( \@ARGV, 'some' );

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

=cut

sub get_opts {
    my ( $pkg, $argv, $realm ) = @_;
    my $self = &new( @_ );
    my $argx = {};

    # get_args sets $self->{ARGV}
    $self->get_args( $argv );
    DEBUG( Data::Dumper->Dump( [ $self->{ARGV} ], [ qw/ ARGV / ] ) );
    DEBUG( Data::Dumper->Dump( [ $self->{BAREWORDS} ], [ qw /BAREWORDS/ ] ) );

    # make sure we can use ENV vars
    my $skip_env =  $ENV{ACT_OPT_skip_env};

    $realm ||=
      $self->{ARGV}->{realm} ||
	( $skip_env ? undef : $ENV{ACT_OPT_realm} ) ||
	  'default';

    # setup or get the merged YAML configuration settings from files
    # into the registry
    my $opts = $self->{REGISTRY}->get_realm( $realm );

    # first call
    if ( !keys %$opts ) {
	# define valid opts from config files
	try eval {
	    $self->_process_config_for( $realm );
	};

	# _set_reg throws err if $realm is invalid
	if ( catch my $e ) {
	    $e->rethrow;
	}

	# read environment variables, set any keys found
	if ( !$skip_env ) {
	    my ( $env_key, $env_realm );
	    foreach my $env_key ( keys %ENV ) {
		next unless $env_key =~ /^ACT_OPT_(.+)/;
		$opt_key = $1;
		$opt_realm = $realm;

		my $env_opt_realm = $opt_realm;
		my $env_opt_key = $opt_key;
		if ( $opt_key =~ /^_(\w+)__(\w+)$/ ) {
		    $env_opt_realm = $1;
		    $env_opt_key = $2;
		    if ( $env_opt_realm eq $realm ) {
			$opt_key = $env_opt_key;
			$opt_realm = $env_opt_realm;
		    }
		}

		if ( $self->{REGISTRY}->get( $opt_key, $opt_realm ) ) {
		    $self->{REGISTRY}->register( $opt_key, $ENV{ $env_key }, $opt_realm );
		}
		elsif( $env_opt_realm ne $opt_realm &&
		      !grep( /$opt_key/, qw( skip_env project project_home
					     realm conf_file conf_path ) ) ) {
		    WARN( "Skipped invalid environment variable $env_key.  Key '$opt_key' for realm '$opt_realm' unchanged");
		}
	    }
	}

	# forced overrides from config files
	my $overrides = $self->{REGISTRY}->get_realm( 'overrides' );
	DEBUG( 'processing overrides: '.Dumper( $overrides ));

	# NOTE: bad (typo) keys could be in overrides. Someday,