1Path::Class::File(3) User Contributed Perl Documentation Path::Class::File(3)
2
6 Path::Class::File - Objects representing files
7
9 version 0.23
10
12 use Path::Class qw(file); # Export a short constructor
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 $dir = file( 'foo', 'bar', 'baz.txt' );
47 or platform-native syntax:
49 my $dir = dir( 'foo/bar/baz.txt' );
51 or a mixture of the two:
53 my $dir = dir( '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 $dir = dir( '/var/tmp/foo.txt' );
61 or use an empty string as the first argument:
63 my $dir = dir( '', '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->is_dir
90 Returns a boolean value indicating whether this object represents a
91 directory. Not surprisingly, "Path::Class::File" objects always
92 return false, and "Path::Class::Dir" objects always return true.
93 $file->is_absolute
95 Returns true or false depending on whether the file refers to an
96 absolute path specifier (like "/usr/local/foo.txt" or
97 "\Windows\Foo.txt").
98 $file->is_relative
100 Returns true or false depending on whether the file refers to a
101 relative path specifier (like "lib/foo.txt" or ".\Foo.txt").
102 $file->cleanup
104 Performs a logical cleanup of the file path. For instance:
105 my $file = file('/foo//baz/./foo.txt')->cleanup;
107 # $file now represents '/foo/baz/foo.txt';
108 $dir->resolve
110 Performs a physical cleanup of the file path. For instance:
111 my $dir = dir('/foo/baz/../foo.txt')->resolve;
113 # $dir now represents '/foo/foo.txt', assuming no symlinks
114 This actually consults the filesystem to verify the validity of the
116 path.
117 $dir = $file->dir
119 Returns a "Path::Class::Dir" object representing the directory
120 containing this file.
121 $dir = $file->parent
123 A synonym for the "dir()" method.
124 $abs = $file->absolute
126 Returns a "Path::Class::File" object representing $file as an
127 absolute path. An optional argument, given as either a string or a
128 "Path::Class::Dir" object, specifies the directory to use as the
129 base of relativity - otherwise the current working directory will
130 be used.
131 $rel = $file->relative
133 Returns a "Path::Class::File" object representing $file as a
134 relative path. An optional argument, given as either a string or a
135 "Path::Class::Dir" object, specifies the directory to use as the
136 base of relativity - otherwise the current working directory will
137 be used.
138 $foreign = $file->as_foreign($type)
140 Returns a "Path::Class::File" object representing $file as it would
141 be specified on a system of type $type. Known types include
142 "Unix", "Win32", "Mac", "VMS", and "OS2", i.e. anything for which
143 there is a subclass of "File::Spec".
144 Any generated objects (subdirectories, files, parents, etc.) will
146 also retain this type.
147 $foreign = Path::Class::File->new_foreign($type, @args)
149 Returns a "Path::Class::File" object representing a file as it
150 would 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 The arguments in @args are the same as they would be specified in
155 "new()".
156 $fh = $file->open($mode, $permissions)
158 Passes the given arguments, including $file, to "IO::File->new"
159 (which in turn calls "IO::File->open" and returns the result as an
160 "IO::File" object. If the opening fails, "undef" is returned and
161 $! is set.
162 $fh = $file->openr()
164 A shortcut for
165 $fh = $file->open('r') or croak "Can't read $file: $!";
167 $fh = $file->openw()
169 A shortcut for
170 $fh = $file->open('w') or croak "Can't write $file: $!";
172 $file->touch
174 Sets the modification and access time of the given file to right
175 now, if the file exists. If it doesn't exist, "touch()" will make
176 it exist, and - YES! - set its modification and access time to now.
177 $file->slurp()
179 In a scalar context, returns the contents of $file in a string. In
180 a list context, returns the lines of $file (according to how $/ is
181 set) as a list. If the file can't be read, this method will throw
182 an exception.
183 If you want "chomp()" run on each line of the file, pass a true
185 value for the "chomp" or "chomped" parameters:
186 my @lines = $file->slurp(chomp => 1);
188 You may also use the "iomode" parameter to pass in an IO mode to
190 use when opening the file, usually IO layers (though anything
191 accepted by the MODE argument of "open()" is accepted here). Just
192 make sure it's a reading mode.
193 my @lines = $file->slurp(iomode => ':crlf');
195 my $lines = $file->slurp(iomode => '<:encoding(UTFaXX8)');
196 The default "iomode" is "r".
198 $file->remove()
200 This method will remove the file in a way that works well on all
201 platforms, and returns a boolean value indicating whether or not
202 the file was successfully removed.
203 "remove()" is better than simply calling Perl's "unlink()"
205 function, because on some platforms (notably VMS) you actually may
206 need to call "unlink()" several times before all versions of the
207 file are gone - the "remove()" method handles this process for you.
208 $st = $file->stat()
210 Invokes "File::stat::stat()" on this file and returns a
211 "File::stat" object representing the result.
212 $st = $file->lstat()
214 Same as "stat()", but if $file is a symbolic link, "lstat()" stats
215 the link instead of the file the link points to.
216 $class = $file->dir_class()
218 Returns the class which should be used to create directory objects.
219 Generally overridden whenever this class is subclassed.
221
223 Ken Williams, kwilliams@cpan.org
224
226 Path::Class, Path::Class::Dir, File::Spec
227perl v5.12.3 2011-04-22 Path::Class::File(3)