1Path::Class(3) User Contributed Perl Documentation Path::Class(3)
2
3
4
6 Path::Class - Cross-platform path specification manipulation
7
9 version 0.37
10
12 use Path::Class;
13
14 my $dir = dir('foo', 'bar'); # Path::Class::Dir object
15 my $file = file('bob', 'file.txt'); # Path::Class::File object
16
17 # Stringifies to 'foo/bar' on Unix, 'foo\bar' on Windows, etc.
18 print "dir: $dir\n";
19
20 # Stringifies to 'bob/file.txt' on Unix, 'bob\file.txt' on Windows
21 print "file: $file\n";
22
23 my $subdir = $dir->subdir('baz'); # foo/bar/baz
24 my $parent = $subdir->parent; # foo/bar
25 my $parent2 = $parent->parent; # foo
26
27 my $dir2 = $file->dir; # bob
28
29 # Work with foreign paths
30 use Path::Class qw(foreign_file foreign_dir);
31 my $file = foreign_file('Mac', ':foo:file.txt');
32 print $file->dir; # :foo:
33 print $file->as_foreign('Win32'); # foo\file.txt
34
35 # Interact with the underlying filesystem:
36
37 # $dir_handle is an IO::Dir object
38 my $dir_handle = $dir->open or die "Can't read $dir: $!";
39
40 # $file_handle is an IO::File object
41 my $file_handle = $file->open($mode) or die "Can't read $file: $!";
42
44 "Path::Class" is a module for manipulation of file and directory
45 specifications (strings describing their locations, like
46 '/home/ken/foo.txt' or 'C:\Windows\Foo.txt') in a cross-platform
47 manner. It supports pretty much every platform Perl runs on, including
48 Unix, Windows, Mac, VMS, Epoc, Cygwin, OS/2, and NetWare.
49
50 The well-known module File::Spec also provides this service, but it's
51 sort of awkward to use well, so people sometimes avoid it, or use it in
52 a way that won't actually work properly on platforms significantly
53 different than the ones they've tested their code on.
54
55 In fact, "Path::Class" uses "File::Spec" internally, wrapping all the
56 unsightly details so you can concentrate on your application code.
57 Whereas "File::Spec" provides functions for some common path
58 manipulations, "Path::Class" provides an object-oriented model of the
59 world of path specifications and their underlying semantics.
60 "File::Spec" doesn't create any objects, and its classes represent the
61 different ways in which paths must be manipulated on various platforms
62 (not a very intuitive concept). "Path::Class" creates objects
63 representing files and directories, and provides methods that relate
64 them to each other. For instance, the following "File::Spec" code:
65
66 my $absolute = File::Spec->file_name_is_absolute(
67 File::Spec->catfile( @dirs, $file )
68 );
69
70 can be written using "Path::Class" as
71
72 my $absolute = Path::Class::File->new( @dirs, $file )->is_absolute;
73
74 or even as
75
76 my $absolute = file( @dirs, $file )->is_absolute;
77
78 Similar readability improvements should happen all over the place when
79 using "Path::Class".
80
81 Using "Path::Class" can help solve real problems in your code too - for
82 instance, how many people actually take the "volume" (like "C:" on
83 Windows) into account when writing "File::Spec"-using code? I thought
84 not. But if you use "Path::Class", your file and directory objects
85 will know what volumes they refer to and do the right thing.
86
87 The guts of the "Path::Class" code live in the Path::Class::File and
88 Path::Class::Dir modules, so please see those modules' documentation
89 for more details about how to use them.
90
91 EXPORT
92 The following functions are exported by default.
93
94 file
95 A synonym for "Path::Class::File->new".
96
97 dir A synonym for "Path::Class::Dir->new".
98
99 If you would like to prevent their export, you may explicitly pass an
100 empty list to perl's "use", i.e. "use Path::Class ()".
101
102 The following are exported only on demand.
103
104 foreign_file
105 A synonym for "Path::Class::File->new_foreign".
106
107 foreign_dir
108 A synonym for "Path::Class::Dir->new_foreign".
109
110 tempdir
111 Create a new Path::Class::Dir instance pointed to temporary
112 directory.
113
114 my $temp = Path::Class::tempdir(CLEANUP => 1);
115
116 A synonym for "Path::Class::Dir->new(File::Temp::tempdir(@_))".
117
119 Although it is much easier to write cross-platform-friendly code with
120 this module than with "File::Spec", there are still some issues to be
121 aware of.
122
123 • On some platforms, notably VMS and some older versions of DOS (I
124 think), all filenames must have an extension. Thus if you create a
125 file called foo/bar and then ask for a list of files in the
126 directory foo, you may find a file called bar. instead of the bar
127 you were expecting. Thus it might be a good idea to use an
128 extension in the first place.
129
131 Ken Williams, KWILLIAMS@cpan.org
132
134 Copyright (c) Ken Williams. All rights reserved.
135
136 This library is free software; you can redistribute it and/or modify it
137 under the same terms as Perl itself.
138
140 Path::Class::Dir, Path::Class::File, File::Spec
141
142
143
144perl v5.36.0 2023-01-20 Path::Class(3)