=begin pod

=TITLE class IO

   class IO::Path is Cool does IO::FileTestable { }

=head1 Methods

=head2 dir

    sub dir Cool $path = '.', Mu :$test = none('.', '..')

Returns a list of L<IO::File> and L<IO::Dir> objects for the
files and directories found in the $path. If $path is not given
assumes the current directory.

A second optional parameter can be given that will be
matched against the strings to filter out certain entries.
By default it filters out the '.' and '..' entries.

Examples:

    for dir() -> $file {
       say $file;
    }

    dir('path/to/directory');

To include all the entries (including . and ..) write:

    dir(test => all())

To include only entries with a .pl extension write:

    dir(test => /.pl$/)

=head2 prompt

Prints out a string to the standard output and waits
for the user to type in something and finish with an ENTER.
Returns the string typed in without the trailing newline.

    my $name = prompt("Hi, what's your name?");

=head2 File Test operators

    -e
    -f Do not exist in Perl 6. See :e, :f.

    -M Does not exist in Perl 6. See C<modified>.
    -A Does not exist in Perl 6. See C<accessed>.
    -C Does not exist in Perl 6. See C<changed>.

    :e Exists
    :d Directory
    :f File
    :l Symbolic link
    :r Readable
    :w Writable
    :x Executable
    :s Size
    :z Zero size

Usage:

If you have a string - a path to something in the filesystem:

    if "path/to/file".IO ~~ :e {
        say 'file exists';
	}

    my $file = "path/to/file";
    if $file.IO ~~ :e {
        say 'file exists';
    }

If you already have an IO object in $file, either by creating one yourself,
or by getting it from another subroutine, such as C<dir>,
you can write this:

    my $file = "path/to/file".IO;
    if $file ~~ :e {
        say 'file exists';
    }

There are also 3 methods for fetching the 3 timestamps of a file (inode),
on Operating Systems where these are available:

=head2 modified

Timestamp when the file was last modified.

    "path/to/file".IO.modified()

=head2 accessed

Timestamp when the file was last accessed.

    "path/to/file".IO.accessed()

=head2 changed

Timestamp when the inode was last changed.

    "path/to/file".IO.changed()

=end pod