view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

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 `$SITE` variable is taken from the environment variable
**APP\_ENV\_SITE** if it exists, or from the **Site** option to the class
**import()** function or the **new()** object constructor.
Additionally, if the **APP\_ENV\_SITE** environment variable does _not
exist_ (it is not merely empty), **App::Env** will first attempt to
load the **App::Env::Site** module, which can set the **APP\_ENV\_SITE**
environment variable.

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.

# INTERFACE

**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.

## Using **App::Env** without objects

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

- import

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

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