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

VERSION

9       version 0.37
10

SYNOPSIS

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

DESCRIPTION

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

Notes on Cross-Platform Compatibility

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

AUTHOR

131       Ken Williams, KWILLIAMS@cpan.org
132

COPYRIGHT

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