view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

        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
multiple applications with incompatible environments.

### Constructors

- new

        $env = App::Env->new( ... )

    **new** takes the same arguments as **App::Env::import** and returns
    an **App::Env** object.  It does not modify the environment.

- clone

        $clone = $app->clone( \%opts );

    Clone an existing environment.  The available options are `CacheID`,
    `Cache`, `SysFatal` (see the documentation for the **import** function).

    The cloned environment is by default not cached.  If caching is
    requested and a cache id is not provided, a unique id is created --
    it will _not_ be the same as that of the original environment.

    This generated cache id is not based on a signature of the
    environment, so this environment will effectively not be automatically
    reused when a similar environment is requested via the **new**
    constructor (see ["Environment Caching"](#environment-caching)).

### Overloaded operators

**App::Env** overloads the %{} and "" operators.  When
dereferenced as a hash an **App::Env** object returns a hash of
the environmental variables:

    %ENV = %$env;

When interpolated in a string, it is replaced with a string suitable
for use with the \*NIX **env** command; see the **str()** method below
for its format.

### Methods

- cache

        $env->cache( $cache_state );

    If `$cache_state` is true, cache this environment using the object's
    cache id.  If `$cache_state` is false and this environment is being
    cached, delete the cache.

    Note that only the original **App::Env** object which cached the
    environment may delete it.  Objects which reuse existing, cached,
    environments cannot.

- cacheid

        $cacheid = $env->cacheid;

    Returns the cache id for this environment.

- env

        # return a hashref of the entire environment (similar to %{$env})
        $hashref = $env->env( );

        # return the value of a given variable in the environment
        $value = $env->env( $variable_name )

        # return an array of values of particular variables.
        # names should be strings
        @values = $env->env( @variable_names );

        # match variable names and return a hashref
        $hashref = $env->env( @match_specifications );

        # exclude specific variables
        $hashref = $env->env( { Exclude => $match_spec   } );
        $hashref = $env->env( { Exclude => \@match_specs } );
        $hashref = $env->env( @match_specs, { Exclude => $match_spec   } );
        $hashref = $env->env( @match_specs, { Exclude => \@match_specs } );

    Return all or parts of the environment.  What is returned