App::Env

App::Env presents a uniform interface to initializing environments for
applications which require special environments. App::Env only handles
the loading, merging, and caching of environments; it does not create
them. That is done within modules for each application suite (e.g.
App::Env::MyApp). App::Env ships with two such modules, App::Env::Null
which simply returns a snapshot of the current environment, and
App::Env::Example, which provides example code for creating an
application specific environment.

App::Env is probably most useful in situations where a Perl program must
invoke multiple applications each of which may require an environment
different and possibly incompatible from the others. The simplified
interface it provides makes it useful even in less complicated
situations.

  Initializing Application Environments

As mentioned above, App::Env does not itself provide the environments
for applications; it relies upon application specific Perl modules to do
so. Such modules must provide an envs() function which should return a
hash reference containing the environment. Application specific options
(e.g. version) may be passed to the module.

See App::Env::Example for information on how to write such modules.

  Managing Environments

In the simplest usage, App::Env can merge ("import") the application's
environment directly into the current environment. For situations where
multiple incompatible environments are required, it can encapsulate
those as objects with convenience methods to easily run applications
within those environments.

  Environment Caching

Environments are (by default) cached to improve performance; the default
cache id is generated from the name of the Perl module which creates the
environment and the options passed to it. signature. When a environment
is requested its signature is compared against those stored in the cache
and if matched, the associated cached environment is returned.

The cache id is (by default) generated from the full module name
(beginning with "App::Env" and including the optional site path -- see
"Site Specific Contexts") and the contents of the AppOpts hash passed to
the module. If the AppOpts hash is empty, the id is just the module
name. The cache id may be explicitly specified with the "CacheID"
option.

If "CacheID" is set to the string "AppID" the cache id is set to the
full module name, ignoring the contents of AppOpts. This is useful if an
application wishes to load an environment using special options but make
it available under the more generic cache id.

To prevent caching, use the "Cache" option. It doesn't prevent App::Env
from *retrieving* an existing cached environment -- to do that, use the
"Force" option, which will result in a freshly generated environment.

To retrieve a cached environment using its cache id use the retrieve()
function.

If multiple applications are loaded via a single call to import or new
the applications will be loaded incrementally in the order specified. In
order to ensure a properly merged environment the 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 CacheID option.

  Application Aliases

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

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

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

The aliased environment can provide presets for 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 "AppOpts" passed in via import(), with the
latter taking precedence.

  Site Specific Contexts

In some situations an application's environment will depend upon which
host or network it is executed on. In such instances 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 $SITE is determined when "App::Env" is first
loaded. If the environment variable "APP_ENV_SITE" exists it is set to
that, otherwise if the "App::Env::Site" module exists, that is loaded.
It should set the "APP_ENV_SITE" variable. After this, modifications to
"APP_ENV_SITE" are ignored.

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

Take as an example the situation where an application's environment is
stored in /usr/local/myapp/setup on one host and /opt/local/myapp/setup
on another. One could include logic in a single "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. "App::Env::LAN1::myapp" and
"App::Env::LAN2::myapp"), and switch between them based upon the
APP_ENV_SITE environment variable.

The logic for setting that variable might be encoded in an
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;

  The Null Environment

App::Env provides the "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 "null" environment is a *snapshot* of the current environment, if
future "null" environments should reflect the environment at the time
they are constructed, C"null" environments should not be cached (e.g.
"Cache => 0"). The "Force => 1" option is specified to ensure that the
environment is not being read from cache, just in case a prior "null"
environment was inadvertently cached.

INSTALLATION

This is a Perl module distribution. It should be installed with whichever
tool you use to manage your installation of Perl, e.g. any of

  cpanm .
  cpan  .
  cpanp -i .

Consult http://www.cpan.org/modules/INSTALL.html for further instruction.
Should you wish to install this module manually, the procedure is

  perl Build.PL
  ./Build
  ./Build test
  ./Build install

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018 by Smithsonian Astrophysical
Observatory.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007