view release on metacpan or  search on metacpan

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

  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.

=over

=item AppOpts I<hashref>

This is a hash of options to pass to the
C<App::Env::E<lt>applicationE<gt>> module.  Their meanings are
application specific.

This option may not be shared.

=item Force I<boolean>

Don't use the cached environment for this application.

=item Site

Specify a site.  See L</Application Environments> for more
information.  Set this to C<undef> or the empty string C<''> to ignore
(rather than replace) the default site.  For example, if the default
site is C<Site1>, then setting C<< $application = 'MyApp' >> and C<<
Site => undef >> will clear load C<App::Env::MyApp>, not
C<App::Env::Site1::MyApp>.

=item Cache I<boolean>

Cache (or don't cache) the environment. By default it is cached.  If
multiple environments are loaded the I<combination> is also cached.

=item CacheID

A unique name for the environment. See L</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
C<AppID>, the full module name will be used as the cache id (ignoring
the contents of the B<AppOpts> option hash).

=item SysFatal I<boolean>

If true, the B<system>, B<qexec>, and B<capture> object methods will throw
an exception if the passed command exits with a non-zero error.

=item Temp I<boolean>

If true, and the requested environment does not exist in the cache,
create it but do not cache it (this overrides the B<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

=back

=item retrieve

  $env = App::Env::retrieve( $cacheid );

Retrieve the environment with the given cache id, or undefined if it
doesn't exist.

=back

=head2 Managing Environments

=over

=item config

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

Configure default options for environments.  See L<Changing Default
Option Values> for more information.

=item uncache

  App::Env::uncache( App => $app, [ Site => $site ] )
  App::Env::uncache( CacheID => $cacheid )

Delete the cache entry for the given application.  If C<Site> is not
specified, the site is determined as specified in L</Site Specific
Contexts>.

It is currently I<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 B<App::Env>
objects.

The available options are:

=over

=item App

The application name.  This may not be specified if B<CacheID> is
specified.

=item Site

If the B<Site> option was used when first loading the environment,

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

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
Perl B<system> command.

If the B<SysFatal> flag is set for this environment,
B<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.

=item exec

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

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

=item qexec

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

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

If the B<SysFatal> flag is set for this environment,
B<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.

=item capture

Execute a command in the environment defined by B<$env> and returns or
redirects the content of its standard output and error streams.
Check the C<$?> variable for the exit value of the command.

=over

=item *

Return the standard output stream

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

=item *

Return output, error and command exit value.

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

=item *

Return exit value and redirect standard output or error streams.

  $exit = $env->capture( $command, @args,
                 { stdout => $out, stderr => $err }
               );

C<$out> and C<$err> may either by filehandles (e.g. L<IO::File>
objects) or file names.

=back

For even more control of the output streams, consider calling
L<Capture::Tiny/capture> directly, e.g.

  my $exit;
  capture { $exit = $env->system( $command, @args ) }

If the B<SysFatal> flag is set for this environment,
B<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 avoids invoking a shell to run the command if possible.

=item which

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

Return the path (or paths in list mode) of the passed command using
L<File::Which>.  It returns C<undef> or an empty list if the command
is not found.

=back

=head2 Changing Default Option Values

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

=over

=item *

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

  use App::Env \%Default;

=item *

Calling the B<config> function:

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

=back

The following options may have their default values changed:

  Force  Cache  Site  SysFatal

=head1 EXAMPLE USAGE

=head2 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 );

=head2 A single application with options

If the B<CIAO> environment module provides a C<Version> option:

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

=head2 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 );