1Path::Class::File(3) User Contributed Perl Documentation Path::Class::File(3)
2
6 Path::Class::File - Objects representing files
7
9 version 0.37
10
12 use Path::Class; # Exports file() by default
13 my $file = file('foo', 'bar.txt'); # Path::Class::File object
15 my $file = Path::Class::File->new('foo', 'bar.txt'); # Same thing
16 # Stringifies to 'foo/bar.txt' on Unix, 'foo\bar.txt' on Windows, etc.
18 print "file: $file\n";
19 if ($file->is_absolute) { ... }
21 if ($file->is_relative) { ... }
22 my $v = $file->volume; # Could be 'C:' on Windows, empty string
24 # on Unix, 'Macintosh HD:' on Mac OS
25 $file->cleanup; # Perform logical cleanup of pathname
27 $file->resolve; # Perform physical cleanup of pathname
28 my $dir = $file->dir; # A Path::Class::Dir object
30 my $abs = $file->absolute; # Transform to absolute path
32 my $rel = $file->relative; # Transform to relative path
33
35 The "Path::Class::File" class contains functionality for manipulating
36 file names in a cross-platform way.
37
39 $file = Path::Class::File->new( <dir1>, <dir2>, ..., <file> )
40 $file = file( <dir1>, <dir2>, ..., <file> )
41 Creates a new "Path::Class::File" object and returns it. The
42 arguments specify the path to the file. Any volume may also be
43 specified as the first argument, or as part of the first argument.
44 You can use platform-neutral syntax:
45 my $file = file( 'foo', 'bar', 'baz.txt' );
47 or platform-native syntax:
49 my $file = file( 'foo/bar/baz.txt' );
51 or a mixture of the two:
53 my $file = file( 'foo/bar', 'baz.txt' );
55 All three of the above examples create relative paths. To create
57 an absolute path, either use the platform native syntax for doing
58 so:
59 my $file = file( '/var/tmp/foo.txt' );
61 or use an empty string as the first argument:
63 my $file = file( '', 'var', 'tmp', 'foo.txt' );
65 If the second form seems awkward, that's somewhat intentional -
67 paths like "/var/tmp" or "\Windows" aren't cross-platform concepts
68 in the first place, so they probably shouldn't appear in your code
69 if you're trying to be cross-platform. The first form is perfectly
70 fine, because paths like this may come from config files, user
71 input, or whatever.
72 $file->stringify
74 This method is called internally when a "Path::Class::File" object
75 is used in a string context, so the following are equivalent:
76 $string = $file->stringify;
78 $string = "$file";
79 $file->volume
81 Returns the volume (e.g. "C:" on Windows, "Macintosh HD:" on Mac
82 OS, etc.) of the object, if any. Otherwise, returns the empty
83 string.
84 $file->basename
86 Returns the name of the file as a string, without the directory
87 portion (if any).
88 $file->components
90 Returns a list of the directory components of this file, followed
91 by the basename.
92 Note: unlike "$dir->components", this method currently does not
94 accept any arguments to select which elements of the list will be
95 returned. It may do so in the future. Currently it throws an
96 exception if such arguments are present.
97 $file->is_dir
99 Returns a boolean value indicating whether this object represents a
100 directory. Not surprisingly, "Path::Class::File" objects always
101 return false, and Path::Class::Dir objects always return true.
102 $file->is_absolute
104 Returns true or false depending on whether the file refers to an
105 absolute path specifier (like "/usr/local/foo.txt" or
106 "\Windows\Foo.txt").
107 $file->is_relative
109 Returns true or false depending on whether the file refers to a
110 relative path specifier (like "lib/foo.txt" or ".\Foo.txt").
111 $file->cleanup
113 Performs a logical cleanup of the file path. For instance:
114 my $file = file('/foo//baz/./foo.txt')->cleanup;
116 # $file now represents '/foo/baz/foo.txt';
117 $dir->resolve
119 Performs a physical cleanup of the file path. For instance:
120 my $file = file('/foo/baz/../foo.txt')->resolve;
122 # $file now represents '/foo/foo.txt', assuming no symlinks
123 This actually consults the filesystem to verify the validity of the
125 path.
126 $dir = $file->dir
128 Returns a "Path::Class::Dir" object representing the directory
129 containing this file.
130 $dir = $file->parent
132 A synonym for the "dir()" method.
133 $abs = $file->absolute
135 Returns a "Path::Class::File" object representing $file as an
136 absolute path. An optional argument, given as either a string or a
137 Path::Class::Dir object, specifies the directory to use as the base
138 of relativity - otherwise the current working directory will be
139 used.
140 $rel = $file->relative
142 Returns a "Path::Class::File" object representing $file as a
143 relative path. An optional argument, given as either a string or a
144 "Path::Class::Dir" object, specifies the directory to use as the
145 base of relativity - otherwise the current working directory will
146 be used.
147 $foreign = $file->as_foreign($type)
149 Returns a "Path::Class::File" object representing $file as it would
150 be specified on a system of type $type. Known types include
151 "Unix", "Win32", "Mac", "VMS", and "OS2", i.e. anything for which
152 there is a subclass of "File::Spec".
153 Any generated objects (subdirectories, files, parents, etc.) will
155 also retain this type.
156 $foreign = Path::Class::File->new_foreign($type, @args)
158 Returns a "Path::Class::File" object representing a file as it
159 would be specified on a system of type $type. Known types include
160 "Unix", "Win32", "Mac", "VMS", and "OS2", i.e. anything for which
161 there is a subclass of "File::Spec".
162 The arguments in @args are the same as they would be specified in
164 "new()".
165 $fh = $file->open($mode, $permissions)
167 Passes the given arguments, including $file, to "IO::File->new"
168 (which in turn calls "IO::File->open" and returns the result as an
169 IO::File object. If the opening fails, "undef" is returned and $!
170 is set.
171 $fh = $file->openr()
173 A shortcut for
174 $fh = $file->open('r') or croak "Can't read $file: $!";
176 $fh = $file->openw()
178 A shortcut for
179 $fh = $file->open('w') or croak "Can't write to $file: $!";
181 $fh = $file->opena()
183 A shortcut for
184 $fh = $file->open('a') or croak "Can't append to $file: $!";
186 $file->touch
188 Sets the modification and access time of the given file to right
189 now, if the file exists. If it doesn't exist, "touch()" will make
190 it exist, and - YES! - set its modification and access time to now.
191 $file->slurp()
193 In a scalar context, returns the contents of $file in a string. In
194 a list context, returns the lines of $file (according to how $/ is
195 set) as a list. If the file can't be read, this method will throw
196 an exception.
197 If you want "chomp()" run on each line of the file, pass a true
199 value for the "chomp" or "chomped" parameters:
200 my @lines = $file->slurp(chomp => 1);
202 You may also use the "iomode" parameter to pass in an IO mode to
204 use when opening the file, usually IO layers (though anything
205 accepted by the MODE argument of "open()" is accepted here). Just
206 make sure it's a reading mode.
207 my @lines = $file->slurp(iomode => ':crlf');
209 my $lines = $file->slurp(iomode => '<:encoding(UTF-8)');
210 The default "iomode" is "r".
212 Lines can also be automatically split, mimicking the perl command-
214 line option "-a" by using the "split" parameter. If this parameter
215 is used, each line will be returned as an array ref.
216 my @lines = $file->slurp( chomp => 1, split => qr/\s*,\s*/ );
218 The "split" parameter can only be used in a list context.
220 $file->spew( $content );
222 The opposite of "slurp", this takes a list of strings and prints
223 them to the file in write mode. If the file can't be written to,
224 this method will throw an exception.
225 The content to be written can be either an array ref or a plain
227 scalar. If the content is an array ref then each entry in the
228 array will be written to the file.
229 You may use the "iomode" parameter to pass in an IO mode to use
231 when opening the file, just like "slurp" supports.
232 $file->spew(iomode => '>:raw', $content);
234 The default "iomode" is "w".
236 $file->spew_lines( $content );
238 Just like "spew", but, if $content is a plain scalar, appends $/ to
239 it, or, if $content is an array ref, appends $/ to each element of
240 the array.
241 Can also take an "iomode" parameter like "spew". Again, the default
243 "iomode" is "w".
244 $file->traverse(sub { ... }, @args)
246 Calls the given callback on $file. This doesn't do much on its own,
247 but see the associated documentation in Path::Class::Dir.
248 $file->remove()
250 This method will remove the file in a way that works well on all
251 platforms, and returns a boolean value indicating whether or not
252 the file was successfully removed.
253 "remove()" is better than simply calling Perl's "unlink()"
255 function, because on some platforms (notably VMS) you actually may
256 need to call "unlink()" several times before all versions of the
257 file are gone - the "remove()" method handles this process for you.
258 $st = $file->stat()
260 Invokes "File::stat::stat()" on this file and returns a File::stat
261 object representing the result.
262 $st = $file->lstat()
264 Same as "stat()", but if $file is a symbolic link, "lstat()" stats
265 the link instead of the file the link points to.
266 $class = $file->dir_class()
268 Returns the class which should be used to create directory objects.
269 Generally overridden whenever this class is subclassed.
271 $copy = $file->copy_to( $dest );
273 Copies the $file to $dest. It returns a Path::Class::File object
274 when successful, "undef" otherwise.
275 $moved = $file->move_to( $dest );
277 Moves the $file to $dest, and updates $file accordingly.
278 It returns $file is successful, "undef" otherwise.
280
282 Ken Williams, kwilliams@cpan.org
283
285 Path::Class, Path::Class::Dir, File::Spec
286perl v5.32.1 2021-01-27 Path::Class::File(3)