=begin pod :kind("Type") :subkind("class") :category("domain-specific")

=TITLE class IO::Path::Parts

=SUBTITLE IO::Path parts encapsulation

=begin code :skip-test<XXX need to define 'of' method in test's anon class>
class IO::Path::Parts does Positional does Associative does Iterable { }
=end code

An C<IO::Path::Parts> object is a container for the parts of an
L«C<IO::Path>|/type/IO::Path» object. It is usually created with
a call to the method L«C<.parts>|/type/IO::Path#method_parts» on a
C<IO::Path> object. It can also be created with a call to the method
L«C<.split>|/routine/split» on a object of one of the low-level path
operations sub-classes of L«C<IO::Spec>|/type/IO::Spec».

The parts of an C<IO::Path> are:

=item the volume, see L«C<.volume>|/type/IO::Path#method_volume»
=item the directory name, see L«C<.dirname>|/type/IO::Path#method_dirname»
=item the basename, see L«C<.basename>|/type/IO::Path#method_basename»

=head1 Methods

=head2 method new

    method new(\volume, \dirname, \basename)

Create a new C<IO::Path::Parts> object with C<\volume>, C<\dirname>
and C<\basename> as respectively the volume, directory name and basename
parts.

=head2 attribute volume

Read-only. Returns the volume of the C<IO::Path::Parts> object.

=begin code
IO::Path::Parts.new('C:', '/some/dir', 'foo.txt').dirname.say;
# OUTPUT: «C:␤»
=end code

=head2 attribute dirname

Read-only. Returns the directory name part of the C<IO::Path::Parts>
object.

=begin code
IO::Path::Parts.new('C:', '/some/dir', 'foo.txt').dirname.say;
# OUTPUT: «/some/dir␤»
=end code

=head2 attribute basename

Read-only. Returns the basename part of the C<IO::Path::Parts> object.

=begin code
IO::Path::Parts.new('C:', '/some/dir', 'foo.txt').basename.say;
# OUTPUT: «foo.txt␤»
=end code

=head1 Previous implementations

Before Rakudo 2020.06 the C<.parts> method of C<IO::Path> returned
a L«C<Map>|/type/Map» and the C<.split> routine of the C<IO::Spec>
sub-classes returned a L«C<List>|/type/List» of L«C<Pair>|/type/Pair».
The C<IO::Path::Part> class maintains compatibility with these
previous implementations by doing L«C<Positional>|/type/Positional»,
L«C<Associative>|/type/Associative» and L«C<Iterable>|/type/Iterable».

=begin code
my $parts = IO::Path::Parts.new('C:', '/some/dir', 'foo.txt');
say $parts<volume>;      # OUTPUT: «C:␤»
say $parts[0];           # OUTPUT: «volume => C:␤»
say $parts[0].^name;     # OUTPUT: «Pair␤»
.say for $parts[];
# OUTPUT: «volume => C:␤dirname => /some/dir␤basename => foo.txt␤»
=end code

=end pod

# vim: expandtab shiftwidth=4 ft=perl6
