Path::Class(3pm)

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

NAME

6       Path::Class - Cross-platform path specification manipulation
7

SYNOPSIS

9         use Path::Class;
10
11         my $dir  = dir('foo', 'bar');       # Path::Class::Dir object
12         my $file = file('bob', 'file.txt'); # Path::Class::File object
13
14         # Stringifies to 'foo/bar' on Unix, 'foo\bar' on Windows, etc.
15         print "dir: $dir\n";
16
17         # Stringifies to 'bob/file.txt' on Unix, 'bob\file.txt' on Windows
18         print "file: $file\n";
19
20         my $subdir  = $dir->subdir('baz');  # foo/bar/baz
21         my $parent  = $subdir->parent;      # foo/bar
22         my $parent2 = $parent->parent;      # foo
23
24         my $dir2 = $file->dir;              # bob
25
26         # Work with foreign paths
27         use Path::Class qw(foreign_file foreign_dir);
28         my $file = foreign_file('Mac', ':foo:file.txt');
29         print $file->dir;                   # :foo:
30         print $file->as_foreign('Win32');   # foo\file.txt
31
32         # Interact with the underlying filesystem:
33
34         # $dir_handle is an IO::Dir object
35         my $dir_handle = $dir->open or die "Can't read $dir: $!";
36
37         # $file_handle is an IO::File object
38         my $file_handle = $file->open($mode) or die "Can't read $file: $!";
39

DESCRIPTION

41       "Path::Class" is a module for manipulation of file and directory speci‐
42       fications (strings describing their locations, like '/home/ken/foo.txt'
43       or 'C:\Windows\Foo.txt') in a cross-platform manner.  It supports
44       pretty much every platform Perl runs on, including Unix, Windows, Mac,
45       VMS, Epoc, Cygwin, OS/2, and NetWare.
46
47       The well-known module "File::Spec" also provides this service, but it's
48       sort of awkward to use well, so people sometimes avoid it, or use it in
49       a way that won't actually work properly on platforms significantly dif‐
50       ferent than the ones they've tested their code on.
51
52       In fact, "Path::Class" uses "File::Spec" internally, wrapping all the
53       unsightly details so you can concentrate on your application code.
54       Whereas "File::Spec" provides functions for some common path manipula‐
55       tions, "Path::Class" provides an object-oriented model of the world of
56       path specifications and their underlying semantics.  "File::Spec"
57       doesn't create any objects, and its classes represent the different
58       ways in which paths must be manipulated on various platforms (not a
59       very intuitive concept).  "Path::Class" creates objects representing
60       files and directories, and provides methods that relate them to each
61       other.  For instance, the following "File::Spec" code:
62
63        my $absolute = File::Spec->file_name_is_absolute(
64                         File::Spec->catfile( @dirs, $file )
65                       );
66
67       can be written using "Path::Class" as
68
69        my $absolute = Path::Class::File->new( @dirs, $file )->is_absolute;
70
71       or even as
72
73        my $absolute = file( @dirs, $file )->is_absolute;
74
75       Similar readability improvements should happen all over the place when
76       using "Path::Class".
77
78       Using "Path::Class" can help solve real problems in your code too - for
79       instance, how many people actually take the "volume" (like "C:" on Win‐
80       dows) into account when writing "File::Spec"-using code?  I thought
81       not.  But if you use "Path::Class", your file and directory objects
82       will know what volumes they refer to and do the right thing.
83
84       The guts of the "Path::Class" code live in the "Path::Class::File" and
85       "Path::Class::Dir" modules, so please see those modules' documentation
86       for more details about how to use them.
87
88       EXPORT
89
90       The following functions are exported by default.
91
92       file
93           A synonym for "Path::Class::File->new".
94
95       dir A synonym for "Path::Class::Dir->new".
96
97       If you would like to prevent their export, you may explicitly pass an
98       empty list to perl's "use", i.e. "use Path::Class ()".
99
100       The following are exported only on demand.
101
102       foreign_file
103           A synonym for "Path::Class::File->new_foreign".
104
105       foreign_dir
106           A synonym for "Path::Class::Dir->new_foreign".
107

Notes on Cross-Platform Compatibility

109       Although it is much easier to write cross-platform-friendly code with
110       this module than with "File::Spec", there are still some issues to be
111       aware of.
112
113       ·   Some platforms, notably VMS and some older versions of DOS (I
114           think), all filenames must have an extension.  Thus if you create a
115           file called foo/bar and then ask for a list of files in the direc‐
116           tory foo, you may find a file called bar. instead of the bar you
117           were expecting.  Thus it might be a good idea to use an extension
118           in the first place.
119

AUTHOR

121       Ken Williams, KWILLIAMS@cpan.org
122

COPYRIGHT

124       Copyright (c) Ken Williams.  All rights reserved.
125
126       This library is free software; you can redistribute it and/or modify it
127       under the same terms as Perl itself.
128

NAME

SYNOPSIS

DESCRIPTION

Notes on Cross-Platform Compatibility

AUTHOR

COPYRIGHT

SEE ALSO