<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">package Env::Sanctify;
{
  $Env::Sanctify::VERSION = '1.10';
}

#ABSTRACT: Lexically scoped sanctification of %ENV

use strict;
use warnings;

sub sanctify {
  my $package = shift;
  my %opts = @_;
  $opts{lc $_} = delete $opts{$_} for keys %opts;
  delete $opts{env} unless $opts{env} and ref $opts{env} eq 'HASH';
  delete $opts{sanctify} unless $opts{sanctify} and ref $opts{sanctify} eq 'ARRAY';
  my $self = bless \%opts, $package;
  $self-&gt;_sanctify();
  return $self;
}

sub _sanctify {
  my $self = shift;
  $self-&gt;{_backup} = { };
  if ( $self-&gt;{sanctify} ) {
     foreach my $regex ( @{ $self-&gt;{sanctify} } ) {
	$self-&gt;{_backup}-&gt;{$_} = delete $ENV{$_} for grep { eval { /$regex/ } } keys %ENV;
     }
  }
  if ( $self-&gt;{env} ) {
     $self-&gt;{_backup}-&gt;{$_} = delete $ENV{$_} for grep { defined $ENV{$_} } keys %{ $self-&gt;{env} };
     $ENV{$_} = $self-&gt;{env}-&gt;{$_} for keys %{ $self-&gt;{env} };
  }
  return 1;
}

sub restore {
  my $self = shift;
  delete $ENV{$_} for keys %{ $self-&gt;{env} };
  $ENV{$_} = $self-&gt;{_backup}-&gt;{$_} for keys %{ $self-&gt;{_backup} };
  return $self-&gt;{_restored} = 1;
}

sub DESTROY {
  my $self = shift;
  $self-&gt;restore unless $self-&gt;{_restored};
}

'Sanctify yourself, set yourself free';

__END__

=pod

=head1 NAME

Env::Sanctify - Lexically scoped sanctification of %ENV

=head1 VERSION

version 1.10

=head1 SYNOPSIS

  my $sanctify = Env::Sanctify-&gt;sanctify( sanctify =&gt; [ '^POE' ] );

  # do some stuff, fork some processes etc.

  $sanctify-&gt;restore

  {

    my $sanctify = Env::Sanctify-&gt;sanctify( env =&gt; { POE_TRACE_DEFAULT =&gt; 1 } );

    # do some stuff, fork some processes etc.
  }

  # out of scope, %ENV is back to normal

=head1 DESCRIPTION

Env::Sanctify is a module that provides lexically scoped manipulation and sanctification of
C&lt;%ENV&gt;.

You can specify that it alter or add additional environment variables or remove existing ones
according to a list of matching regexen.

You can then either C&lt;restore&gt; the environment back manually or let the object fall out of
scope, which automagically restores.

Useful for manipulating the environment that forked processes and sub-processes will inherit.

=head1 CONSTRUCTOR

=over

=item C&lt;sanctify&gt;

Creates an Env::Sanctify object. Takes two optional arguments:

  'env', a hashref of env vars to add to %ENV;
  'sanctify', an arrayref of regex pattern strings to match against current %ENV vars;

Any C&lt;%ENV&gt; var that matches a C&lt;sanctify&gt; regex is removed from the resultant C&lt;%ENV&gt;.

=back

=head1 METHODs

=over

=item C&lt;restore&gt;

Explicitly restore the previous C&lt;%ENV&gt;. This is called automagically when the object is C&lt;DESTROY&gt;ed,
for instance, when it goes out of scope.

=back

=head1 CAVEATS

It has been reported that redefining the Env::Sanctify object causes unexpected behaviour.

  use strict;
  use warnings;

  use Env::Sanctify;

  $ENV{TEST} = 'Test thing';

  my $sanctify = Env::Sanctify-&gt;sanctify( sanctify =&gt; [ 'TEST' ] );

  printf "My ENV{TEST}: %s\n", $ENV{TEST};

  $sanctify = Env::Sanctify-&gt;sanctify( env =&gt; { TEST =&gt; 'Other answer' } );

  printf "My ENV{TEST}: %s\n", $ENV{TEST};

This script outputs:

  My ENV{TEST}:
  My ENV{TEST}: Test thing

=head1 AUTHOR

Chris Williams &lt;chris@bingosnet.co.uk&gt;

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Chris Williams.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut
</pre></body></html>