view release on metacpan or  search on metacpan

lib/App/Env.pm  view on Meta::CPAN

sub uncache {
    goto \&App::Env::_Util::uncache;
}


#-------------------------------------------------------

sub env {
    my $self = shift;
    my @opts = ( 'HASH' eq ref $_[-1] ? pop : {} );

    # mostly a duplicate of what's in str(). ick.
    my %opt = Params::Validate::validate(
        @opts,
        {
            Exclude => {
                callbacks => { 'type' => \&App::Env::_Util::exclude_param_check },
                default   => undef,
            },
            AllowIllegalVariableNames => {
                optional => 1,
                default  => !!1,
            },
        } );

    # Exclude is only allowed in scalar calling context where
    # @_ is empty, has more than one element, or the first element
    # is not a scalar.
    App::Env::_Util::croak( "Cannot use Exclude in this calling context\n" )
      if $opt{Exclude} && ( wantarray() || ( @_ == 1 && !ref $_[0] ) );    ## no critic (Community::Wantarray)

    my $include = [ @_ ? @_ : qr/.*/ ];
    my $env     = $self->_envhash;

    my @exclude
      = defined( $opt{Exclude} )
      ? ( 'ARRAY' eq ref $opt{Exclude} ? @{ $opt{Exclude} } : ( $opt{Exclude} ) )
      : ();

    # exclude any variables with non-word characters
    push @exclude, qr/\W/
      unless $opt{AllowIllegalVariableNames};

    my @vars = $self->_filter_env( $include, \@exclude );

    if ( wantarray() ) {    ## no critic (Community::Wantarray)
        return map { exists $env->{$_} ? $env->{$_} : undef } @vars;
    }
    elsif ( @_ == 1 && !ref $_[0] ) {
        return @vars && exists $env->{ $vars[0] } ? $env->{ $vars[0] } : undef;
    }
    else {
        my %env;
        @env{@vars} = map { exists $env->{$_} ? $env->{$_} : undef } @vars;
        return \%env;
    }
}

#-------------------------------------------------------

sub setenv {
    my $self = shift;
    my $var  = shift;

    defined $var
      or App::Env::_Util::croak( "missing variable name argument\n" );

    if ( @_ ) {
        $self->_envhash->{$var} = $_[0];
    }
    else {
        delete $self->_envhash->{$var};
    }
}

#-------------------------------------------------------

# return an env compatible string
sub str {
    my $self = shift;
    my @opts = ( 'HASH' eq ref $_[-1] ? pop : {} );

    # validate type.  Params::Validate doesn't do Regexp, so
    # this is a bit messy.
    my %opt = Params::Validate::validate(
        @opts,
        {
            Exclude => {
                callbacks => { 'type' => \&App::Env::_Util::exclude_param_check },
                optional  => 1,
            },
            AllowIllegalVariableNames => {
                optional => 1,
                default  => !!0,
            },
        } );

    my $include = [ @_ ? @_ : qr/.*/ ];
    my @exclude
      = defined( $opt{Exclude} )
      ? ( 'ARRAY' eq ref $opt{Exclude} ? @{ $opt{Exclude} } : ( $opt{Exclude} ) )
      : ();

    push @exclude, 'TERMCAP'
      if List::Util::none { $_ eq 'TERMCAP' } @$include;

    # exclude any variables with non-word characters
    push @exclude, qr/\W/
      unless $opt{AllowIllegalVariableNames};

    my $env  = $self->_envhash;
    my @vars = grep { exists $env->{$_} } $self->_filter_env( $include, \@exclude );
    return join( q{ }, map { "$_=" . App::Env::_Util::shell_escape( $env->{$_} ) } @vars );
}

#-------------------------------------------------------

# return a list of included variables, in the requested
# order, based upon a list of include and exclude specs.
# variable names  passed as plain strings are not checked
# for existance in the environment.

lib/App/Env.pm  view on Meta::CPAN

If called with no variable names or match specifications,
return the environment after filtering out variables
via the B<Exclude> or B<AllowIllegalVariableNames> options.

=item Context 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 I<undef> if it is not in the environment.

=item Context 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
(I<undef> for those not in the environment).

=item Context 4

If called in a scalar context and passed one or more I<match
specifications>, return a hashref containing the subset
of the environment which matches.  The C<Exclude> option (see below)
may be present.

A I<match specification> may be a string, (for an exact match of a
variable name), a regular expression created with the B<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 L</Context 1> if the I<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 ] );

=back

The B<%options> hash may contain the following entries:

=over

=item Exclude

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

=item AllowIllegalVariableNames

Not all variable names may be set with a shell command, but may be
inherited from the parent environment.  This option controls whether
such variables are returned by L</env>.  It defaults to true.

=back

=item setenv

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

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

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

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

=item 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 C<$;> (subscript separator) character.

=item str

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

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

The environment may be pared down by passing I<match specifications>
and an C<Exclude> option; see the documentation for the B<env> method,
L</Context 4>, for more information.

Because the B<TERMCAP> environment variable is often riddled with
escape characters, which are not always handled well by shells, the
B<TERMCAP> variable is I<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.

B<Note!> By default variables with illegal names (that is,
characters which match B<qr/\W/> are I<not> output).

To output them, set the B<AllowIllegalVariableNames> option to a true
value (it defaults to false).

The B<%options> hash may contain the following entries:

=over

=item AllowIllegalVariableNames

Not all variable names may be set with a shell command, but may be
inherited from the parent environment.  This option controls whether
such variables are returned by L</str>.  It defaults to false.

=back

=item system

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

This runs the passed command in the environment defined by B<$env>.
It has the same argument and returned value convention as the core