
=encoding utf8

=head1 NAME

Sidef::Types::Glob::FileHandle

=head1 DESCRIPTION

This class implements file handle operations for reading from and writing to files, as well as in-memory string buffers. It provides methods for I/O operations, file positioning, locking, and iteration over file content.

=head1 SYNOPSIS

    # Open a file and get a FileHandle
    var fh = File("/path/to/file. txt").open_r

    # Read all content
    var content = fh.slurp

    # Read line by line
    fh.each { |line|
        say line
    }

    # Create an in-memory buffer
    var buf = FileHandle.new_buf(: raw, "initial content")
    buf.print("more content")

    # Standard streams
    var stdout = FileHandle.stdout
    var stderr = FileHandle.stderr
    var stdin  = FileHandle.stdin


=head1 INHERITS

Inherits methods from:

       * Sidef::Object::Object

=head1 METHODS

=head2 «

    a « b

Writes the content of C<b> to the file handle C<a> and returns the file handle.  This is an operator alias for writing data to a file handle.

Aliases:  I<E<lt>E<lt>>, I<write_from>

=cut

=head2 »

    a » b

Reads a line from file handle C<a> into variable reference C<b> (with newline removed) and returns the file handle. Sets C<b> to C<nil> at end of file.

Aliases: I<E<gt>E<gt>>, I<read_to>

=cut

=head2 autoflush

    self.autoflush(bool)

Enables or disables autoflush mode on the file handle. When enabled (C<true>), output is flushed immediately after each write operation.  Returns the file handle.

=cut

=head2 binmode

    self. binmode(encoding)

Sets the encoding layer for the file handle. Common values include C<:raw>, C<:utf8>, C<:encoding(UTF-8)>. Returns the file handle.

=cut

=head2 byte

    self.byte(var_ref)

Reads a single byte from the file handle.  If C<var_ref> is provided, stores the byte value (as a Number) in it and returns C<true> on success or C<false> on failure.  Without C<var_ref>, returns the byte value directly or C<nil> at end of file.

Aliases: I<getb>, I<read_byte>

=cut

=head2 call

    self.call

Creates a new FileHandle object.  This is an alias for the constructor.

=cut

=head2 char

    self.char(var_ref)

Reads a single character from the file handle. If C<var_ref> is provided, stores the character in it and returns C<true> on success or C<false> on failure. Without C<var_ref>, returns the character directly or C<nil> at end of file.

Aliases: I<getc>, I<read_char>

=cut

=head2 chars

    self.chars

Reads the entire file and returns an Array of individual characters (as Strings).

=cut

=head2 close

    self.close

Closes the file handle. Returns C<true> on success, C<false> on failure.

=cut

=head2 cp

    self.cp(fh)

Copies the content from this file handle to another FileHandle C<fh>.  Returns C<true> on success, C<false> on failure.

Aliases: I<copy>

=cut

=head2 each

    self.each(code)

Iterates over each line in the file, executing C<code> with each line (with newline removed) as an argument. Returns the file handle.

    fh.each { |line|
        say line
    }

Aliases: I<each_line>

=cut

=head2 each_char

    self.each_char(code)

Iterates over each character in the file, executing C<code> with each character as an argument. Returns the file handle.

    fh.each_char { |char|
        print char
    }

=cut

=head2 eof

    self. eof

Returns C<true> if the file handle is at end of file, C<false> otherwise.

=cut

=head2 fcntl

    self.fcntl(func, flags)

Performs a file control operation on the file handle. Takes a function code and flags as arguments.  Returns C<true> on success, C<false> on failure.

=cut

=head2 file

    self.file

Returns the parent File object associated with this file handle, or the string buffer if this is a buffer handle.

Aliases: I<parent>

=cut

=head2 fileno

    self. fileno

Returns the file descriptor number (as a Number) for the file handle.

=cut

=head2 flock

    self. flock(mode)

Applies an advisory lock on the file handle with the specified mode. Returns C<true> on success, C<false> on failure.

=cut

=head2 get

    self.get(var_ref)

Reads a single line from the file handle (with newline removed). If C<var_ref> is provided, stores the line in it and returns C<true> on success or C<false> at end of file.  Without C<var_ref>, returns the line directly or C<nil> at end of file.

Aliases: I<line>, I<readln>, I<read_line>, I<readline>

=cut

=head2 grep

    self.grep(obj)

Reads all lines from the file and returns an Array containing only the lines for which C<obj> (a Block or Regex) returns true.

    var matches = fh.grep { |line| line.contains("pattern") }

Aliases: I<select>

=cut

=head2 isatty

    self.isatty

Returns C<true> if the file handle is connected to a terminal (TTY), C<false> otherwise.

Aliases: I<is_on_tty>

=cut

=head2 iter

    self.iter

Returns an iterator Block that yields one line at a time (with newline removed) on each call. Returns C<nil> when end of file is reached.

    var iter = fh. iter
    while (defined(var line = iter.run)) {
        say line
    }

=cut

=head2 lines

    self.lines

Reads all lines from the file and returns them as an Array of Strings (with newlines removed).

    var lines = fh. lines

Aliases: I<read_lines>, I<readlines>

=cut

=head2 lock

    self. lock

Applies an exclusive lock (LOCK_EX) on the file handle.  Returns C<true> on success, C<false> on failure.

=cut

=head2 lstat

    self.lstat

Returns a Stat object with information about the file (without following symbolic links).

=cut

=head2 map

    self.map(block)

Reads all lines from the file and applies C<block> to each line, returning an Array of the transformed results.

    var upper = fh.map { |line| line. uc }

Aliases: I<collect>

=cut

=head2 new_buf

    self. new_buf(mode, initial_string)

Creates a new in-memory file handle backed by a string buffer. The C<mode> can be C<:raw> for binary mode or an encoding like C<:utf8>. The C<initial_string> provides the initial content. Returns the FileHandle (or in list context, both the FileHandle and the String buffer).

    var buf = FileHandle.new_buf(:raw, "initial")
    buf.print("appended")
    say buf.parent  # => "initialappended"

Aliases: I<new_buffer>

=cut

=head2 print

    self.print(*args)

Writes the given arguments to the file handle without a trailing newline. Returns C<true> on success, C<false> on failure.

Aliases: I<spurt>, I<write>

=cut

=head2 printf

    self.printf(*args)

Writes formatted output to the file handle using a format string and arguments (similar to C printf). Returns C<true> on success, C<false> on failure.

    fh.printf("%s:  %d\n", name, value)

=cut

=head2 read

    self.read(var_ref, length, offset)

Reads up to C<length> bytes from the file handle into C<var_ref>, optionally at the specified C<offset>. Returns the number of bytes read.

=cut

=head2 rewind

    self. rewind

Repositions the file pointer to the beginning of the file. Returns C<true> on success, C<false> on failure.

=cut

=head2 say

    self.say(*args)

Writes the given arguments to the file handle followed by a newline.  Returns C<true> on success, C<false> on failure.

Aliases: I<println>

=cut

=head2 sayf

    self.sayf(format, *args)

Writes formatted output to the file handle followed by a newline.  Returns C<true> on success, C<false> on failure.

    fh. sayf("%s:  %d", name, value)

Aliases: I<printlnf>

=cut

=head2 seek

    self. seek(pos, whence)

Positions the file pointer at C<pos> bytes relative to C<whence>. The C<whence> value can be 0 (beginning), 1 (current position), or 2 (end of file). Returns C<true> on success, C<false> on failure.

=cut

=head2 slurp

    self.slurp

Reads and returns the entire remaining content of the file as a single String.

    var content = fh.slurp

=cut

=head2 stat

    self.stat

Returns a Stat object with information about the file.

=cut

=head2 stderr

    self.stderr

Returns a FileHandle for the standard error stream (STDERR).

    var stderr = FileHandle.stderr

=cut

=head2 stdin

    self.stdin

Returns a FileHandle for the standard input stream (STDIN).

    var stdin = FileHandle.stdin

=cut

=head2 stdout

    self.stdout

Returns a FileHandle for the standard output stream (STDOUT).

    var stdout = FileHandle.stdout

=cut

=head2 sysread

    self.sysread(var_ref, length, offset)

Performs a low-level read of up to C<length> bytes from the file handle into C<var_ref>, optionally at the specified C<offset>. Returns the number of bytes read.  This bypasses buffered I/O.

=cut

=head2 sysseek

    self. sysseek(pos, whence)

Performs a low-level seek to position C<pos> relative to C<whence>. Returns C<true> on success, C<false> on failure.  This bypasses buffered I/O.

=cut

=head2 syswrite

    self.syswrite(scalar, length, offset)

Performs a low-level write of C<scalar> to the file handle, optionally writing only C<length> bytes starting at C<offset>. Returns C<true> on success, C<false> on failure.  This bypasses buffered I/O.

=cut

=head2 tell

    self.tell

Returns the current position (as a Number) of the file pointer in bytes from the beginning of the file.

=cut

=head2 truncate

    self. truncate(length)

Truncates the file to the specified C<length> in bytes (default 0). Returns C<true> on success, C<false> on failure.

=cut

=head2 unlock

    self. unlock

Releases the advisory lock on the file handle (LOCK_UN). Returns C<true> on success, C<false> on failure.

=cut

=head2 words

    self.words

Reads the entire file and returns an Array of all whitespace-separated words as Strings.

    var words = fh.words

=cut
