1Path::Class::File(3)  User Contributed Perl Documentation Path::Class::File(3)
2
3
4

NAME

6       Path::Class::File - Objects representing files
7

VERSION

9       version 0.37
10

SYNOPSIS

12         use Path::Class;  # Exports file() by default
13
14         my $file = file('foo', 'bar.txt');  # Path::Class::File object
15         my $file = Path::Class::File->new('foo', 'bar.txt'); # Same thing
16
17         # Stringifies to 'foo/bar.txt' on Unix, 'foo\bar.txt' on Windows, etc.
18         print "file: $file\n";
19
20         if ($file->is_absolute) { ... }
21         if ($file->is_relative) { ... }
22
23         my $v = $file->volume; # Could be 'C:' on Windows, empty string
24                                # on Unix, 'Macintosh HD:' on Mac OS
25
26         $file->cleanup; # Perform logical cleanup of pathname
27         $file->resolve; # Perform physical cleanup of pathname
28
29         my $dir = $file->dir;  # A Path::Class::Dir object
30
31         my $abs = $file->absolute; # Transform to absolute path
32         my $rel = $file->relative; # Transform to relative path
33

DESCRIPTION

35       The "Path::Class::File" class contains functionality for manipulating
36       file names in a cross-platform way.
37

METHODS

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
46             my $file = file( 'foo', 'bar', 'baz.txt' );
47
48           or platform-native syntax:
49
50             my $file = file( 'foo/bar/baz.txt' );
51
52           or a mixture of the two:
53
54             my $file = file( 'foo/bar', 'baz.txt' );
55
56           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
60             my $file = file( '/var/tmp/foo.txt' );
61
62           or use an empty string as the first argument:
63
64             my $file = file( '', 'var', 'tmp', 'foo.txt' );
65
66           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
73       $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
77             $string = $file->stringify;
78             $string = "$file";
79
80       $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
85       $file->basename
86           Returns the name of the file as a string, without the directory
87           portion (if any).
88
89       $file->components
90           Returns a list of the directory components of this file, followed
91           by the basename.
92
93           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
98       $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
103       $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
108       $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
112       $file->cleanup
113           Performs a logical cleanup of the file path.  For instance:
114
115             my $file = file('/foo//baz/./foo.txt')->cleanup;
116             # $file now represents '/foo/baz/foo.txt';
117
118       $dir->resolve
119           Performs a physical cleanup of the file path.  For instance:
120
121             my $file = file('/foo/baz/../foo.txt')->resolve;
122             # $file now represents '/foo/foo.txt', assuming no symlinks
123
124           This actually consults the filesystem to verify the validity of the
125           path.
126
127       $dir = $file->dir
128           Returns a "Path::Class::Dir" object representing the directory
129           containing this file.
130
131       $dir = $file->parent
132           A synonym for the "dir()" method.
133
134       $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
141       $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
148       $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
154           Any generated objects (subdirectories, files, parents, etc.) will
155           also retain this type.
156
157       $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
163           The arguments in @args are the same as they would be specified in
164           "new()".
165
166       $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
172       $fh = $file->openr()
173           A shortcut for
174
175            $fh = $file->open('r') or croak "Can't read $file: $!";
176
177       $fh = $file->openw()
178           A shortcut for
179
180            $fh = $file->open('w') or croak "Can't write to $file: $!";
181
182       $fh = $file->opena()
183           A shortcut for
184
185            $fh = $file->open('a') or croak "Can't append to $file: $!";
186
187       $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
192       $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
198           If you want "chomp()" run on each line of the file, pass a true
199           value for the "chomp" or "chomped" parameters:
200
201             my @lines = $file->slurp(chomp => 1);
202
203           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
208             my @lines = $file->slurp(iomode => ':crlf');
209             my $lines = $file->slurp(iomode => '<:encoding(UTF-8)');
210
211           The default "iomode" is "r".
212
213           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
217               my @lines = $file->slurp( chomp => 1, split => qr/\s*,\s*/ );
218
219           The "split" parameter can only be used in a list context.
220
221       $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
226           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
230           You may use the "iomode" parameter to pass in an IO mode to use
231           when opening the file, just like "slurp" supports.
232
233             $file->spew(iomode => '>:raw', $content);
234
235           The default "iomode" is "w".
236
237       $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
242           Can also take an "iomode" parameter like "spew". Again, the default
243           "iomode" is "w".
244
245       $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
249       $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
254           "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
259       $st = $file->stat()
260           Invokes "File::stat::stat()" on this file and returns a File::stat
261           object representing the result.
262
263       $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
267       $class = $file->dir_class()
268           Returns the class which should be used to create directory objects.
269
270           Generally overridden whenever this class is subclassed.
271
272       $copy = $file->copy_to( $dest );
273           Copies the $file to $dest. It returns a Path::Class::File object
274           when successful, "undef" otherwise.
275
276       $moved = $file->move_to( $dest );
277           Moves the $file to $dest, and updates $file accordingly.
278
279           It returns $file is successful, "undef" otherwise.
280

AUTHOR

282       Ken Williams, kwilliams@cpan.org
283

SEE ALSO

285       Path::Class, Path::Class::Dir, File::Spec
286
287
288
289perl v5.32.1                      2021-01-27              Path::Class::File(3)
Impressum