=begin pod

=TITLE class IO::Spec::Unix

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

    class IO::Spec::Unix is IO::Spec  { }

On object of this type is available via the variable C<$*SPEC> if the perl is
running on a Unix-like platform.

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 abs2rel

    method abs2rel(IO::Path:D $path, IO::Path:D $base = $*CWD --> Str:D)

Returns a string that represents C<$path>, but relative to C<$base> path.
Both C<$path> and C<$base> may be relative paths C<$bar> defaults to C<$*CWD>

=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:

    IO::Spec::Unix.basename("foo/bar/") .perl.say; # OUTPUT: «""␤»
    IO::Spec::Unix.basename("foo/bar/.").perl.say; # OUTPUT: «"."␤»
    IO::Spec::Unix.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, so no symlinks are followed.

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

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

    IO::Spec::Unix.canonpath("foo///./../bar/../ber", :parent).say;
    # OUTPUT: «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::Unix.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 $part1, Str:D $part2 --> Str:D)

Takes two path fragments and concatenates them, adding or removing a path
separator, if necessary. The first argument is ignored (it exists to maintain
consistent interface with other C<IO::Spec> types for systems that have
volumes).

    IO::Spec::Unix.catpath($, 'some/dir', 'and/more').say;
    # OUTPUT: «some/dir/and/more␤»

=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
