1Path::Class::File(3) User Contributed Perl Documentation Path::Class::File(3)
2
6 Path::Class::File - Objects representing files
7
9 use Path::Class qw(file); # Export a short constructor
10 my $file = file('foo', 'bar.txt'); # Path::Class::File object
12 my $file = Path::Class::File->new('foo', 'bar.txt'); # Same thing
13 # Stringifies to 'foo/bar.txt' on Unix, 'foo\bar.txt' on Windows, etc.
15 print "file: $file\n";
16 if ($file->is_absolute) { ... }
18 my $v = $file->volume; # Could be 'C:' on Windows, empty string
20 # on Unix, 'Macintosh HD:' on Mac OS
21 $file->cleanup; # Perform logical cleanup of pathname
23 my $dir = $file->dir; # A Path::Class::Dir object
25 my $abs = $file->absolute; # Transform to absolute path
27 my $rel = $file->relative; # Transform to relative path
28
30 The "Path::Class::File" class contains functionality for manipulating
31 file names in a cross-platform way.
32
34 $file = Path::Class::File->new( <dir1>, <dir2>, ..., <file> )
35 $file = file( <dir1>, <dir2>, ..., <file> )
36 Creates a new "Path::Class::File" object and returns it. The argu‐
37 ments specify the path to the file. Any volume may also be speci‐
38 fied as the first argument, or as part of the first argument. You
39 can use platform-neutral syntax:
40 my $dir = file( 'foo', 'bar', 'baz.txt' );
42 or platform-native syntax:
44 my $dir = dir( 'foo/bar/baz.txt' );
46 or a mixture of the two:
48 my $dir = dir( 'foo/bar', 'baz.txt' );
50 All three of the above examples create relative paths. To create
52 an absolute path, either use the platform native syntax for doing
53 so:
54 my $dir = dir( '/var/tmp/foo.txt' );
56 or use an empty string as the first argument:
58 my $dir = dir( '', 'var', 'tmp', 'foo.txt' );
60 If the second form seems awkward, that's somewhat intentional -
62 paths like "/var/tmp" or "\Windows" aren't cross-platform concepts
63 in the first place, so they probably shouldn't appear in your code
64 if you're trying to be cross-platform. The first form is perfectly
65 fine, because paths like this may come from config files, user
66 input, or whatever.
67 $file->stringify
69 This method is called internally when a "Path::Class::File" object
70 is used in a string context, so the following are equivalent:
71 $string = $file->stringify;
73 $string = "$file";
74 $file->volume
76 Returns the volume (e.g. "C:" on Windows, "Macintosh HD:" on Mac
77 OS, etc.) of the object, if any. Otherwise, returns the empty
78 string.
79 $file->basename
81 Returns the name of the file as a string, without the directory
82 portion (if any).
83 $file->is_dir
85 Returns a boolean value indicating whether this object represents a
86 directory. Not surprisingly, "Path::Class::File" objects always
87 return false, and "Path::Class::Dir" objects always return true.
88 $file->is_absolute
90 Returns true or false depending on whether the file refers to an
91 absolute path specifier (like "/usr/local/foo.txt" or "\Win‐
92 dows\Foo.txt").
93 $file->cleanup
95 Performs a logical cleanup of the file path. For instance:
96 my $file = file('/foo//baz/./foo.txt')->cleanup;
98 # $file now represents '/foo/baz/foo.txt';
99 $dir = $file->dir
101 Returns a "Path::Class::Dir" object representing the directory con‐
102 taining this file.
103 $dir = $file->parent
105 A synonym for the "dir()" method.
106 $abs = $file->absolute
108 Returns a "Path::Class::File" object representing $file as an abso‐
109 lute path. An optional argument, given as either a string or a
110 "Path::Class::Dir" object, specifies the directory to use as the
111 base of relativity - otherwise the current working directory will
112 be used.
113 $rel = $file->relative
115 Returns a "Path::Class::File" object representing $file as a rela‐
116 tive path. An optional argument, given as either a string or a
117 "Path::Class::Dir" object, specifies the directory to use as the
118 base of relativity - otherwise the current working directory will
119 be used.
120 $foreign = $file->as_foreign($type)
122 Returns a "Path::Class::File" object representing $file as it would
123 be specified on a system of type $type. Known types include
124 "Unix", "Win32", "Mac", "VMS", and "OS2", i.e. anything for which
125 there is a subclass of "File::Spec".
126 Any generated objects (subdirectories, files, parents, etc.) will
128 also retain this type.
129 $foreign = Path::Class::File->new_foreign($type, @args)
131 Returns a "Path::Class::File" object representing a file as it
132 would be specified on a system of type $type. Known types include
133 "Unix", "Win32", "Mac", "VMS", and "OS2", i.e. anything for which
134 there is a subclass of "File::Spec".
135 The arguments in @args are the same as they would be specified in
137 "new()".
138 $fh = $file->open($mode, $permissions)
140 Passes the given arguments, including $file, to "IO::File->new"
141 (which in turn calls "IO::File->open" and returns the result as an
142 "IO::File" object. If the opening fails, "undef" is returned and
143 $! is set.
144 $fh = $file->openr()
146 A shortcut for
147 $fh = $file->open('r') or die "Can't read $file: $!";
149 $fh = $file->openw()
151 A shortcut for
152 $fh = $file->open('w') or die "Can't write $file: $!";
154 $file->touch
156 Sets the modification and access time of the given file to right
157 now, if the file exists. If it doesn't exist, "touch()" will make
158 it exist, and - YES! - set its modification and access time to now.
159 $file->slurp()
161 In a scalar context, returns the contents of $file in a string. In
162 a list context, returns the lines of $file (according to how $/ is
163 set) as a list. If the file can't be read, this method will throw
164 an exception.
165 If you want "chomp()" run on each line of the file, pass a true
167 value for the "chomp" or "chomped" parameters:
168 my @lines = $file->slurp(chomp => 1);
170 $file->remove()
172 This method will remove the file in a way that works well on all
173 platforms, and returns a boolean value indicating whether or not
174 the file was successfully removed.
175 "remove()" is better than simply calling Perl's "unlink()" func‐
177 tion, because on some platforms (notably VMS) you actually may need
178 to call "unlink()" several times before all versions of the file
179 are gone - the "remove()" method handles this process for you.
180 $st = $file->stat()
182 Invokes "File::stat::stat()" on this file and returns a
183 "File::stat" object representing the result.
184 $st = $file->lstat()
186 Same as "stat()", but if $file is a symbolic link, "lstat()" stats
187 the link instead of the file the link points to.
188
190 Ken Williams, ken@mathforum.org
191
193 Path::Class, Path::Class::Dir, File::Spec
194perl v5.8.8 2007-02-12 Path::Class::File(3)