GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  SHELL::ENVIMPORTER (3)

.ds Aq ’

NAME

Shell::EnvImporter - Perl extension for importing environment variable changes from external commands or shell scripts

CONTENTS

SYNOPSIS



  use Shell::EnvImporter;

  # Import environment variables exported from a shell script
  my $sourcer  = Shell::EnvImporter->new(
                   file => $filename,
                 );

  # Import environment variables exported from a shell command
  my $runner   = Shell::EnvImporter->new(
                   command => $shell_command,
                 );


  # Exert more control over the process
  my $importer = Shell::EnvImporter->new(
                   shell           => $shellname,

                   command         => $command,
                   # -- OR --
                   file            => $file,

                   auto_run        => 0,
                   auto_import     => 0,

                   import_modified => 1,
                   import_added    => 1,
                   import_removed  => 1,
                   # -- OR --
                   import_filter   => $coderef
                 );

  my $result = $importer->run() or die "Run failed: $@";


  # Manual import by policy
  $importer->env_import();

  # -- OR --

  # Manual import by filter
  $importer->env_import_filtered();


  # Restore environment
  $importer->restore_env or die "Restore failed: $@";



DESCRIPTION

Shell::EnvImporter allows you to import environment variable changes exported by an external script or command into the current environment. The process happens in (up to) three stages:

Execution



 - saves a backup copy of the current environment (%ENV)

 - creates a shell script that sources the specified file (or runs the
   specified command) and prints out the environment

 - runs the shell script in a separate process

 - parses the output to determine success or failure and, on success,
   any changes to the environment



Importation



 - imports variable changes by policy or filter.



Restoration



 - restores the environment (%ENV) to pre-run state



If ’auto_run’ is true (the default), execution is kicked off automatically by the constructor. If ’auto_import’ is true (the default), importation is kicked off automatically after execution. Restoration never happens automatically; you must call the restore() method explicitly.

CONTROLLING IMPORTS

Imports are controlled by two factors:



  - the shell ignore list

  - the import policy or the import filter



The shell ignore list is a list of variables to ignore, maintained by the shell object. These are generally variables that are changed automatically by the shell (e.g. SHLVL and PWD), providing little information to a noninteractive shell. The ignore list can be modified using the shell object’s <B>B>ignore()<B>B> and <B>ignore_*()B> methods; see the Shell::EnvImporter::Shell documentation for details. The ignore list overrides the import policy or the import filter (whichever is in effect).

An import policy indicates what action to take for each kind of environment change. If <B>import_addedB> is true, new variables added to the environment will be imported. If <B>import_modifiedB> is true, variables whose value is changed will be imported. If <B>import_removedB> is true, variables unset by the external script or command will be removed from the environment. The default policy is to import added and modified variables but not removed variables.

An import filter provides more control over importation. The import filter is a reference to a function that will be called with the variable name, the new value, and the type of change (’added’, ’modified’ or ’removed’); if it returns a true value, the variable will be imported. The import filter, if provided, overrides the import policy.

CONSTRUCTOR

<B>B>new()<B>B>


  Create a new Shell::EnvImporter object.  Parameters are:



<B>shellB> Name of the shell to use. Currently supported: ’bash’, ’csh’, ’ksh’, ’sh’, ’tcsh’, ’zsh’, and of course, ’perl’. :)
<B>commandB> Command to run in the language of the specified shell. Overridden by <B>fileB>.
<B>fileB> File to be sourced by the specified shell.
<B>auto_runB> If set to a true value (the default), Shell::EnvImporter will run the shell command (or source the file) immediately, from the constructor. Set to a false value to delay execution until <B>B>run()<B>B> is called.
<B>auto_importB> If set to a true value (the default), import the changed environment immediately after running the command. Set to a false value to delay the import until <B>B>import()<B>B> (or <B>B>import_filtered()<B>B>) is called.
<B>import_addedB>
<B>import_modifiedB>
<B>import_removedB> Specify import policy. (See CONTROLLING IMPORTS above).
<B>import_filterB> Use the supplied code ref to filter imports. Overrides import policy settings. (See CONTROLLING IMPORTS above).

METHODS

<B>B>run()<B>B>
<B>run($command)B> Run the supplied command, or run the command (or source the file) supplied during construction, returning a Shell::EnvImporter::Result object or undef with $@ set on error. It is an error to call <B>B>run()<B>B> without a command if none was supplied in the constructor.
<B>B>env_import()<B>B>
<B>env_import($var)B>
<B>env_import(@vars)B>
<B>env_import(\@vars)B> Perform a policy import (see CONTROLLING IMPORTS above). If an optional list (or array reference) of variable names is supplied, the import is restricted to those variables (subject to import policy). Returns a Shell::EnvImporter::Result object or undef with $@ set on error.
<B>B>env_import_filtered()<B>B>
<B>env_import_filtered(\&filter)B> Perform a filtered import (see CONTROLLING IMPORTS above), returning a Shell::EnvImporter::Result object or undef with $@ set on error. If no filter is supplied, the filter supplied to the constructor is used. It is an error to call <B>B>env_import_filtered()<B>B> without a filter if none was supplied in the constructor.
<B>B>restore_env()<B>B> Restores the current environment (%ENV) to its state before shell script execution. It is an error to call restore_env before a successful run.

DATA MEMBERS

<B>B>result()<B>B> Returns the importer’s Shell::EnvImporter::Result object.
<B>B>shellobj()<B>B> Returns the importer’s Shell::EnvImporter::Shell object.

EXAMPLES

    - Command Import



    # Import environment variables set by a shell command
    my $importer = Shell::EnvImporter->new(
                     command => ssh-agent
                   ) or die $@;



    - ‘‘Sourced’’ File Import



    # Import environment variables exported by a configuration file
    my $importer = Shell::EnvImporter->new(
                     file => "$ENV{HOME}/.profile"
                   ) or die $@;



    - Policy import - modified only, bash script



    my $importer = Shell::EnvImporter->new(
                     file            => /etc/bashrc,
                     shell           => bash,
                     import_modified => 1,
                     import_added    => 0,
                     import_removed  => 0,
                   );



    - Import a specific variable



    my $file     = /etc/mydaemon.conf;
    my $importer = Shell::EnvImporter->new(
                     file            => $file,
                     shell           => bash,
                     auto_import     => 0,
                   );

    my $result = $importer->env_import(MAX_CLIENTS);

    if ($result->succeeded) {
      print "Max clients: $ENV{MAX_CLIENTS}\n";
    } else {
      die("Error:  Source of $file failed: ", $result->stderr, "\n");
    }



    - Filtered import - all ’DB*’ vars whose value references my homedir



    my $file     = /etc/mydaemon.conf;

    my $filter = sub {
      my($var, $value, $change) = @_;

      return ($var =~ /^DB/ and $value =~ /$ENV{HOME}/);
    };

    my $importer = Shell::EnvImporter->new(
                     file            => $file,
                     shell           => bash,
                     import_filter   => $filter,
                   );

    print "Imported:  ", join(", ", $importer->result->imported), "\n";



    - Unexported Variables in Bourne-like shells



    # Get the default system font from /etc/sysconfig/i18n (a /bin/sh
    # script).  Note that the variable is NOT exported, only set, so we
    # use the set command to print the environment.

    my $sourcer  = Shell::EnvImporter->new(
                     file => /etc/sysconfig/i18n,
                   ) or die $@;

    $sourcer->shellobj->envcmd(set);

    $sourcer->run();

    print "System font: $ENV{SYSFONT}\n";



SEE ALSO

Shell::EnvImporter::Result Shell::EnvImporter::Shell

AUTHOR

David Faraldo, <dfaraldo@cpan.org>

COPYRIGHT AND LICENSE



  Copyright (C) 2005-2006 by Dave Faraldo

  This library is free software; you can redistribute it and/or modify it
  under the same terms as Perl itself.  No warranty is expressed or implied.



Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 SHELL::ENVIMPORTER (3) 2008-06-04

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.