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

=TITLE class IO::Special

=SUBTITLE Path to special I/O device

=for code
class IO::Special does IO { }

Used as a L«C<$.path>|/type/IO::Handle#method_path>» attribute in filehandles
for special standard input C<$*IN> and output C<$*OUT> and C<$*ERR>. Provides
a bridged interface of L«C<IO::Handle>|/type/IO::Handle», mostly file tests
and stringification.

=head1 Methods

=head2 method new

=for code :skip-test<compile time error>
method new(:$!what!)

Takes a single required attribute L<what|/routine/what>. It is unlikely that you will ever
need to construct one of these objects yourself.

=head2 method what

    say $*IN.path.what;  # OUTPUT: «<STDIN>␤»
    say $*OUT.path.what; # OUTPUT: «<STDOUT>␤»
    say $*ERR.path.what; # OUTPUT: «<STDERR>␤»

Returns one of the strings C«'<STDIN>'», C«'<STDOUT>'», or C«'<STDERR>'»,
specifying the type of the special IO device.

=head2 method WHICH

    method WHICH(IO::Special:D: --> Str)

This returns a string that identifies the object. The string is composed by the
type of the instance (C<IO::Special>) and the C<what> attribute:

    $*IN.path.what;  # OUTPUT: «<STDIN>␤»
    $*IN.path.WHICH; # OUTPUT: «IO::Special<STDIN>␤»

=head2 method Str

    method Str(IO::Special:D:)

This returns C«'<STDIN>'», C«'<STDOUT>'», or C«'<STDERR>'» as appropriate.

=head2 method IO

    method IO(IO::Special:D: --> IO::Special)

Returns the invocant.

    say $*IN.path.IO.what;  # OUTPUT: «<STDIN>␤»
    say $*IN.path.what;     # OUTPUT: «<STDIN>␤»

=head2 method e

    method e(IO::Special:D: --> True)

The 'exists' file test operator, always returns C<True>.

=head2 method d

    method d(IO::Special:D: --> False)

The 'directory' file test operator, always returns C<False>.

=head2 method f

    method f(IO::Special:D: --> False)

The 'file' file test operator, always returns C<False>.

=head2 method s

    method s(IO::Special:D: --> 0)

The 'size' file test operator, always returns C<0>.

=head2 method l

    method l(IO::Special:D: --> False)

The 'symbolic links' file test operator, always returns C<False>.

=head2 method r

    method r(IO::Special:D: --> Bool)

The 'read access' file test operator, returns C<True> if and only if
this instance represents the standard input handle(C«<STDIN>»).

=head2 method w

    method w(IO::Special:D: --> Bool)

The 'write access' file test operator, returns C<True>
only if this instance represents either the standard output (C«<STOUT>»)
or the standard error (C«<STDERR>») handle.

=head2 method x

    method x(IO::Special:D: --> False)

The 'execute access' file test operator, always returns C<False>.

=head2 method modified

    method modified(IO::Special:D: --> Instant)

The last modified time for the filehandle.
It always returns an L«C<Instant>|/type/Instant» type
object.

=head2 method accessed

    method accessed(IO::Special:D: --> Instant)

The last accessed time for the filehandle.
It always returns an L«C<Instant>|/type/Instant» type
object.

=head2 method changed

    method changed(IO::Special:D: --> Instant)

The last changed time for the filehandle.
It always returns an L«C<Instant>|/type/Instant» type
object.

=head2 method mode

    method mode(IO::Special:D: --> Nil)

The mode for the filehandle, it always returns L<Nil|/type/Nil>

=end pod
