view release on metacpan or  search on metacpan

lib/App/Env.pm  view on Meta::CPAN

applications will be loaded freshly (any caches will be ignored) and
the merged environment will be cached.  The cache id will by default
be generated from all of the names of the environment modules invoked;
again, this can be overridden using the B<CacheID> option.

=head2 Application Aliases

B<App::Env> performs a case-insensitive search for application
modules.  For example, if the application module is named
B<App::Env::CIAO>, a request for C<ciao> will resolve to it.

Explicit aliases are also possible. A module should be created for
each alias with the single class method B<alias> which should return
the name of the original application.  For example, to make C<App3> be
an alias for C<App1> create the following F<App3.pm> module:

  package App::Env::App3;
  sub alias { return 'App1' };
  1;

The aliased environment can provide presets for B<AppOpts> by returning
a hash as well as the application name:

  package App::Env::ciao34;
  sub alias { return 'CIAO', { Version => 3.4 } };
  1;

These will be merged with any C<AppOpts> passed in via B<import()>, with
the latter taking precedence.

=head2 Site Specific Contexts

In some situations an application's environment will depend upon which
host or network it is executed on.  In such instances B<App::Env>
provides a means for loading an alternate application module.  It does
this by loading the first existent module from the following set of
module names:

  App::Env::$SITE::$app
  App::Env::$app

The default value for C<$SITE> is determined when C<App::Env> is first
loaded. If the environment variable C<APP_ENV_SITE> exists it is set to that,
otherwise if the C<App::Env::Site> module exists, that is loaded.  It should
set the C<APP_ENV_SITE> variable.  After this, modifications to C<APP_ENV_SITE>
are ignored.

The default value may be overridden via the L<Site> option passed to
the class B<import()> function or the B<new()> object constructor.

Take as an example the situation where an application's environment is
stored in F</usr/local/myapp/setup> on one host and
F</opt/local/myapp/setup> on another.  One could include logic in a
single C<App::Env::myapp> module which would recognize which file is
appropriate.  If there are multiple applications, this gets messy.  A
cleaner method is to have separate site-specific modules (e.g.
C<App::Env::LAN1::myapp> and C<App::Env::LAN2::myapp>), and switch
between them based upon the B<APP_ENV_SITE> environment variable.

The logic for setting that variable might be encoded in an
B<App::Env::Site> module to transparently automate things:

  package App::Env::Site;

  my %LAN1 = map { ( $_ => 1 ) } qw( sneezy breezy queasy );
  my %LAN2 = map { ( $_ => 1 ) } qw( dopey  mopey  ropey  );

  use Sys::Hostname;

  if ( $LAN1{hostname()} )
  {
    $ENV{APP_ENV_SITE} = 'LAN1';
  }
  elsif ( $LAN2{hostname()} )
  {
    $ENV{APP_ENV_SITE} = 'LAN2';
  }

  1;

=head2 The Null Environment

B<App::Env> provides the C<null> environment, which simply returns a
snapshot of the current environment.  This may be useful to provide
fall-backs in case an application specific environment was not found,
but the code should fallback to using the existing environment.

  $env = eval { App::Env->new( "MyApp" ) } \
     // App::Env->new( "null", { Force => 1, Cache => 0 } );

As the C<null> environment is a I<snapshot> of the current
environment, if future C<null> environments should reflect the
environment at the time they are constructed, C"null" environments
should not be cached (e.g. C<Cache =E<gt> 0>).  The C<Force =E<gt> 1>
option is specified to ensure that the environment is not being read
from cache, just in case a prior C<null> environment was inadvertently
cached.

=for Pod::Coverage lobject_id

=head1 INTERFACE

B<App::Env> may be used to directly import an application's
environment into the current environment, in which case the
non-object oriented interface will suffice.

For more complicated uses, the object oriented interface allows for
manipulating multiple separate environments.

=head2 Using B<App::Env> without objects

Application environments may be imported into the current environment
either when loading B<App::Env> or via the B<App::Env::import()>
function.

=over

=item import

  use App::Env ( $application, \%options );
  use App::Env ( @applications, \%shared_options );