Env::Path(3pm)

1Path(3)               User Contributed Perl Documentation              Path(3)
2
3
4

NAME

6       Env::Path - Advanced operations on path variables
7

SYNOPSIS

9         use Env::Path;
10
11         # basic usage
12         my $manpath = Env::Path->MANPATH;
13         $manpath->Append('/opt/samba/man');
14         for ($manpath->List) { print $_, "\n" };
15
16         # similar to above using the "implicit object" shorthand
17         Env::Path->MANPATH;
18         MANPATH->Append('/opt/samba/man');
19         for (MANPATH->List) { print $_, "\n" };
20
21         # one-shot use
22         Env::Path->PATH->Append('/usr/sbin');
23
24         # Windows-ish example
25         use Env::Path qw(PATH);
26         PATH->Append('C:\\Program Files\\Debugging Tools for Windows');
27         print "$_\n" for (PATH->List);
28
29         # change instances of /usr/local/bin to an architecture-specific dir
30         Env::Path->PATH->Replace('/usr/local/bin', "/usr/local/$ENV{PLATFORM}/bin");
31
32         # more complex use (different names for same semantics)
33         my $libpath;
34         if ($^O =~ /aix/) {
35             $libpath = Env::Path->LIBPATH;
36         } else {
37             $libpath = Env::Path->LD_LIBRARY_PATH;
38         }
39         $libpath->Assign(qw(/usr/lib /usr/openwin/lib));
40         $libpath->Prepend('/usr/ucblib') unless $libpath->Contains('/usr/ucblib');
41         $libpath->InsertAfter('/usr/ucblib', '/xx/yy/zz');
42         $libpath->Uniqify;
43         $libpath->DeleteNonexistent;
44         $libpath->Remove('/usr/local/lib');
45         print $libpath->Name, ":";
46         for ($libpath->List) { print " $_" };
47         print "\n";
48
49         # simplest usage: bless all existing EV's as Env::Path objects
50         use Env::Path ':all';
51         my @cats = PATH->Whence('cat*');
52         print "@cats\n";
53

DESCRIPTION

55       Env::Path presents an object-oriented interface to path variables,
56       defined as that subclass of environment variables which name an ordered
57       list of filesystem elements separated by a platform-standard separator
58       (typically ':' on UNIX and ';' on Windows).
59
60       Of course, core Perl constructs such
61
62         $ENV{PATH} .= ":/usr/local/bin";
63
64       will suffice for most uses. Env::Path is for the others; cases where
65       you need to insert or remove interior path entries, strip redundancies,
66       operate on a pathvar without having to know whether the current
67       platform uses ":" or ";", operate on a pathvar which may have a
68       different name on different platforms, etc.
69
70       The OO interface is slightly unusual in that the environment variable
71       is itself the object and the constructor is Env::Path->AUTOLOAD(); thus
72
73           Env::Path->MANPATH;
74
75       will bless $ENV{MANPATH} into its package while leaving it otherwise
76       unmodified (with the exception of possible autovivification).  Unlike
77       most objects, this is a scalar and thus can have only one attribute;
78       its value.
79
80       In other words, Env::Path simply defines a set of methods a path
81       variable may call on itself without changing the variable's value or
82       other semantics.
83
84       Also, while the object reference may be assigned and used in the normal
85       style
86
87           my $path = Env::Path->CLASSPATH;
88           $path->Append('/opt/foo/classes.jar');
89
90       a shorthand is also available:
91
92           Env::Path->CLASSPATH;
93           CLASSPATH->Append('/opt/foo/classes.jar');
94
95       I.e. the name of the path variable may be used as a proxy for its
96       object reference. This may be done at 'use' time too:
97
98           use Env::Path qw(PATH CLASSPATH);   # or qw(:all) to bless all EV's
99           CLASSPATH->Append('/opt/foo/classes.jar');
100
101       The design is intended to make use of this module as lightweight as
102       possible.  Rather than creating a new object to manage an environment
103       variable, the environment variable is provided a set of methods for
104       self-modification but is otherwise left undisturbed and can be used in
105       all normal ways.
106
107   CLASS METHODS
108       •   <CONSTRUCTOR>
109
110           The constructor may have any name; it's assumed to name a path
111           variable as defined above. Returns the object reference.
112
113       •   PathSeparator
114
115           Returns or sets the platform-specific path separator character, by
116           default : on open platforms and ; on monopolistic ones.
117
118   INSTANCE METHODS
119       Unless otherwise indicated these methods return the object reference,
120       allowing method calls to be strung together. All methods which take
121       lists join them together using the value of "Env::Path->PathSeparator".
122
123       •   Name
124
125           Returns the name of the pathvar.
126
127       •   Contains
128
129           Returns true iff the specified entry is present in the pathvar.
130
131       •   Assign
132
133           Takes a list and sets the pathvar to that value, separated by the
134           current PathSeparator.
135
136       •   List
137
138           Returns the current path in list format.
139
140       •   Prepend
141
142           For each entry in the supplied list, removes it from the pathvar if
143           present and prepends it, thus ensuring that it's present exactly
144           once and at the front.
145
146       •   Append
147
148           Analogous to Prepend.
149
150       •   InsertBefore
151
152           Takes a <dirname> and a list, inserts the list just before the
153           first instance of the <dirname>. If dirname is not found, works
154           just like Prepend. As with Prepend, duplicates of the supplied
155           entries are removed.
156
157       •   InsertAfter
158
159           Analogous to InsertBefore
160
161       •   Remove
162
163           Removes the specified entries from the path.
164
165       •   Replace
166
167           Takes a /pattern/ and a list. Traverses the path and replaces all
168           entries which match the pattern with the concatenated list entries.
169
170       •   ListNonexistent
171
172           Returns a list of all entries which do not exist as filesystem
173           entities.
174
175       •   DeleteNonexistent
176
177           Removes from the path all entries which do not exist as filesystem
178           entities.
179
180       •   Uniqify
181
182           Removes redundant entries (the 2nd through nth instances of each
183           entry).
184
185       •   Whence
186
187           Takes a pattern and returns an ordered list of all filenames found
188           along the path which match it and are executable.
189
190       •   Shell
191
192           Returns a string suitable for passing to a shell which would set
193           and export the pathvar to its current value within the shell
194           context.
195

NOTES

197       •   No provision is made for path variables which are not also
198           environment variables, a situation which is technically possible
199           but quite rare.
200
201       •   Except where necessary no assumption is made that path entries
202           should be directories, because pathvars like CLASSPATH may contain
203           "virtual dirs" such as zip/jar files. For instance the
204           DeleteNonexistent method does not remove entries which are files.
205           In Perl terms the test applied is "-e", not "-d".
206
207       •   The shorthand notation for pathvar FOO is implemented by hacking
208           @FOO::ISA, so there's a slight risk of namespace collision if your
209           code also creates packages with all-upper-case names. No packages
210           are created unless the shorthand notation is employed.
211
212       •   There's some cute code in the Env module by Gregor N. Purdy for
213           splitting pathvars into arrays using ties. I'd love to be able to
214           take advantage of that, and it pains me to do the same thing (and
215           not as well) here rather than using Env. Unfortunately it's a
216           newish feature (5.6.0? 5.005? 5.6.1?) in Env and I don't want
217           Env::Path to be "tied" to the very latest Perls.
218

WORKS ON

220       UNIX and Windows.
221

AUTHOR

223       David Boyce <dsbperl AT boyski.com>
224

COPYRIGHT

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