.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Path 3pm"
.TH Path 3pm "2018-02-25" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Env::Path \- Advanced operations on path variables
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Env::Path;
\&
\&  # basic usage
\&  my $manpath = Env::Path\->MANPATH;
\&  $manpath\->Append(\*(Aq/opt/samba/man\*(Aq);
\&  for ($manpath\->List) { print $_, "\en" };
\&
\&  # similar to above using the "implicit object" shorthand
\&  Env::Path\->MANPATH;
\&  MANPATH\->Append(\*(Aq/opt/samba/man\*(Aq);
\&  for (MANPATH\->List) { print $_, "\en" };
\&
\&  # one\-shot use
\&  Env::Path\->PATH\->Append(\*(Aq/usr/sbin\*(Aq);
\&
\&  # Windows\-ish example
\&  use Env::Path qw(PATH);
\&  PATH\->Append(\*(AqC:\e\eProgram Files\e\eDebugging Tools for Windows\*(Aq);
\&  print "$_\en" for (PATH\->List);
\&
\&  # change instances of /usr/local/bin to an architecture\-specific dir
\&  Env::Path\->PATH\->Replace(\*(Aq/usr/local/bin\*(Aq, "/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(\*(Aq/usr/ucblib\*(Aq) unless $libpath\->Contains(\*(Aq/usr/ucblib\*(Aq);
\&  $libpath\->InsertAfter(\*(Aq/usr/ucblib\*(Aq, \*(Aq/xx/yy/zz\*(Aq);
\&  $libpath\->Uniqify;
\&  $libpath\->DeleteNonexistent;
\&  $libpath\->Remove(\*(Aq/usr/local/lib\*(Aq);
\&  print $libpath\->Name, ":";
\&  for ($libpath\->List) { print " $_" };
\&  print "\en";
\&
\&  # simplest usage: bless all existing EV\*(Aqs as Env::Path objects
\&  use Env::Path \*(Aq:all\*(Aq;
\&  my @cats = PATH\->Whence(\*(Aqcat*\*(Aq);
\&  print "@cats\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Env::Path presents an object-oriented interface to \fIpath variables\fR,
defined as that subclass of \fIenvironment variables\fR which name an
ordered list of filesystem elements separated by a platform-standard
\&\fIseparator\fR (typically ':' on \s-1UNIX\s0 and ';' on Windows).
.PP
Of course, core Perl constructs such
.PP
.Vb 1
\&  $ENV{PATH} .= ":/usr/local/bin";
.Ve
.PP
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 \*(L":\*(R" or \*(L";\*(R", operate on a pathvar which may have a
different name on different platforms, etc.
.PP
The \s-1OO\s0 interface is slightly unusual in that the environment variable
is itself the object and the constructor is Env::Path\->\s-1\fIAUTOLOAD\s0()\fR; thus
.PP
.Vb 1
\&    Env::Path\->MANPATH;
.Ve
.PP
will bless \f(CW$ENV\fR{\s-1MANPATH\s0} 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.
.PP
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.
.PP
Also, while the object reference may be assigned and used in the normal
style
.PP
.Vb 2
\&    my $path = Env::Path\->CLASSPATH;
\&    $path\->Append(\*(Aq/opt/foo/classes.jar\*(Aq);
.Ve
.PP
a shorthand is also available:
.PP
.Vb 2
\&    Env::Path\->CLASSPATH;
\&    CLASSPATH\->Append(\*(Aq/opt/foo/classes.jar\*(Aq);
.Ve
.PP
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:
.PP
.Vb 2
\&    use Env::Path qw(PATH CLASSPATH);   # or qw(:all) to bless all EV\*(Aqs
\&    CLASSPATH\->Append(\*(Aq/opt/foo/classes.jar\*(Aq);
.Ve
.PP
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.
.SS "\s-1CLASS METHODS\s0"
.IX Subsection "CLASS METHODS"
.IP "\(bu" 4
<\s-1CONSTRUCTOR\s0>
.Sp
The constructor may have any name; it's assumed to name a \fIpath
variable\fR as defined above. Returns the object reference.
.IP "\(bu" 4
PathSeparator
.Sp
Returns or sets the platform-specific path separator character, by
default \fI:\fR on open platforms and \fI;\fR on monopolistic ones.
.SS "\s-1INSTANCE METHODS\s0"
.IX Subsection "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 \f(CW\*(C`Env::Path\->PathSeparator\*(C'\fR.
.IP "\(bu" 4
Name
.Sp
Returns the name of the pathvar.
.IP "\(bu" 4
Contains
.Sp
Returns true iff the specified entry is present in the pathvar.
.IP "\(bu" 4
Assign
.Sp
Takes a list and sets the pathvar to that value, separated by the
current PathSeparator.
.IP "\(bu" 4
List
.Sp
Returns the current path in list format.
.IP "\(bu" 4
Prepend
.Sp
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.
.IP "\(bu" 4
Append
.Sp
Analogous to Prepend.
.IP "\(bu" 4
InsertBefore
.Sp
Takes a <dirname> and a list, inserts the list just before the first
instance of the <dirname>. If \fIdirname\fR is not found, works just like
\&\fIPrepend\fR. As with \fIPrepend\fR, duplicates of the supplied entries are
removed.
.IP "\(bu" 4
InsertAfter
.Sp
Analogous to \fIInsertBefore\fR
.IP "\(bu" 4
Remove
.Sp
Removes the specified entries from the path.
.IP "\(bu" 4
Replace
.Sp
Takes a /pattern/ and a list. Traverses the path and replaces all
entries which match the pattern with the concatenated list entries.
.IP "\(bu" 4
ListNonexistent
.Sp
Returns a list of all entries which do not exist as filesystem
entities.
.IP "\(bu" 4
DeleteNonexistent
.Sp
Removes from the path all entries which do not exist as filesystem
entities.
.IP "\(bu" 4
Uniqify
.Sp
Removes redundant entries (the 2nd through nth instances of each entry).
.IP "\(bu" 4
Whence
.Sp
Takes a pattern and returns an ordered list of all filenames found
along the path which match it and are executable.
.IP "\(bu" 4
Shell
.Sp
Returns a string suitable for passing to a shell which would set and export
the pathvar to its current value within the shell context.
.SH "NOTES"
.IX Header "NOTES"
.IP "\(bu" 4
No provision is made for path variables which are not also environment
variables, a situation which is technically possible but quite rare.
.IP "\(bu" 4
Except where necessary no assumption is made that path entries should
be directories, because pathvars like \s-1CLASSPATH\s0 may contain \*(L"virtual
dirs\*(R" such as zip/jar files. For instance the \fIDeleteNonexistent\fR
method does not remove entries which are files.  In Perl terms the test
applied is \f(CW\*(C`\-e\*(C'\fR, not \f(CW\*(C`\-d\*(C'\fR.
.IP "\(bu" 4
The shorthand notation for pathvar \fI\s-1FOO\s0\fR is implemented by hacking
\&\fI\f(CI@FOO::ISA\fI\fR, 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.
.IP "\(bu" 4
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 \*(L"tied\*(R" to the
very latest Perls.
.SH "WORKS ON"
.IX Header "WORKS ON"
\&\s-1UNIX\s0 and Windows.
.SH "AUTHOR"
.IX Header "AUTHOR"
David Boyce <dsbperl \s-1AT\s0 boyski.com>
.SH "COPYRIGHT"
.IX Header "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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), \fIperlobj\fR\|(1), \fIEnv::Array\fR\|(3), \fIEnv\fR\|(3)