Activator
11 results

 view release on metacpan or  search on metacpan

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

=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
  <realm>.yml    - realm specific settings and defaults
  <project>.yml  - project specific settings and defaults
  org.yml        - top level organization settings and defaults

It is up to the script using this module to define what C<project> is,
and up to the project to define what realms exist, which all could
come from any of the command line options, environment variables or
configuration files. All of the above files are optional and will be
ignored if they don't exist, however at least one configuration file
must exist for the C<get_opts()> function.

=head2 Configuration File Search Path

TODO: This functionality is not implemented yet. Currently, only
      ~/.activator.d/<project> is supported

The search path for configuration YAML files is listed below. The
first conf file for each level appearing in the following directories
will be utilized:

  --conf_path=<paths_to_conf_dir>        # colon separated list
  --conf_files=<conf_files>              # comma separated list
  $ENV{ACT_OPT_conf_path}
  $ENV{ACT_OPT_project_home}/.<$ENV{ACT_OPT_project}>.d/
  $ENV{HOME}/.<$ENV{ACT_OPT_project}>.d/
  /etc/<$ENV{ACT_OPT_project}>.d/
  /etc/activator.d/                      # useful for org.yml

It is up to the script to define what C<project> is by insuring that
C<$ENV{ACT_OPT_project}> is set. This module will throw
C<Activator::Exception::Option> it is not set by you or passed in as a
command line argument, so you could force the user to use the
C<--project> option if you like.

=head2 Realms

This module supports the concept of realms to allow multiple similar
configurations to override only the esential keys to "git 'er done".

=head2 Configuration Logic Summary

=over

=item *

All configuration files are read and merged together on a realm by
realm basis with higher precedence configuration files overriding
lower precedence. If duplicate level files exist in the Configuration
File Search Path, only the first discovered file is used.

=item *

All realms are then merged with the C<default> realm, I<realm> config
taking precedence.

=item *

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

=item *

All specific realm environment variables override that realm's values
for the key.

=item *

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

=item *

The specific realm overrides section is used to override matching keys
in the requested realm.

=item *

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

=item *

# TODO: NOT YET IMPLEMENTED

Perform variable substitution

=back

=head1 COMMAND LINE ARGUMENTS

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

    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,
	# Activator::Registry will allow debug mode so we can state
	# show this.
	if ( exists( $overrides->{ $realm } ) ) {
	    $self->{REGISTRY}->register_hash( 'right', $overrides->{ $realm }, $realm );
	}

	# now that realm is set, make sure our $opts points to it
	$opts = $self->{REGISTRY}->get_realm( $realm );

	# Override any provided command line options into this realm.
	# Strips known options out of \@ARGV
	$self->_argv_override( $opts, $argv );

	DEBUG( 'created opts: '.Dumper( $opts ));
    }
    else {
	DEBUG( 'found opts: '.Dumper( $opts ));
    }

    return $opts;
}

=head2 get_args()

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

        if ( defined $value ) {
	    DEBUG("got key '$key' = '$value'");

	    # if we see an argument again, coerce this value into an
	    # array
            if ( exists $argv->{ $key } ) {
		if ( reftype ( $argv->{ $key } ) eq 'ARRAY' ) {
		    DEBUG("added '$value' to key list '$key'" );
		    push @{ $argv->{ $key } }, $value;
		}
		else {
		    DEBUG("created key list '$key' and added '$value'" );
		  $argv->{ $key } = [ $argv->{ $key }, $value ];
	      }
	    }
	    # just set it
	    else {
		$argv->{ $key } = $value;
	    }
	}
        else {

	    # if we see a value again, increment the occurence count
	    if ( exists $argv->{ $key } ) {
		DEBUG("incremented key '$key'" );
		$argv->{ $key }++;
	    }
	    else {
		DEBUG("set $key" );
		$argv->{ $key } = 1;
	    }
        }
    }

    # save these so we don't have to do it again
    $self->{ARGV}      = $argv;
    $self->{BAREWORDS} = $barewords;

    return ( $argv, $barewords );
}

# Helper to split an arg into key/value. Returns ($key, $value), where
# $value is undef if the argument is flag format (--debug), undef if
# it is a bareword ( foo ) and '--' if it is the arguments terminator
# symbol.
#
sub _get_arg {
    my ( $self, $arg ) = @_;

    if ( $arg !~ /^-(-)?/ ) {
	return;
    }

    if ( $arg eq '--' ) {
	return $arg;
    }

    my ( $key, $value ) = split /=/xms, $arg, 2;

    if ( !defined $key ) {
	Activator::Exception::Options->throw( 'argument',
					      'invalid',
					      $arg );
    }

    # clean up key
    $key =~ s/^--?//;

    # clean up value, if quoted
    if ( defined $value ) {
	$value =~ s/^"//;
	$value =~ s/"$//;
    }

    return ( $key, $value );
}

# Merge config files into this objects Activator::Registry object
sub _process_config_for {
    my ( $pkg, $realm ) = @_;
    my $self = &new( @_ );

    # figure out what project we are working on
    my $project =
      $self->{ARGV}->{project} ||
	$ENV{ACT_OPT_project} ||
	  Activator::Exception::Options->throw( 'project', 'missing' );

    # assemble a list of paths to look for config files
    # TODO: look in all these places:
    #   --conf_path
    #   ACT_OPT_conf_path
    #   $ENV{ACT_OPT_project_home}/.<$ENV{ACT_OPT_project}>.d/
    #   $ENV{HOME}/.<$ENV{ACT_OPT_project}>.d/
    #   $ENV{HOME}/.activator.d/
    #   /etc/<$ENV{ACT_OPT_project}>.d/
    #   /etc/activator.d/
    #

    # assemble a list of files to process into the keys of $seach_paths
    # TODO: assemble list of files for each of the above dirs
    #   --conf_file=       : use $self->{ARGV}->{conf_file} (which could be an arrayref )
    #   ACT_OPT_conf_file= : comma separated list of files
    #   $ENV{USER}.yml
    #   <realm>.yml    - realm specific settings and defaults
    #   <project>.yml  - project specific settings and defaults
    #   org.yml        - top level organization settings and defaults

    # For now, just use ~/.activator.d/$project : key/value is path/'where
    # found', 'where found' being one of: hardcoded, env, or arg
    my $dir = $self->{ARGV}->{conf_path} ||
	$ENV{ACT_OPT_conf_path} ||
	  Activator::Exception::Options->throw( 'conf_path', 'missing');
    my $search_paths = { $dir => 'arg' };

    my $files = { user    => { target => "$ENV{USER}.yml" },
		  realm   => { target => "${realm}.yml"   },
		  project => { target => "${project}.yml" },
		  org     => { target => 'org.yml' } };
    foreach my $path ( keys %$search_paths ) {
	$path =~ s|/$||;
	foreach my $which ( keys %$files ) {
	    my $target = $files->{ $which }->{target};
	    if ( !opendir DIR, $path ) {
		# TODO: enhance this note to say where this path was detected
		WARN( "Ignoring invalid path '$path'" );
	    }
	    else {
		my @found = grep { /^$target$/ && -f "$path/$_" } readdir(DIR);
		if ( @found  ) {
		    my $file = "$path/$found[0]";
		    if ( !exists( $files->{ $which }->{ file } ) ) {
			$files->{ $which }->{file} = $file;
		    }
		    else {
			# TODO: enhance this note to say where this path was detected
			INFO( "Ignoring lower priority config file '$file'" );
		    }
		}
	    }
	}
    }

    # now that we have all the files, import 'em! This is a super long
    # winded but safe "left precedence" merge of all files
    my ( $user_config, $realm_config, $project_config, $org_config );

    try eval {
	if( exists( $files->{user}->{file} ) ) {
	    $user_yml = YAML::Syck::LoadFile( $files->{user}->{file} );
	}
    };
    if ( catch my $e ) {
	Activator::Exception::Options->throw( 'user_config', 'invalid', $e );
    }

    try eval {
	if( exists( $files->{realm}->{file} ) ) {
	    $realm_yml = YAML::Syck::LoadFile( $files->{realm}->{file} );
	}
    };
    if ( catch my $e ) {
	Activator::Exception::Options->throw( 'realm_config', 'invalid', $e );
    }

    try eval {
	if( exists( $files->{project}->{file} ) ) {
	    $project_yml = YAML::Syck::LoadFile( $files->{project}->{file} );
	}
    };
    if ( catch my $e ) {
	Activator::Exception::Options->throw( 'project_config', 'invalid', $e );
    }

    try eval {
	if( exists( $files->{org}->{file} ) ) {
	    $org_yml = YAML::Syck::LoadFile( $files->{org}->{file} );
	}
    };
    if ( catch my $e ) {
	Activator::Exception::Options->throw( 'org_config', 'invalid', $e );
    }

    if ( defined( $user_yml ) && exists( $user_yml->{ $realm } ) ) {
	$self->{REGISTRY}->register_hash( 'left', $user_yml->{ $realm }, $realm );
    }

    if ( defined( $realm_yml ) && exists( $realm_yml->{ $realm } ) ) {
	$self->{REGISTRY}->register_hash( 'left', $realm_yml->{ $realm }, $realm );
    }

    if ( defined( $project_yml ) && exists( $project_yml->{ $realm } ) ) {
	$self->{REGISTRY}->register_hash( 'left', $project_yml->{ $realm }, $realm );
    }

    if ( defined( $org_yml ) && exists( $org_yml->{ $realm } ) ) {
	$self->{REGISTRY}->register_hash( 'left', $org_yml->{ $realm }, $realm );
    }

    if ( defined( $user_yml ) && exists( $user_yml->{default} ) ) {
	$self->{REGISTRY}->register_hash( 'left', $user_yml->{default}, $realm );
    }

    if ( defined( $realm_yml ) && exists( $realm_yml->{default} ) ) {
	$self->{REGISTRY}->register_hash( 'left', $realm_yml->{default}, $realm );
    }

    if ( defined( $project_yml ) && exists( $project_yml->{default} ) ) {
	$self->{REGISTRY}->register_hash( 'left', $project_yml->{default}, $realm );
    }

    if ( defined( $org_yml ) && exists( $org_yml->{default} ) ) {
	$self->{REGISTRY}->register_hash( 'left', $org_yml->{default}, $realm );
    }

    if ( defined( $user_yml ) && exists( $user_yml->{overrides} ) ) {
	$self->{REGISTRY}->register_hash( 'left', $user_yml->{overrides}, 'overrides' );
    }

    if ( defined( $realm_yml ) && exists( $realm_yml->{overrides} ) ) {
	$self->{REGISTRY}->register_hash( 'left', $realm_yml->{overrides}, 'overrides' );
    }

    if ( defined( $project_yml ) && exists( $project_yml->{overrides} ) ) {
	$self->{REGISTRY}->register_hash( 'left', $project_yml->{overrides}, 'overrides' );
    }

    if ( defined( $org_yml ) && exists( $org_yml->{overrides} ) ) {
	$self->{REGISTRY}->register_hash( 'left', $org_yml->{overrides}, 'overrides' );
    }

    # make sure all is kosher
    my $test = $self->{REGISTRY}->get_realm( $realm );
    if ( !keys %$test ) {
	Activator::Exception::Options->throw('realm', 'invalid', $realm);
    }

}

# Override any options in $opts with the values in $argv. Sets non-existent keys.
#
# Arguments:
#   $opts  : hashref to the options for $realm
#   $argv  : arrayref to command line arguments. All recognized options are removed.
#
sub _argv_override {
    my ( $self, $opts, $argv ) = @_;

    my @barewords;
    my @unrec;

    # loop through $argv (which we assume to be a ref to @ARGV) and
    # set any opts if they exist.
    while ( my $arg = shift @$argv  ) {
	my ( $key, $value ) = $self->_get_arg( $arg );

	# ignore barewords
	if ( ! defined( $key ) ) {
	    DEBUG("Ignoring bareword '$arg'");
	    push @barewords, $arg;
	    next;
	}

	# finish up if we find terminator
	if ( $key eq '--' ) {
	    DEBUG("Found arguments terminator --");
	    unshift @$argv, '--';
	    unshift @$argv, @barewords;
	    last;
	}

# TODO: consider supporting realm specific command line arguments
#
#	# skip this key if it is for a different realm
#	if ( $key =~ /^__(\w+)__(\w+)$/ ) {
#	    $key_realm = $1;
#	    $key = $2;
#	    if( $realm ne $key_realm ) {
#		push @unrec, $arg;
#		next;
#	    }
#	}

	$opts->{ $key } = $value;
    }
    unshift @$argv, @unrec;

}

# do variable replacements throughout
sub _var_replace {
    my ( $self, $opts, $replacements ) = @_;
#    Activator::Registry->replace_in_hashref( $opts, 
}



( run in 0.696 second using v1.01-cache-2.11-cpan-39bf76dae61 )