module RIO::IF::RubyIO

Public Instance Methods

binmode() click to toggle source

Calls IO#binmode

Puts rio into binary mode. This is useful only in MS-DOS/Windows environments. Once a stream is in binary mode, it cannot be reset to nonbinary mode.

Returns the Rio.

rio('afile.exe').binmode.bytes(512).to_a # read a file in 512 byte blocks
# File lib/rio/if/rubyio.rb, line 125
def binmode() target.binmode(); self end
close() click to toggle source

Calls IO#close

ario.close   => nil

Closes ario and flushes any pending writes to the operating system. The stream is unavailable for any further data operations; an IOError is raised if such an attempt is made. I/O streams are automatically closed when they are claimed by the garbage collector.

# File lib/rio/if/rubyio.rb, line 441
def close() target.close(); self end
close_write() click to toggle source
# File lib/rio/if/rubyio.rb, line 442
def close_write() target.close_write(); self end
each_byte(*args,&block) click to toggle source

Calls IO#each_byte

ario.each_byte {|byte| block }  => ario

Calls the given block once for each byte (0..255) in ario, passing the byte as an argument.

# File lib/rio/if/rubyio.rb, line 142
def each_byte(*args,&block) target.each_byte(*args,&block); self end
each_line(*args,&block) click to toggle source

Calls IO#each_line

ario.each_line(sep_string=$/) {|line| block }  => ario

Executes the block for every line in ario, where lines are separated by sep_string.

# File lib/rio/if/rubyio.rb, line 156
def each_line(*args,&block) target.each_line(*args,&block); self end
eof?() click to toggle source

Calls IO#eof?

ario.eof     => true or false

Returns true if ario is at end of file. The stream must be opened for reading or an IOError will be raised.

# File lib/rio/if/rubyio.rb, line 345
def eof?() target.eof? end
fcntl(integer_cmd,arg) click to toggle source

Calls IO#fcntl

ario.fcntl(integer_cmd, arg)    => integer

Provides a mechanism for issuing low-level commands to control or query file-oriented I/O streams. Arguments and results are platform dependent. If arg is a number, its value is passed directly. If it is a string, it is interpreted as a binary sequence of bytes (Array#pack might be a useful way to build this string). On Unix platforms, see fcntl(2) for details. Not implemented on all platforms.

# File lib/rio/if/rubyio.rb, line 455
def fcntl(integer_cmd,arg) target.fcntl(integer_cmd,arg) end
fileno() click to toggle source

Calls IO#fileno

ario.fileno    => fixnum
ario.to_i      => fixnum

Returns an integer representing the numeric file descriptor for ario.

# File lib/rio/if/rubyio.rb, line 474
def fileno() target.fileno() end
flush() click to toggle source

Calls IO#flush

ario.flush    => ario

Flushes any buffered data within ario to the underlying operating system (note that this is Ruby internal buffering only; the OS may buffer the data as well).

# File lib/rio/if/rubyio.rb, line 134
def flush() target.flush(); self end
fsync() click to toggle source

Calls IO#fsync

ario.fsync   => ario

Immediately writes all buffered data in ario to disk and return ario. Does nothing if the underlying operating system does not support _fsync(2)_. Note that fsync differs from using #sync. The latter ensures that data is flushed from Ruby's buffers, but doesn't not guarantee that the underlying operating system actually writes it to disk.

# File lib/rio/if/rubyio.rb, line 487
def fsync() target.fsync end
getc() click to toggle source

Calls IO#getc

ario.getc   => fixnum or nil

Gets the next 8-bit byte (0..255) from ario. Returns nil if called at end of file.

f = File.new(“testfile”) f.getc #=> 84 f.getc #=> 104

# File lib/rio/if/rubyio.rb, line 536
def getc() target.getc() end
gets(sep_string=$/) click to toggle source

Calls IO#gets

Reads the next line from the Rio; lines are separated by sep_string. A separator of nil reads the entire contents, and a zero-length separator reads the input a paragraph at a time (two successive newlines in the input separate paragraphs).

Returns nil if called at end of file.

astring  = rio('afile.txt').gets # read the first line of afile.txt into astring
# File lib/rio/if/rubyio.rb, line 37
def gets(sep_string=$/) target.gets(sep_string) end
ioctl(integer_cmd,arg) click to toggle source

Calls IO#ioctl

ario.ioctl(integer_cmd, arg)    => integer

Provides a mechanism for issuing low-level commands to control or query I/O devices. Arguments and results are platform dependent. If arg is a number, its value is passed directly. If it is a string, it is interpreted as a binary sequence of bytes. On Unix platforms, see +ioctl(2)+ for details. Not implemented on all platforms.

# File lib/rio/if/rubyio.rb, line 466
def ioctl(integer_cmd,arg) target.ioctl(integer_cmd,arg) end
ioh(*args) click to toggle source

Provides direct access to the IO handle (as would be returned by ::IO#new) with filtering. Reading from and writing to this handle will be affected by such things as #gzip and #chomp if they were specified for the Rio.

Compare this with #ios

# File lib/rio/if/rubyio.rb, line 353
def ioh(*args) target.ioh() end
ios(*args) click to toggle source

Provides direct access to the IO handle (as would be returned by ::IO#new) Reading from and writing to this handle is not affected by such things as #gzip and #chomp.

Compare this with #ioh

# File lib/rio/if/rubyio.rb, line 361
def ios(*args) target.ios() end
lineno() click to toggle source

Calls IO#lineno

Returns the current line number of a Rio.

The Rio will be opened for reading if not already. lineno counts the number of times gets is called, rather than the number of newlines encountered – so lineno will only be accurate if the file is read exclusively with line-oriented methods (#readline, #each_line, #gets etc.)

See also the $. variable and #recno

f = rio("testfile")
f.lineno   #=> 0
f.gets     #=> "This is line one\n"
f.lineno   #=> 1
f.gets     #=> "This is line two\n"
f.lineno   #=> 2
# File lib/rio/if/rubyio.rb, line 67
def lineno() target.lineno() end
lineno=(integer) click to toggle source

Calls IO#lineno=

ario.lineno = integer    => integer

Manually sets the current line number to the given value. $. is updated only on the next read.

f = rio(“testfile”) f.gets #=> “This is line onen” $. #=> 1 f.lineno = 1000 f.lineno #=> 1000 $. # lineno of last read #=> 1 f.gets #=> “This is line twon” $. # lineno of last read #=> 1001

# File lib/rio/if/rubyio.rb, line 84
def lineno=(integer) target.lineno = integer end
mode(m,*args) click to toggle source

Explicitly set the mode with which a Rio will be opened.

ario.mode('r+')   => ario

Normally one needs never open a Rio or specify its mode – the mode is determined by the operation the Rio is asked to perform. (i.e. #print requires write access, #readlines requires read access). However there are times when one wishes to be specific about the mode with which a Rio will be opened. Note that explicitly setting the mode overrides all of Rio's internal mode logic. If a mode is specified via #mode or #open that mode will be used. Period.

Returns the Rio.

See also #mode?

If the mode is given as a String, it must be one of the values listed in the following table.

 Mode |  Meaning
 -----+--------------------------------------------------------
 "r"  |  Read-only, starts at beginning of file  (default mode).
 -----+--------------------------------------------------------
 "r+" |  Read-write, starts at beginning of file.
 -----+--------------------------------------------------------
 "w"  |  Write-only, truncates existing file
      |  to zero length or creates a new file for writing.
 -----+--------------------------------------------------------
 "w+" |  Read-write, truncates existing file to zero length
      |  or creates a new file for reading and writing.
 -----+--------------------------------------------------------
 "a"  |  Write-only, starts at end of file if file exists,
      |  otherwise creates a new file for writing.
 -----+--------------------------------------------------------
 "a+" |  Read-write, starts at end of file if file exists,
      |  otherwise creates a new file for reading and
      |  writing.
 -----+--------------------------------------------------------
  "b" |  (DOS/Windows only) Binary file mode (may appear with
      |  any of the key letters listed above).

ario = rio('afile').mode('r+').nocloseoneof # file will be opened in r+ mode
                                           # don't want the file closed at eof
ario.seek(apos).gets # read the string at apos in afile
ario.rewind.gets # read the string at the beginning of the file
ario.close

TODO:

  • Add support for integer modes

# File lib/rio/if/rubyio.rb, line 410
def mode(m,*args) target.mode(m,*args); self end
mode?() click to toggle source

Query a Rio's mode

ario.mode?      #=> a mode string

See #mode

ario = rio('afile')
ario.puts("Hello World") 
ario.mode?      #=> 'w' {#puts}[rdoc-ref:IF::RubyIO#puts] requires write access

ario = rio('afile')
ario.gets
ario.mode?      #=> 'r' {#gets}[rdoc-ref:IF::RubyIO#gets] requires read access

ario = rio('afile').mode('w+').nocloseoneof
ario.gets
ario.mode?      #=> 'w+' Set explictly
# File lib/rio/if/rubyio.rb, line 429
def mode?() target.mode?() end
nosync(arg=false,&block) click to toggle source

Similar to IO#sync= false

ario.nosync(&block)   => ario

Sets the Rio so that its 'sync mode' will be set to false when opened, or set it immediately if already open. When sync mode is true, all output is immediately flushed to the underlying operating system and is not buffered internally. Returns the rio. See also #fsync, #sync, #sync?.

If a block is given behaves like ario.nosync.each(&block)

f = rio("testfile").sync.puts("Hello World")
f.sync?     # => true
f.nosync
f.sync?     # => false
# File lib/rio/if/rubyio.rb, line 644
def nosync(arg=false,&block) target.nosync(arg,&block); self end
pid() click to toggle source

Calls IO#pid

ario.pid    => fixnum

Returns the process ID of a child process associated with ario. This will be set by IO::popen.

pipe = IO.popen("-")
if pipe
  $stderr.puts "In parent, child pid is #{pipe.pid}"
else
  $stderr.puts "In child, pid is #{$$}"
end

produces:

In child, pid is 26209
In parent, child pid is 26209
# File lib/rio/if/rubyio.rb, line 507
def pid() target.pid end
print(*args,&block) click to toggle source

Calls IO::print

Writes the given object(s) to the Rio. If the output record separator ($) is not nil, it will be appended to the output. If no arguments are given, prints $_. Objects that aren't strings will be converted by calling their to_s method. Returns the Rio.

rio('f.txt').print("Hello Rio\n") # print the string to f.txt
rio(?-).print("Hello Rio\n") # print the string to stdout
print!(*args,&block) click to toggle source

Writes the given objects to the rio as with #print and then closes the Rio. Returns the Rio.

Equivalent to rio.print(*args).close

rio('f.txt').print!("Hello Rio\n") # print the string to f.txt then close it
printf(*argv) click to toggle source

Calls IO#printf

ario.printf(format_string [, obj, ...] )   => ario

Formats and writes to ario, converting parameters under control of the format string. See +Kernel#sprintf+ for details.

# File lib/rio/if/rubyio.rb, line 275
def printf(*argv) target.printf(*argv); self end
printf!(*argv) click to toggle source

Writes the given objects to the rio as with #printf and then closes the rio. Returns the rio.

Equivalent to rio.printf(*args).close

# File lib/rio/if/rubyio.rb, line 267
def printf!(*argv) target.printf!(*argv); self end
putc(*argv) click to toggle source

Calls IO#putc

ario.putc(obj)    => ario

If obj is Numeric, write the character whose code is obj, otherwise write the first character of the string representation of obj to ario.

stdout = rio(?-)
stdout.putc "A"
stdout.putc 65

produces:

AA
# File lib/rio/if/rubyio.rb, line 300
def putc(*argv) target.putc(*argv); self end
putc!(*argv) click to toggle source

Writes the given objects to the rio as with #putc and then closes the rio. Returns the rio.

Equivalent to rio.putc(*args).close

# File lib/rio/if/rubyio.rb, line 283
def putc!(*argv) target.putc!(*argv); self end
puts(*args) click to toggle source

Calls IO#puts

Writes the given objects to the rio as with #print. Writes a record separator (typically a newline) after any that do not already end with a newline sequence. If called with an array argument, writes each element on a new line. If called without arguments, outputs a single record separator. Returns the rio.

# File lib/rio/if/rubyio.rb, line 310
def puts(*args) target.puts(*args); self end
puts!(*args) click to toggle source

Writes the given objects to the rio as with #puts and then closes the rio. Returns the rio.

Equivalent to rio.puts(*args).close

rio('f.txt').puts!('Hello Rio') # print the string to f.txt then close it
# File lib/rio/if/rubyio.rb, line 319
def puts!(*args) target.puts!(*args); self end
readline(*args) click to toggle source

Calls IO#readline

ario.readline(sep_string=$/)   => string

Reads a line as with +IO#gets+, but raises an EOFError on end of file.

# File lib/rio/if/rubyio.rb, line 175
def readline(*args) target.readline(*args) end
readlines(*args,&block) click to toggle source

Calls IO#readlines

Reads all of the lines in a Rio, and returns them in anArray. Lines are separated by the optional aSepString. The stream must be opened for reading or an IOerror will be raised.

an_array = rio('afile.txt').readlines # read afile.txt into an array
an_array = rio('afile.txt').chomp.readlines # read afile.txt into an array with each line chomped
# File lib/rio/if/rubyio.rb, line 168
def readlines(*args,&block) target.readlines(*args,&block) end
readpartial(*args) click to toggle source

Calls IO#readpartial

Reads at most maxlen bytes from the I/O stream but it blocks only if ios has no data immediately available. If the optional outbuf argument is present, it must reference a String, which will receive the data. It raises EOFError on end of file.

readpartial is designed for streams such as pipe, socket, tty, etc. It blocks only when no data immediately available. This means that it blocks only when following all conditions hold.

  • the buffer in the IO object is empty.

  • the content of the stream is empty.

  • the stream is not reached to EOF.

When readpartial blocks, it waits data or EOF on the stream. If some data is reached, readpartial returns with the data. If EOF is reached, readpartial raises EOFError.

When readpartial doesn�t blocks, it returns or raises immediately. If the buffer is not empty, it returns the data in the buffer. Otherwise if the stream has some content, it returns the data in the stream. Otherwise if the stream is reached to EOF, it raises EOFError.

r, w = IO.pipe           #               buffer          pipe content
w << "abc"               #               ""              "abc".
r.readpartial(4096)      #=> "abc"       ""              ""
r.readpartial(4096)      # blocks because buffer and pipe is empty.

r, w = IO.pipe           #               buffer          pipe content
w << "abc"               #               ""              "abc"
w.close                  #               ""              "abc" EOF
r.readpartial(4096)      #=> "abc"       ""              EOF
r.readpartial(4096)      # raises EOFError

r, w = IO.pipe           #               buffer          pipe content
w << "abc\ndef\n"        #               ""              "abc\ndef\n"
r.gets                   #=> "abc\n"     "def\n"         ""
w << "ghi\n"             #               "def\n"         "ghi\n"
r.readpartial(4096)      #=> "def\n"     ""              "ghi\n"
r.readpartial(4096)      #=> "ghi\n"     ""              ""

Note that readpartial is nonblocking-flag insensitive. It blocks even if the nonblocking-flag is set.

Also note that readpartial behaves similar to sysread in blocking mode. The behavior is identical when the buffer is empty. ios.reopen(other_IO) => ios ios.reopen(path, mode_str) => ios

Reassociates ios with the I/O stream given in other_IO or to a new stream opened on path. This may dynamically change the actual class of this stream.

f1 = File.new("testfile")
f2 = File.new("testfile")
f2.readlines[0]   #=> "This is line one\n"
f2.reopen(f1)     #=> #<File:testfile>
f2.readlines[0]   #=> "This is line one\n"
# File lib/rio/if/rubyio.rb, line 237
def readpartial(*args) target.readpartial(*args) end
recno() click to toggle source

Returns the current record number of a Rio. The recno is the index used by the grande selection methods. It represents the zero-based index of the last record read. Returns nil until a record has been read.

see #lines #bytes and #records

To illustrate: Given a file containing three lines “L0n”,“L1n”,“L2n” and a Range (0..1) Each of the following would fill anarray with [“L0n”, “L1n”]

Given:

anarray = []
range = (0..1)

all_lines = rio('afile').readlines
all_lines.each_with_index do |line,i|
  anarray << line if range === i
end
# anarray == ["L0\n", "L1\n"]

anarray = rio('afile').lines[0..1] # anarray == ["L0\n", "L1\n"]

recno counts the number of times #getrec or #each is used to get a record. so recno will only concern parts of the file read with grande methods #each, #[], #getrec

See also #lineno

# File lib/rio/if/rubyio.rb, line 113
def recno() target.recno() end
sync(arg=true,&block) click to toggle source

Sets the 'sync-mode' of the underlying IO using IO#sync=

ario.sync(boolean=true,&block)   => ario

Sets the Rio so that its 'sync mode' will be set to true or false when opened, or set it immediately if already open. When sync mode is true, all output is immediately flushed to the underlying operating system and is not buffered internally. Returns the rio. See also #fsync, #nosync, #sync?.

If a block is given behaves like ario.sync(arg).each(&block)

f = rio("testfile").sync.puts("Hello World")
f.sync?     # => true
# File lib/rio/if/rubyio.rb, line 627
def sync(arg=true,&block) target.sync(arg,&block); self end
sync?() click to toggle source

Query the current “sync mode” with IO#sync

ario.sync?    => true or false

Returns the current “sync mode” of ario. When sync mode is true, all output is immediately flushed to the underlying operating system and is not buffered by Ruby internally. See also #fsync, #sync, #nosync

f = rio("testfile")
f.sync?   #=> false
# File lib/rio/if/rubyio.rb, line 656
def sync?() target.sync?() end
to_i() click to toggle source

Calls IO#to_i

to_i()

Alias for fileno

# File lib/rio/if/rubyio.rb, line 580
def to_i() target.to_i() end
to_io() click to toggle source

Calls IO#to_io

ario.to_io -> ios

Returns ario.

# File lib/rio/if/rubyio.rb, line 587
def to_io() target.to_io() end
tty?() click to toggle source

Calls IO#tty?

ario.tty?     => true or false

Returns true if ario is associated with a terminal device (tty), false otherwise.

rio("testfile").tty?   #=> false
rio("/dev/tty").tty?   #=> true
# File lib/rio/if/rubyio.rb, line 598
def tty?() target.tty?() end
ungetc(*args) click to toggle source

Calls IO#ungetc

ario.ungetc(integer)   => ario

Pushes back one character (passed as a parameter) onto ario, such that a subsequent buffered read will return it. Only one character may be pushed back before a subsequent read operation (that is, you will be able to read only the last of several characters that have been pushed back).

f = rio("testfile")        #=> #<Rio:testfile>
c = f.getc                 #=> 84
f.ungetc(c).getc           #=> 84
# File lib/rio/if/rubyio.rb, line 612
def ungetc(*args) target.ungetc(*args); self end
write(*argv) click to toggle source

Calls IO#write

ario.write(string)    => integer

Writes the given string to ario. If the argument is not a string, it will be converted to a string using to_s. Returns the number of bytes written.

# File lib/rio/if/rubyio.rb, line 337
def write(*argv) target.write(*argv) end
write!(*argv) click to toggle source

Writes the given objects to the rio as with #write and then closes the rio.

Equivalent to

ario.write(*args)
ario.close
# File lib/rio/if/rubyio.rb, line 328
def write!(*argv) target.write!(*argv) end