view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

- 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