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

FreeBSD Manual Pages

  
 
  

home | help
Path(3)		      User Contributed Perl Documentation	       Path(3)

NAME
       Env::Path - Advanced operations on path variables

SYNOPSIS
	 use Env::Path;

	 # basic usage
	 my $manpath = Env::Path->MANPATH;
	 $manpath->Append('/opt/samba/man');
	 for ($manpath->List) {	print $_, "\n" };

	 # similar to above using the "implicit	object"	shorthand
	 Env::Path->MANPATH;
	 MANPATH->Append('/opt/samba/man');
	 for (MANPATH->List) { print $_, "\n" };

	 # one-shot use
	 Env::Path->PATH->Append('/usr/sbin');

	 # Windows-ish example
	 use Env::Path qw(PATH);
	 PATH->Append('C:\\Program Files\\Debugging Tools for Windows');
	 print "$_\n" for (PATH->List);

	 # change instances of /usr/local/bin to an architecture-specific dir
	 Env::Path->PATH->Replace('/usr/local/bin', "/usr/local/$ENV{PLATFORM}/bin");

	 # more	complex	use (different names for same semantics)
	 my $libpath;
	 if ($^O =~ /aix/) {
	     $libpath =	Env::Path->LIBPATH;
	 } else	{
	     $libpath =	Env::Path->LD_LIBRARY_PATH;
	 }
	 $libpath->Assign(qw(/usr/lib /usr/openwin/lib));
	 $libpath->Prepend('/usr/ucblib') unless $libpath->Contains('/usr/ucblib');
	 $libpath->InsertAfter('/usr/ucblib', '/xx/yy/zz');
	 $libpath->Uniqify;
	 $libpath->DeleteNonexistent;
	 $libpath->Remove('/usr/local/lib');
	 print $libpath->Name, ":";
	 for ($libpath->List) {	print "	$_" };
	 print "\n";

	 # simplest usage: bless all existing EV's as Env::Path	objects
	 use Env::Path ':all';
	 my @cats = PATH->Whence('cat*');
	 print "@cats\n";

DESCRIPTION
       Env::Path presents an object-oriented interface to path variables,
       defined as that subclass	of environment variables which name an ordered
       list of filesystem elements separated by	a platform-standard separator
       (typically ':' on UNIX and ';' on Windows).

       Of course, core Perl constructs such

	 $ENV{PATH} .= ":/usr/local/bin";

       will suffice for	most uses. Env::Path is	for the	others;	cases where
       you need	to insert or remove interior path entries, strip redundancies,
       operate on a pathvar without having to know whether the current
       platform	uses ":" or ";", operate on a pathvar which may	have a
       different name on different platforms, etc.

       The OO interface	is slightly unusual in that the	environment variable
       is itself the object and	the constructor	is Env::Path->AUTOLOAD(); thus

	   Env::Path->MANPATH;

       will bless $ENV{MANPATH}	into its package while leaving it otherwise
       unmodified (with	the exception of possible autovivification).  Unlike
       most objects, this is a scalar and thus can have	only one attribute;
       its value.

       In other	words, Env::Path simply	defines	a set of methods a path
       variable	may call on itself without changing the	variable's value or
       other semantics.

       Also, while the object reference	may be assigned	and used in the	normal
       style

	   my $path = Env::Path->CLASSPATH;
	   $path->Append('/opt/foo/classes.jar');

       a shorthand is also available:

	   Env::Path->CLASSPATH;
	   CLASSPATH->Append('/opt/foo/classes.jar');

       I.e. the	name of	the path variable may be used as a proxy for its
       object reference. This may be done at 'use' time	too:

	   use Env::Path qw(PATH CLASSPATH);   # or qw(:all) to	bless all EV's
	   CLASSPATH->Append('/opt/foo/classes.jar');

       The design is intended to make use of this module as lightweight	as
       possible.  Rather than creating a new object to manage an environment
       variable, the environment variable is provided a	set of methods for
       self-modification but is	otherwise left undisturbed and can be used in
       all normal ways.

   CLASS METHODS
       o   <CONSTRUCTOR>

	   The constructor may have any	name; it's assumed to name a path
	   variable as defined above. Returns the object reference.

       o   PathSeparator

	   Returns or sets the platform-specific path separator	character, by
	   default : on	open platforms and ; on	monopolistic ones.

   INSTANCE METHODS
       Unless otherwise	indicated these	methods	return the object reference,
       allowing	method calls to	be strung together. All	methods	which take
       lists join them together	using the value	of "Env::Path->PathSeparator".

       o   Name

	   Returns the name of the pathvar.

       o   Contains

	   Returns true	iff the	specified entry	is present in the pathvar.

       o   Assign

	   Takes a list	and sets the pathvar to	that value, separated by the
	   current PathSeparator.

       o   List

	   Returns the current path in list format.

       o   Prepend

	   For each entry in the supplied list,	removes	it from	the pathvar if
	   present and prepends	it, thus ensuring that it's present exactly
	   once	and at the front.

       o   Append

	   Analogous to	Prepend.

       o   InsertBefore

	   Takes a <dirname> and a list, inserts the list just before the
	   first instance of the <dirname>. If dirname is not found, works
	   just	like Prepend. As with Prepend, duplicates of the supplied
	   entries are removed.

       o   InsertAfter

	   Analogous to	InsertBefore

       o   Remove

	   Removes the specified entries from the path.

       o   Replace

	   Takes a /pattern/ and a list. Traverses the path and	replaces all
	   entries which match the pattern with	the concatenated list entries.

       o   ListNonexistent

	   Returns a list of all entries which do not exist as filesystem
	   entities.

       o   DeleteNonexistent

	   Removes from	the path all entries which do not exist	as filesystem
	   entities.

       o   Uniqify

	   Removes redundant entries (the 2nd through nth instances of each
	   entry).

       o   Whence

	   Takes a pattern and returns an ordered list of all filenames	found
	   along the path which	match it and are executable.

       o   Shell

	   Returns a string suitable for passing to a shell which would	set
	   and export the pathvar to its current value within the shell
	   context.

NOTES
       o   No provision	is made	for path variables which are not also
	   environment variables, a situation which is technically possible
	   but quite rare.

       o   Except where	necessary no assumption	is made	that path entries
	   should be directories, because pathvars like	CLASSPATH may contain
	   "virtual dirs" such as zip/jar files. For instance the
	   DeleteNonexistent method does not remove entries which are files.
	   In Perl terms the test applied is "-e", not "-d".

       o   The shorthand notation for pathvar FOO is implemented by hacking
	   @FOO::ISA, so there's a slight risk of namespace collision if your
	   code	also creates packages with all-upper-case names. No packages
	   are created unless the shorthand notation is	employed.

       o   There's some	cute code in the Env module by Gregor N. Purdy for
	   splitting pathvars into arrays using	ties. I'd love to be able to
	   take	advantage of that, and it pains	me to do the same thing	(and
	   not as well)	here rather than using Env. Unfortunately it's a
	   newish feature (5.6.0? 5.005? 5.6.1?) in Env	and I don't want
	   Env::Path to	be "tied" to the very latest Perls.

WORKS ON
       UNIX and	Windows.

AUTHOR
       David Boyce <dsbperl AT boyski.com>

COPYRIGHT
       Copyright (c) 2000-2001 David Boyce. All	rights reserved.  This Perl
       program is free software; you may redistribute and/or modify it under
       the same	terms as Perl itself.

SEE ALSO
       perl(1),	perlobj(1), Env::Array(3), Env(3)

perl v5.32.1			  2013-05-14			       Path(3)

NAME | SYNOPSIS | DESCRIPTION | NOTES | WORKS ON | AUTHOR | COPYRIGHT | SEE ALSO

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

home | help