view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

    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
    depends upon the type of argument and which of the
    following contexts matches:

    1. If called with no arguments (or just an **Exclude** option,
    as discussed below) return a hashref containing the environment.
    2. If called in a scalar context and passed a single variable name
    (which must be a string) return the value for that variable,
    or _undef_ if it is not in the environment.
    3. If called in a list context and passed a list of variable names
    (which must be strings) return an array of values for those variables
    (_undef_ for those not in the environment).
    4. If called in a scalar context and passed one or more _match
    specifications_, return a hashref containing the subset
    of the environment which matches.  The `Exclude` option (see below)
    may be present.

        A _match specification_ may be a string, (for an exact match of a
        variable name), a regular expression created with the **qr** operator,
        or a subroutine reference.  The subroutine will be passed two
        arguments, the variable name and its value, and should return true if
        the variable should be excluded, false otherwise.

        To avoid mistaking this context for context 1 if the _match specification_
        is a single string, enclose it in an array, e.g.

            # this is context 1
            $value = $env->env( $variable_name );

            # this is context 3
            $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 );