lib/rio/if/stream.rb in rio-0.3.7 vs lib/rio/if/stream.rb in rio-0.3.8

- old
+ new

@@ -1,8 +1,8 @@ #-- # =============================================================================== -# Copyright (c) 2005, Christopher Kleckner +# Copyright (c) 2005, 2006 Christopher Kleckner # All rights reserved # # This file is part of the Rio library for ruby. # # Rio is free software; you can redistribute it and/or modify @@ -20,11 +20,11 @@ # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA # =============================================================================== #++ # # To create the documentation for Rio run the command -# rake rdoc +# ruby build_doc.rb # from the distribution directory. Then point your browser at the 'doc/rdoc' directory. # # Suggested Reading # * RIO::Doc::SYNOPSIS # * RIO::Doc::INTRO @@ -47,11 +47,11 @@ # # astring = rio('afile.txt').gets # read the first line of afile.txt into astring # def gets(sep_string=$/) target.gets(sep_string) end - # Slurps the contents of the rio into a string. See also Rio#contents + # Slurps the contents of the rio into a string. # # astring = rio('afile.txt').contents # slurp the entire contents of afile.txt into astring # def contents() target.contents() end @@ -193,10 +193,72 @@ # file. # def readline(*args) target.readline(*args) end + # 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" + # + def readpartial(*args) target.readpartial(*args) end + + # 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. @@ -281,20 +343,20 @@ # # Equivalent to # ario.write(*args) # ario.close # - def write!(*argv) target.write!(*argv); self end + def write!(*argv) target.write!(*argv) end # 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. # - def write(*argv) target.write(*argv); self end + def write(*argv) target.write(*argv) end # Calls IO#eof? # ario.eof => true or false # Returns true if _ario_ is at end of file. The stream must be opened @@ -402,12 +464,12 @@ # 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 + # (<tt>Array#pack</tt> might be a useful way to build this string). On Unix + # platforms, see <tt>fcntl(2)</tt> for details. Not implemented on all # platforms. # # def fcntl(integer_cmd,arg) target.fcntl(integer_cmd,arg) end @@ -444,25 +506,26 @@ def fsync() target.fsync end # Calls IO#pid # ario.pid => fixnum # Returns the process ID of a child process associated with _ario_. - # This will be set by +IO::popen+. + # This will be set by <tt>IO::popen</tt>. # - # pipe = IO.popen("-") - # if pipe - # $stderr.puts "In parent, child pid is #{pipe.pid}" - # else - # $stderr.puts "In child, pid is #{$$}" - # end + # pipe = IO.popen("-") + # if pipe + # $stderr.puts "In parent, child pid is #{pipe.pid}" + # else + # $stderr.puts "In child, pid is #{$$}" + # end # - # _produces:_ + # produces: # - # In child, pid is 26209 - # In parent, child pid is 26209 + # In child, pid is 26209 + # In parent, child pid is 26209 # # + def pid() target.pid end # Calls IO#putc # ario.putc(obj) => obj # If _obj_ is +Numeric+, write the character whose code is _obj_, @@ -487,10 +550,11 @@ # f = File.new("testfile") # f.getc #=> 84 # f.getc #=> 104 # # + def getc() target.getc() end # Calls IO#readchar # ario.readchar => fixnum # Reads a character as with +IO#getc+, but raises an +EOFError+ on # end of file. @@ -509,11 +573,13 @@ # f2.readlines[0] #=> "This is line one\n" # f2.reopen(f1) #=> #<File:testfile> # f2.readlines[0] #=> "This is line one\n" # # + #def reopen(m) target.reopen(m) end + # Calls IO#stat # ario.stat => stat # Returns status information for _ario_ as an object of type # +File::Stat+. # @@ -523,32 +589,22 @@ # s.blksize #=> 4096 # s.atime #=> Wed Apr 09 08:53:54 CDT 2003 # # - # Calls IO#tell - # ario.pos => integer - # ario.tell => integer - # Returns the current offset (in bytes) of _ario_. - # - # f = rio("testfile") - # f.pos #=> 0 - # f.gets #=> "This is line one\n" - # f.pos #=> 17 - # - # - # Calls IO#to_i # to_i() # Alias for #fileno # # + def to_i() target.to_i() end # Calls IO#to_io # ario.to_io -> ios # Returns _ario_. # # + def to_io() target.to_io() end # Calls IO#tty? # ario.tty? => true or false # Returns +true+ if _ario_ is associated with a terminal device (tty), # +false+ otherwise.