view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

    Import the specified applications.

    Options may be applied to specific applications by grouping
    application names and option hashes in arrays:

        use App::Env ( [ 'app1', \%app1_options ],
                       [ 'app2', \%app2_options ],
                       \%shared_options );

        App::Env::import( [ 'app1', \%app1_options ],
                          [ 'app2', \%app2_options ],
                          \%shared_options );

    Shared (or default) values for options may be specified in a hash passed as
    the last argument.

    The available options are listed below.  Not all options may be shared; these
    are noted.

    - AppOpts _hashref_

        This is a hash of options to pass to the
        `App::Env::<application>` module.  Their meanings are
        application specific.

        This option may not be shared.

    - Force _boolean_

        Don't use the cached environment for this application.

    - Site

        Specify a site.  See ["Application Environments"](#application-environments) for more information

    - Cache _boolean_

        Cache (or don't cache) the environment. By default it is cached.  If
        multiple environments are loaded the _combination_ is also cached.

    - CacheID

        A unique name for the environment. See ["Environment Caching"](#environment-caching) for more information.

        When used as a shared option for multiple applications, this will be
        used to identify the merged environment.  If set to the string
        `AppID`, the full module name will be used as the cache id (ignoring
        the contents of the **AppOpts** option hash).

    - SysFatal _boolean_

        If true, the **system**, **qexec**, and **capture** object methods will throw
        an exception if the passed command exits with a non-zero error.

    - Temp _boolean_

        If true, and the requested environment does not exist in the cache,
        create it but do not cache it (this overrides the **Cache** option).
        If the requested environment does exist in the cache, return an
        non-cached clone of it.  The following options are updated in
        the cloned environment:

            SysFatal

- retrieve

        $env = App::Env::retrieve( $cacheid );

    Retrieve the environment with the given cache id, or undefined if it
    doesn't exist.

## Managing Environments

- config

        App::Env::config( %Defaults );

    Configure default options for environments.  See ["Changing Default
    Option Values"](#changing-default-option-values) for more information.

- uncache

        App::Env::uncache( App => $app, [ Site => $site ] )
        App::Env::uncache( CacheID => $cacheid )

    Delete the cache entry for the given application.  If `Site` is not
    specified, the site is determined as specified in ["Site Specific
    Contexts"](#site-specific-contexts).

    It is currently _not_ possible to use this interface to
    explicitly uncache multi-application environments if they have not
    been given a unique cache id.  It is possible using **App::Env**
    objects.

    The available options are:

    - App

        The application name.  This may not be specified if **CacheID** is
        specified.

    - Site

        If the **Site** option was used when first loading the environment,
        it must be specified here in order to delete the correct cache entry.
        Do not specify this option if **CacheID** is specified.

    - CacheID

        If the **CacheID** option was used to provide a cache key for the cache
        entry, this must be specified here.  Do not specify this option if
        **App** or **Site** are specified.

    - All

        If true uncache all of the cached environments.

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

**App::Env** objects give greater flexibility when dealing with