=begin pod

=TITLE class IO::Handle

=SUBTITLE Opened file or stream

   class IO::Handle does IO { }

=head1 Methods

=head2 method get

Reads a single line from the input stream (usually the Standard Input or a file).

Read one line from the standard input:

    $*IN.get;

Read one line from a file:

    my $fh = open 'filename';
    my $line = $fh.get;


=head2 method getc

Read a single character from the input stream or return Nil. The operation is blocking
and the stream may be buffered.

=head2 method eof

Returns L<Bool::True> if the read operations have exhausted the content of the file.

=head2 method lines

    method lines($limit = Inf)

Return a lazy list of the file's lines read via L<get>, limited to C<$limit> lines.
The new line separator (e.g. $*IN.nl-in) will be excluded.

    =for code :allow<B>
    my @data;
    my $data-file = open 'readings.csv';
    for B<$data-file.lines> -> $line {
        @data.push($line.split(','))
    }

=head2 method words

    method words($count = Inf)

Return a lazy list of the file's words (separated on whitespace), limited
to C<$count> words.

    =for code :allow<B>
    my %dict;
    ++%dict{$_} for $*IN.words;
    say "Most common words: ", %dict.sort(*.value).reverse.[^5];

=head2 method split

    method split(splitter = "")

Returns a lazy list of strings found between the splitter, just like C<split>
on strings.

=head2 method comb

    method comb(comber = "")

Returns a lazy list of strings combed from the handle, just like C<comb>
on strings.

=head2 method print

    method print(*@text --> Bool)

Text writing; writes the given C<@text> to the filehandle.  See L<write>
to write bytes.

    my $fh = open 'path/to/file', :w;
    $fh.print("some text\n");
    $fh.close;

=head2 method read

    method read(IO::Handle:D: Int(Cool:D) $bytes --> Blob)

Binary reading; reads and returns up to C<$bytes> bytes from the filehandle.

=head2 method readchars

    method readchars(IO::Handle:D: Int(Cool:D) $chars --> Str)

Reading chars; reads and returns up to C<$chars> chars (graphemes) from the
filehandle.

=head2 method write

    method write(IO::Handle:D: Blob:D $buf)

Binary writing; writes C<$buf> to the filehandle.  See L<print> to write
characters.

=head2 method seek

     method seek(IO::Handle:D: Int:D $offset, SeekType:D $whence --> True)

Move the file pointer (that is the position at which any subsequent read
or write operations will begin,) to the byte position specified by
C<$offset> relative to the location specified by C<$whence> which may be
one of:

=item SeekFromBeginning

The beginning of the file.

=item SeekFromCurrent

The current position in the file.

=item SeekFromEnd

The end of the file.  Please note that you need to specify a negative
offset if you want to position before the end of the file.

=head2 method tell

    method tell(IO::Handle:D: --> Int)

Return the current position of the file pointer in bytes.

=head2 method ins

    method ins(IO::Handle:D: --> Int)

Return the number of lines read from the file.

=head2 method slurp-rest

    multi method slurp-rest(IO::Handle:D: :$bin! --> Buf)
    multi method slurp-rest(IO::Handle:D: :$enc --> Str)

Return the remaining content of the file from the current file position
(which may have been set by previous reads or by C<seek>.)  If the
adverb C<:bin> is provided a L<Buf> will be returned,
otherwise the return will be a C<Str> with the optional encoding C<:enc>.

=head2 method Supply

    multi method Supply(IO::Handle:D: :$size = 65536, :$bin --> Supply)

Returns a C<Supply> that will emit the contents of the handle in chunks.
The size of the chunks is determined by the optional C<:size> named parameter
and defaults to 64K.  The optional C<:bin> named parameter can be specified
to indicate binary reading of the contents, rather than character based
reading.

=head2 method close

Will close a previously opened filehandle.

    $fh.close;

=head2 method flush

Will flush the filehandle to disk.

    $fh.flush;

=head2 method native-descriptor

    method native-descriptor()

This returns a value that the operating system would understand as a "file descriptor" and
is suitable for passing to a native function that requires a file descriptor as an
argument such as C<fcntl> or C<ioctl>. 

=head1 Related roles and classes

See also the related role L<IO> and the related class L<IO::Path>.

=end pod

# vim: expandtab shiftwidth=4 ft=perl6
