/ 
Sidef-26.01
River stage one • 1 direct dependent • 1 total dependent
⭐ Starred 115 GitHub stars
/ Sidef::Types::Glob::FileHandle

NAME

Sidef::Types::Glob::FileHandle

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.

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

INHERITS

Inherits methods from:

* Sidef::Object::Object

METHODS

«

a « b

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

Aliases: <<, write_from

»

a » b

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

Aliases: >>, read_to

autoflush

self.autoflush(bool)

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

binmode

self. binmode(encoding)

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

byte

self.byte(var_ref)

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

Aliases: getb, read_byte

call

self.call

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

char

self.char(var_ref)

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

Aliases: getc, read_char

chars

self.chars

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

close

self.close

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

cp

self.cp(fh)

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

Aliases: copy

each

self.each(code)

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

fh.each { |line|
    say line
}

Aliases: each_line

each_char

self.each_char(code)

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

fh.each_char { |char|
    print char
}

eof

self. eof

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

fcntl

self.fcntl(func, flags)

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

file

self.file

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

Aliases: parent

fileno

self. fileno

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

flock

self. flock(mode)

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

get

self.get(var_ref)

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

Aliases: line, readln, read_line, readline

grep

self.grep(obj)

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

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

Aliases: select

isatty

self.isatty

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

Aliases: is_on_tty

iter

self.iter

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

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

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: read_lines, readlines

lock

self. lock

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

lstat

self.lstat

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

map

self.map(block)

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

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

Aliases: collect

new_buf

self. new_buf(mode, initial_string)

Creates a new in-memory file handle backed by a string buffer. The mode can be :raw for binary mode or an encoding like :utf8. The 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: new_buffer

print

self.print(*args)

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

Aliases: spurt, write

printf

self.printf(*args)

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

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

read

self.read(var_ref, length, offset)

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

rewind

self. rewind

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

say

self.say(*args)

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

Aliases: println

sayf

self.sayf(format, *args)

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

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

Aliases: printlnf

seek

self. seek(pos, whence)

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

slurp

self.slurp

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

var content = fh.slurp

stat

self.stat

Returns a Stat object with information about the file.

stderr

self.stderr

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

var stderr = FileHandle.stderr

stdin

self.stdin

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

var stdin = FileHandle.stdin

stdout

self.stdout

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

var stdout = FileHandle.stdout

sysread

self.sysread(var_ref, length, offset)

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

sysseek

self. sysseek(pos, whence)

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

syswrite

self.syswrite(scalar, length, offset)

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

tell

self.tell

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

truncate

self. truncate(length)

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

unlock

self. unlock

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

words

self.words

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

var words = fh.words