=begin pod

=TITLE class IO::Spec::Win32

=SUBTITLE Platform specific operations on file and directory paths for Windows

    class IO::Spec::Win32 is IO::Spec { }

Objects of this class are not used directly but as a sub-class specific to
the platform perl is running on via the C<$*SPEC> variable which will contain
an object of the appropriate type

B<NOTE:> the C<IO::Spec::*> classes provide low-level path operations. Unless
you're creating your own high-level path manipulation routines, you don't
need to use C<IO::Spec::*>. Use L«C<IO::Path>|/type/IO::Path» instead..

B<NOTE2:> no special validation is done by these classes (e.g. check whether
path contains a NUL byte). It is the job of higher-level classes, like
L«C<IO::Path>|/type/IO::Path», to do that.

=head1 Methods

=head2 method basename

    method basename(Str:D $path --> Str:D)

Takes a path as a string and returns a possibly-empty portion after the last
slash or backslash:

    IO::Spec::Win32.basename("foo/bar/") .perl.say; # OUTPUT: «""␤»
    IO::Spec::Win32.basename("foo/bar\\").perl.say; # OUTPUT: «""␤»
    IO::Spec::Win32.basename("foo/bar/.").perl.say; # OUTPUT: «"."␤»
    IO::Spec::Win32.basename("foo/bar")  .perl.say; # OUTPUT: «"bar"␤»

=head2 method canonpath

    method canonpath(Str() $path, :$parent --> Str:D)

Returns a string that is a canonical representation of C<$path>. If C<:$parent>
is set to true, will also clean up references to parent directories. B<NOTE:>
the routine does not access the filesystem.

    IO::Spec::Win32.canonpath("C:/foo//../bar/../ber").say;
    # OUTPUT: «C:\foo\..\bar\..\ber␤»

    IO::Spec::Win32.canonpath("C:/foo///./../bar/../ber").say;
    # OUTPUT: «C:\foo\..\bar\..\ber␤»

    IO::Spec::Win32.canonpath("C:/foo///./../bar/../ber", :parent).say;
    # OUTPUT: «C:\ber␤»

=head2 method catdir

    method catdir (*@parts --> Str:D)

Concatenates multiple path fragments and returns the canonical representation
of the resultant path as a string. The C<@parts> are L«C<Str>|/type/Str» objects
and are allowed to contain path separators.

    IO::Spec::Win32.catdir(<foo/bar ber perl>).say;
    # OUTPUT: «foo\bar\ber\perl␤»

=head2 method catfile

Alias for L«C<catdir>|/routine/catdir».

=head2 method catpath

    method catpath (Str:D $volume, Str:D $dirs, Str:D $file --> Str:D)

Concatenates a path from given volume, a chain of directories, and file.
An empty string can be given for any of the three arguments. No attempt to
make the path cannonical is made. Use L«C<canonpath>|/routine/canonpath» for
that purpose.

    IO::Spec::Win32.catpath('C:', '/some/dir', 'foo.txt').say;
    # OUTPUT: «C:/some/dir\and/more␤»

    IO::Spec::Win32.catpath('C:', '/some/dir', '').say;
    # OUTPUT: «C:/some/dir␤»

    IO::Spec::Win32.catpath('', '/some/dir', 'foo.txt').say;
    # OUTPUT: «/some/dir\foo.txt␤»

    IO::Spec::Win32.catpath('E:', '', 'foo.txt').say;
    # OUTPUT: «E:foo.txt␤»

=head2 method tmpdir

Defined as:

        method tmpdir(--> IO::Path:D)

Attempts to locate a system's temporary directory by checking several typical directories and environmental variables. Uses currect directory if no suitable directories are found.

=end pod

# vim: expandtab shiftwidth=4 ft=perl6
