1Path(3) User Contributed Perl Documentation Path(3)
2
3
4
6 Env::Path - Advanced operations on path variables
7
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
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
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
220 UNIX and Windows.
221
223 David Boyce <dsbperl AT boyski.com>
224
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
231 perl(1), perlobj(1), Env::Array(3), Env(3)
232
233
234
235perl v5.36.0 2022-07-22 Path(3)