Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Shell::EnvImporter(3) User Contributed Perl DocumentationShell::EnvImporter(3)

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

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	ignore() and ignore_*()	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 import_added is true, new variables added to
       the environment will be imported.  If import_modified is	true,
       variables whose value is	changed	will be	imported.  If import_removed
       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
       new()
	     Create a new Shell::EnvImporter object.  Parameters are:

       shell
	   Name	of the shell to	use.  Currently	supported: 'bash', 'csh',
	   'ksh', 'sh',	'tcsh',	'zsh', and of course, 'perl'.  :)

       command
	   Command to run in the language of the specified shell.  Overridden
	   by file.

       file
	   File	to be "sourced"	by the specified shell.

       auto_run
	   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 run()
	   is called.

       auto_import
	   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 import() (or	import_filtered()) is
	   called.

       import_added
       import_modified
       import_removed
	   Specify import policy. (See CONTROLLING IMPORTS above).

       import_filter
	   Use the supplied code ref to	filter imports.	 Overrides import
	   policy settings. (See CONTROLLING IMPORTS above).

METHODS
       run()
       run($command)
	   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 run()	without	a command if none was supplied
	   in the constructor.

       env_import()
       env_import($var)
       env_import(@vars)
       env_import(\@vars)
	   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.

       env_import_filtered()
       env_import_filtered(\&filter)
	   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	env_import_filtered()
	   without a filter if none was	supplied in the	constructor.

       restore_env()
	   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
       result()
	   Returns the importer's Shell::EnvImporter::Result object.

       shellobj()
	   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.

perl v5.24.1			  2008-06-04		 Shell::EnvImporter(3)

NAME | SYNOPSIS | DESCRIPTION | CONTROLLING IMPORTS | CONSTRUCTOR | METHODS | DATA MEMBERS | EXAMPLES | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Shell::EnvImporter&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help