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
       •   <CONSTRUCTOR>

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

       •   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".

       •   Name

           Returns the name of the pathvar.

       •   Contains

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

       •   Assign

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

       •   List

           Returns the current path in list format.

       •   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.

       •   Append

           Analogous to Prepend.

       •   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.

       •   InsertAfter

           Analogous to InsertBefore

       •   Remove

           Removes the specified entries from the path.

       •   Replace

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

       •   ListNonexistent

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

       •   DeleteNonexistent

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

       •   Uniqify

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

       •   Whence

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

       •   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

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

       •   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".

       •   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.

       •   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)