view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

- import

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

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

    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.

README.mkdn  view on Meta::CPAN

            $hash = $env->env( [ $variable_name ] );

    Variable names may be excluded from the list by passing a hash with
    the key `Exclude` as the last argument (valid only in contexts 0 and
    3).  The value is either a scalar or an arrayref composed of match
    specifications (as an arrayref) as described in context 3.

- setenv

        # set an environmental variable
        $env->setenv( $var, $value );

        # delete an environmetal variable
        $env->setenv( $var );

    If `$value` is present, assign it to the named environmental
    variable.  If it is not present, delete the variable.

    **Note:** If the environment refers to a cached environment, this will
    affect all instances of the environment which share the cache.

- module

        $module = $env->module;

    This returns the name of the module which was used to load the
    environment.  If multiple modules were used, the names are
    concatenated, separated by the `$;` (subscript separator) character.

- str

        $envstr = $env->str( @match_specifications, \%options );

    This function returns a string which may be used with the \*NIX **env**
    command to set the environment.  The string contains space separated
    `var=value` pairs, with shell magic characters escaped.

    The environment may be pared down by passing _match specifications_
    and an `Exclude` option; see the documentation for the **env** method,
    context 3, for more information.

    Because the **TERMCAP** environment variable is often riddled with
    escape characters, which are not always handled well by shells, the
    **TERMCAP** variable is _always_ excluded unless it is explicitly
    included via an exact variable name match specification. For example,

        $envstr = $env->str( qr/.*/, 'TERMCAP );

    is the only means of getting all of the environment returned.

- system

        $env->system( $command, @args );

    This runs the passed command in the environment defined by **$env**.
    It has the same argument and returned value convention as the core
    Perl **system** command.

    If the **SysFatal** flag is set for this environment,
    **IPC::System::Simple::system** is called, which will cause this method
    to throw an exception if the command returned a non-zero exit value.
    It also avoid invoking a shell to run the command if possible.

- exec

        $env->exec( $command, @args );

    This execs the passed command in the environment defined by **$env**.
    It has the same argument and returned value convention as the core
    Perl **exec** command.

- qexec

        $output = $env->qexec( $command, @args );
        @lines = $env->qexec( $command, @args );

    This acts like the **qx{}** Perl operator.  It executes the passed
    command in the environment defined by **$env** and returns its
    (standard) output.  If called in a list context the output is
    split into lines.

    If the **SysFatal** flag is set for this environment,
    **IPC::System::Simple::capture** is called, which will cause this
    method to throw an exception if the command returned a non-zero exit
    value.  It also avoid invoking a shell to run the command if possible.

- capture

        $stdout = $env->capture( $command, @args );
        ($stdout, $stderr) = $env->capture( $command, @args );

    Execute the passed command in the environment defined by **$env** and
    returns content of its standard output and (optionally) standard error
    streams.

    If the **SysFatal** flag is set for this environment,
    **IPC::System::Simple::capture** is called, which will cause this
    method to throw an exception if the command returned a non-zero exit
    value.  It also avoid invoking a shell to run the command if possible.

- which

        $path = $env->which( $command );
        @paths = $env->which( $command );

    Return the path (or paths in list mode) of the passed command using
    [File::Which](https://metacpan.org/pod/File::Which).  It returns `undef` or an empty list if the command
    is not found.

## Changing Default Option Values

Default values for some options may be changed via any of the
following:

- Passing a hashref as the only argument when initially importing the
package:

        use App::Env \%Default;

- Calling the **config** function:

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

The following options may have their default values changed:

    Force  Cache  Site  SysFatal

# EXAMPLE USAGE

## A single application

This is the simplest case.  If you don't care if you "pollute" the
current environment, then simply

    use App::Env qw( ApplicationName );

## A single application with options

If the **CIAO** environment module provides a `Version` option:

    use App::Env ( 'CIAO', { AppOpts => { Version => 3.4 } } );

## Two compatible applications

If two applications can share an environment, and you don't mind
changing the current environment;

    use App::Env qw( Application1 Application2 );

If you need to preserve the environment you need to be a little more
circumspect.

    $env = App::Env->new( qw( Application1 Application 2 ) );
    $env->system( $command1, @args );
    $env->system( $command2, @args );

or even