.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Path::Class 3pm"
.TH Path::Class 3pm 2023-07-26 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Path::Class \- Cross\-platform path specification manipulation
.SH VERSION
.IX Header "VERSION"
version 0.37
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Path::Class;
\&  
\&  my $dir  = dir(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq);       # Path::Class::Dir object
\&  my $file = file(\*(Aqbob\*(Aq, \*(Aqfile.txt\*(Aq); # Path::Class::File object
\&  
\&  # Stringifies to \*(Aqfoo/bar\*(Aq on Unix, \*(Aqfoo\ebar\*(Aq on Windows, etc.
\&  print "dir: $dir\en";
\&  
\&  # Stringifies to \*(Aqbob/file.txt\*(Aq on Unix, \*(Aqbob\efile.txt\*(Aq on Windows
\&  print "file: $file\en";
\&  
\&  my $subdir  = $dir\->subdir(\*(Aqbaz\*(Aq);  # foo/bar/baz
\&  my $parent  = $subdir\->parent;      # foo/bar
\&  my $parent2 = $parent\->parent;      # foo
\&  
\&  my $dir2 = $file\->dir;              # bob
\&
\&  # Work with foreign paths
\&  use Path::Class qw(foreign_file foreign_dir);
\&  my $file = foreign_file(\*(AqMac\*(Aq, \*(Aq:foo:file.txt\*(Aq);
\&  print $file\->dir;                   # :foo:
\&  print $file\->as_foreign(\*(AqWin32\*(Aq);   # foo\efile.txt
\&  
\&  # Interact with the underlying filesystem:
\&  
\&  # $dir_handle is an IO::Dir object
\&  my $dir_handle = $dir\->open or die "Can\*(Aqt read $dir: $!";
\&  
\&  # $file_handle is an IO::File object
\&  my $file_handle = $file\->open($mode) or die "Can\*(Aqt read $file: $!";
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Path::Class\*(C'\fR is a module for manipulation of file and directory
specifications (strings describing their locations, like
\&\f(CW\*(Aq/home/ken/foo.txt\*(Aq\fR or \f(CW\*(AqC:\eWindows\eFoo.txt\*(Aq\fR) in a cross-platform
manner.  It supports pretty much every platform Perl runs on,
including Unix, Windows, Mac, VMS, Epoc, Cygwin, OS/2, and NetWare.
.PP
The well-known module File::Spec also provides this service, but
it's sort of awkward to use well, so people sometimes avoid it, or use
it in a way that won't actually work properly on platforms
significantly different than the ones they've tested their code on.
.PP
In fact, \f(CW\*(C`Path::Class\*(C'\fR uses \f(CW\*(C`File::Spec\*(C'\fR internally, wrapping all
the unsightly details so you can concentrate on your application code.
Whereas \f(CW\*(C`File::Spec\*(C'\fR provides functions for some common path
manipulations, \f(CW\*(C`Path::Class\*(C'\fR provides an object-oriented model of the
world of path specifications and their underlying semantics.
\&\f(CW\*(C`File::Spec\*(C'\fR doesn't create any objects, and its classes represent
the different ways in which paths must be manipulated on various
platforms (not a very intuitive concept).  \f(CW\*(C`Path::Class\*(C'\fR creates
objects representing files and directories, and provides methods that
relate them to each other.  For instance, the following \f(CW\*(C`File::Spec\*(C'\fR
code:
.PP
.Vb 3
\& my $absolute = File::Spec\->file_name_is_absolute(
\&                  File::Spec\->catfile( @dirs, $file )
\&                );
.Ve
.PP
can be written using \f(CW\*(C`Path::Class\*(C'\fR as
.PP
.Vb 1
\& my $absolute = Path::Class::File\->new( @dirs, $file )\->is_absolute;
.Ve
.PP
or even as
.PP
.Vb 1
\& my $absolute = file( @dirs, $file )\->is_absolute;
.Ve
.PP
Similar readability improvements should happen all over the place when
using \f(CW\*(C`Path::Class\*(C'\fR.
.PP
Using \f(CW\*(C`Path::Class\*(C'\fR can help solve real problems in your code too \-
for instance, how many people actually take the "volume" (like \f(CW\*(C`C:\*(C'\fR
on Windows) into account when writing \f(CW\*(C`File::Spec\*(C'\fR\-using code?  I
thought not.  But if you use \f(CW\*(C`Path::Class\*(C'\fR, your file and directory objects
will know what volumes they refer to and do the right thing.
.PP
The guts of the \f(CW\*(C`Path::Class\*(C'\fR code live in the Path::Class::File
and Path::Class::Dir modules, so please see those
modules' documentation for more details about how to use them.
.SS EXPORT
.IX Subsection "EXPORT"
The following functions are exported by default.
.IP file 4
.IX Item "file"
A synonym for \f(CW\*(C`Path::Class::File\->new\*(C'\fR.
.IP dir 4
.IX Item "dir"
A synonym for \f(CW\*(C`Path::Class::Dir\->new\*(C'\fR.
.PP
If you would like to prevent their export, you may explicitly pass an
empty list to perl's \f(CW\*(C`use\*(C'\fR, i.e. \f(CW\*(C`use Path::Class ()\*(C'\fR.
.PP
The following are exported only on demand.
.IP foreign_file 4
.IX Item "foreign_file"
A synonym for \f(CW\*(C`Path::Class::File\->new_foreign\*(C'\fR.
.IP foreign_dir 4
.IX Item "foreign_dir"
A synonym for \f(CW\*(C`Path::Class::Dir\->new_foreign\*(C'\fR.
.IP tempdir 4
.IX Item "tempdir"
Create a new Path::Class::Dir instance pointed to temporary directory.
.Sp
.Vb 1
\&  my $temp = Path::Class::tempdir(CLEANUP => 1);
.Ve
.Sp
A synonym for \f(CW\*(C`Path::Class::Dir\->new(File::Temp::tempdir(@_))\*(C'\fR.
.SH "Notes on Cross-Platform Compatibility"
.IX Header "Notes on Cross-Platform Compatibility"
Although it is much easier to write cross-platform-friendly code with
this module than with \f(CW\*(C`File::Spec\*(C'\fR, there are still some issues to be
aware of.
.IP \(bu 4
On some platforms, notably VMS and some older versions of DOS (I think),
all filenames must have an extension.  Thus if you create a file
called \fIfoo/bar\fR and then ask for a list of files in the directory
\&\fIfoo\fR, you may find a file called \fIbar.\fR instead of the \fIbar\fR you
were expecting.  Thus it might be a good idea to use an extension in
the first place.
.SH AUTHOR
.IX Header "AUTHOR"
Ken Williams, KWILLIAMS@cpan.org
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) Ken Williams.  All rights reserved.
.PP
This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Path::Class::Dir, Path::Class::File, File::Spec