+# Methods common to IO::Readable, IO::Writable, and IO::Seekable.
+module IO::Common
+
+ # Calls both +close_read+ and +close_write+, and raises an exception unless
+ # at least one succeeds. It may be desirable to reimplement this.
+ def close
+ cr = respond_to?(:close_read)
+ cw = respond_to?(:close_write)
+ if cr && cw
+ failed = false
+ begin
+ close_read
+ rescue IOError
+ failed = $!
+ end
+ begin
+ close_write
+ rescue IOError
+ return unless failed
+ raise
+ end
+ elsif cr
+ close_read
+ elsif cw
+ close_write
+ else
+ raise NotImplementedError, "close_read and close_write unimplemented", caller
+ end
+ end
+
+ # Checks both +closed_read+? and +closed_write+?, raising an exception if
+ # neither method exists. This method must be redefined for IO::Readable
+ # and IO::Writable classes unless one of the previously mentioned methods
+ # has been provided.
+ def closed?
+ cr = respond_to?(:closed_read?)
+ cw = respond_to?(:closed_write?)
+ if cr && cw
+ return closed_read? && closed_write?
+ elsif cr
+ return closed_read?
+ elsif cw
+ return closed_write?
+ else
+ raise NotImplementedError, "closed_read? and closed_write? unimplemented", caller
+ end
+ end
+
+ # Do not override this method. Instead, use +isatty+.
+ def tty?
+ isatty
+ end
+
+ # Always +false+. May be redefined.
+ def isatty
+ false
+ end
+
+ # Always 0. May be redefined.
+ def fsync
+ 0
+ end
+
+ # Always +true+. May be redefined.
+ def sync
+ true
+ end
+
+ # Raises a +NotImplementedError+. May be redefined.
+ def fcntl(*args)
+ raise NotImplementedError, "fcntl not implemented", caller
+ end
+
+ # Always returns the object. May be redefined.
+ def binmode
+ self
+ end
+
+ [ :fileno, :pid, :sync=, :path ].each do |method|
+ define_method(method) {nil}
+ end
+
+end
+
+# The IO::Readable mixin provides classes with several methods for reading
+# a data stream, similar to those found in the IO class. The +sysread+ and
+# +close_read+ methods must be defined. Additionally, <tt>closed_read?</tt>,
+# <tt>closed?</tt>, and <tt>close</tt> are recommended.
+#
+# IO::Readable provides buffering, but only the absolute minimum needed to
+# provide a complete implementation. For example, #eof checks for the end of
+# file by reading and buffering a single byte.
+#
+# The example below illustrates the use of IO::Readable in a class that
+# concatenates multiple streams. Note that seeking is not supported but one
+# can start over with #rewind.
+#
+# :include:../../test/read_joiner.rb
+module IO::Readable
+
+ REQUIRED_METHODS = [ :sysread, :close_read ]
+
+ include IO::Common
+ include Enumerable
+
+ # This adds three identically named class methods that function like
+ # IO::read, IO::readlines, and IO::foreach. These may be factored into
+ # IO::Openable or removed entirely in a future release.
+ def self.included(base) #:nodoc:
+ unless base.respond_to?(:read)
+ def base.read(name,length=nil,offset=nil)
+ name = [name] unless name.respond_to?(:to_ary)
+ object = new(*name)
+ object.seek(offset) if offset
+ object.read(length)
+ ensure
+ object.close_read if object.respond_to?(:close_read)
+ end
+ end
+ unless base.respond_to?(:readlines)
+ def base.readlines(name,sep_string=$/)
+ name = [name] unless name.respond_to?(:to_ary)
+ object = new(*name)
+ object.readlines(sep_string)
+ ensure
+ object.close_read if object.respond_to?(:close_read)
+ end
+ end
+ unless base.respond_to?(:foreach)
+ def base.foreach(*args,&block)
+ readlines(*args).each(&block)
+ end
+ end
+ super
+ end
+
+ # As with with IO#gets, read and return a line, with lines separated by
+ # +sep_string+. This method may be overridden, although this is not
+ # recommended unless one is intimately familiar with the required behaviors
+ # and side effects.
+ def gets(sep_string=$/)
+ return read(nil) unless sep_string
+ line = ""
+ paragraph = false
+ if sep_string == ""
+ sep_string = "\n\n"
+ paragraph = true
+ end
+ sep = sep_string.dup
+ position = @_iom_pos
+ while (char = getc)
+ if paragraph && line.empty?
+ if char == ?\n
+ next
+ # else
+ # paragraph = false
+ end
+ end
+ if char == sep[0]
+ sep[0] = ""
+ else
+ sep = sep_string.dup
+ end
+ if sep == ""
+ if paragraph
+ ungetc char
+ else
+ line << char
+ end
+ break
+ end
+ line << char
+ if position && @_iom_pos == position
+ raise IOError, "loop encountered", caller
+ end
+ end
+ line = nil if line == ""
+ if line && respond_to?(:lineno=) && respond_to?(:lineno)
+ self.lineno += 1
+ $. = lineno
+ end
+ $_ = line
+ end
+
+ # This method returns the number of times IO::Readable#gets was called.
+ # The count is reset on calls to IO::Seekable#rewind.
+ def lineno
+ @_iom_lineno ||= 0
+ end
+
+ # This method and +lineno+ must be redefined together, or not at all.
+ def lineno=(num)
+ @_iom_lineno = num
+ end
+
+ # Like IO#read, read up to +length+ bytes and return them, optionally
+ # assigning them to +buffer+ as well.
+ def read(length = nil,buffer = "")
+ raise ArgumentError, "negative length #{length} given", caller if (length||0) < 0
+ return "" if length == 0 && (@_iom_buffer.nil? || @_iom_buffer.length > 0)
+ return (length ? nil : "") if eof
+ return "" if length == 0
+ @_iom_buffer ||= ""
+ if length
+ begin
+ @_iom_buffer << sysread(length-@_iom_buffer.length) if @_iom_buffer.length<length
+ # rescue EOFError
+ end
+ else
+ begin
+ while str = sysread(1024)
+ @_iom_buffer << str
+ end
+ rescue EOFError
+ nil # For coverage
+ end
+ end
+ buffer[0..-1] = @_iom_buffer.slice!(0..(length || 0)-1)
+ @_iom_pos ||= 0
+ @_iom_pos += buffer.length
+ return buffer
+ end
+
+ # See IO#getc. Implemented via #read.
+ def getc
+ read(1).to_s[0]
+ end
+
+ # See IO#ungetc.
+ def ungetc(char)
+ raise IOError, "unread stream", caller unless @_iom_buffer
+ @_iom_buffer[0,0] = char.chr
+ @_iom_pos -= 1
+ nil
+ end
+
+ # See IO#eof.
+ def eof
+ # tell if respond_to?(:tell)
+ @_iom_buffer ||= ""
+ return false unless @_iom_buffer.empty?
+ str = sysread(1)
+ if str
+ @_iom_buffer << str
+ @_iom_buffer.empty?
+ else
+ true
+ end
+ rescue EOFError
+ return true
+ end
+
+ # Reads a character as with IO#getc, but raises an +EOFError+ on end of
+ # file. Implemented via #getc.
+ def readchar()
+ getc or raise EOFError, "end of file reached", caller
+ end
+
+ # Reads a character as with #gets, but raises an +EOFError+ on
+ # end of file. Implemented via #gets.
+ def readline(sep_string = $/)
+ gets(sep_string) or raise EOFError, "end of file reached", caller
+ end
+
+ # See IO#readlines. Implemented via #gets.
+ def readlines(sep_string = $/)
+ array = []
+ line = nil
+ array << line while line = gets(sep_string)
+ array
+ end
+
+ # See IO#each_byte. Implemented via #getc.
+ def each_byte
+ while byte = getc
+ yield byte
+ end
+ self
+ end
+
+ # See IO#each_line. Implemented via #gets.
+ def each_line(sep_string = $/)
+ while line = gets(sep_string)
+ yield line
+ end
+ self
+ end
+
+ alias each each_line
+
+ # See IO#eof?. Implemented via #eof.
+ def eof?
+ eof
+ end
+
+end
+
+# The IO::Writable mixin provides classes with several methods for writing
+# a data stream, similar to those found in the IO class. The methods
+# +syswrite+ and +close_write+ must be provided. Additionally,
+# <tt>closed_write?</tt>, <tt>closed?</tt>, and +close+ are recommended.
+#
+# The following example illustrates the use of IO::Readable, IO::Writable, and
+# IO::Seekable. It wraps around another stream and applies rot13 to the
+# contents.
+#
+# :include:../../test/rot13_filter.rb
+module IO::Writable
+
+ REQUIRED_METHODS = [ :syswrite, :close_write ]
+ include IO::Common
+
+ # See IO#write.
+ def write(string)
+ @_iom_pos ||= 0
+ @_iom_pos += string.to_s.length
+ @_iom_buffer.slice!(0,string.to_s.length) if @_iom_buffer
+ syswrite(string.to_s)
+ end
+
+ # See IO#<<. Implemented via #write.
+ def <<(string)
+ # write(string.respond_to?(:to_int) ? string.to_int.chr : string)
+ write(string)
+ self
+ end
+
+ # See IO#print. Implemented via #write.
+ def print(obj = $_,*args)
+ ([obj]+args).each do |line|
+ write(line + ($\||''))
+ end
+ nil
+ end
+
+ # See IO#puts. Implemented via #write.
+ def puts(obj = "\n",*args)
+ [obj,args].flatten.each do |line|
+ line = "nil" if line.nil?
+ write(line.to_s + (line.to_s[-1] == ?\n ? "" : "\n"))
+ end
+ nil
+ end
+
+ # See IO#printf. Implemented via #write.
+ def printf(first="",*rest)
+ write(sprintf(first,*rest))
+ nil
+ end
+
+ # See IO#putc. Implemented via #write
+ def putc(char)
+ if char.respond_to?(:to_int)
+ write((char.to_int & 0xFF).chr)
+ elsif char.respond_to?(:to_str) && char.to_str.length > 0
+ write(char.to_str[0,1])
+ else
+ raise TypeError, "can't convert #{char.class} to Integer", caller
+ end
+ char
+ end
+
+ # Returns +self+. May be redefined.
+ def flush
+ self
+ end
+
+end
+
+# The IO::Seekable mixin provides classes with several methods for seeking
+# within a data stream, similar to those found in the IO class. The method
+# +sysseek+ must be provided. This method should operate identically to
+# IO#sysseek, seeking to the desired location and returning the final
+# absolute offset. One should also consider optimizing for
+# <tt>sysseek(0,IO::SEEK_CUR)</tt>. This particular call should simply return
+# the position in the stream.
+#
+# For an example implementation, see IO::Writable.
+module IO::Seekable
+
+ REQUIRED_METHODS = [ :sysseek ]
+ include IO::Common
+
+ # See IO#pos. Implemented via #tell.
+ def pos
+ tell
+ end
+
+ # See IO#pos=. Implemented via #seek.
+ def pos=(pos)
+ seek(pos)
+ tell
+ end
+
+ # See IO#rewind. Calls both #seek and IO::Readable#lineno=, if included.
+ def rewind
+ seek(0)
+ self.lineno = 0 if respond_to?(:lineno=)
+ 0
+ end
+
+ # See IO#seek. This method calls #sysseek and only should be overridden in a
+ # class that is taking responsibility for tracking its own position. If this
+ # is the case, the class should also override #seek, as well as
+ # IO::Readable#read, IO::Readable#ungetc, IO::Readable#getc,
+ # IO::Readable#eof, IO::Writable#write, and IO::Writable#putc, if the
+ # respective modules are included.
+ def seek(amount, whence = IO::SEEK_SET)
+ if whence == IO::SEEK_CUR && @_iom_buffer
+ amount -= @_iom_buffer.length
+ end
+ @_iom_pos ||= 0
+ @_iom_pos += @_iom_buffer.length if @_iom_buffer
+ @_iom_buffer = nil if @_iom_buffer
+ @_iom_pos = sysseek(amount, whence)
+ 0
+ end
+
+ # See IO#tell. See #seek for information on overriding this method.
+ def tell
+ @_iom_pos ||= 0
+ end
+
+end
+
+# The IO::Closable mixin works with IO::Readable, IO::Writable, and
+# IO::Seekable. It provides #closed_read?, #closed_write?, #close_read, and
+# #close_write methods, and wraps the required methods for the aforementioned
+# modules such that they raise an exception if applied to a closed object.
+# You must include _at_ _least_ one of IO::Readable or IO::Writable for this
+# mixin to be useful.
+#
+# This mixin is highly experimental. It currently works by trapping
+# method_added and wrapping the newly defined method.
+module IO::Closable
+ WRAPPED_READ_METHODS = [ :sysread, :getc, :ungetc, :eof, :read, :gets ]
+ WRAPPED_WRITE_METHODS = [ :syswrite, :putc, :write ]
+ WRAPPED_BOTH_METHODS = [ :sysseek, :tell, :seek, :reopen, :pos, :pos= ]
+ WRAPPED_METHODS = WRAPPED_READ_METHODS + WRAPPED_WRITE_METHODS + WRAPPED_BOTH_METHODS
+
+ # Either #close or #close_read was called.
+ def closed_read?
+ !respond_to?(:sysread) || !!@_closed_read
+ end
+
+ # Either #close or #close_write was called
+ def closed_write?
+ !respond_to?(:syswrite) || !!@_closed_write
+ end
+
+ # Object is closed for both reading and writing
+ def closed?
+ closed_read? && closed_write?
+ end
+
+ # Wrap an existing method in with a prerequisite that the file must not be
+ # closed.
+ #
+ # wrap_method_for_close(:printf, :closed_write?)
+ def self.wrap_method_for_close(method,condition = :closed?) #:nodoc:
+ class_eval(<<-EOF,__FILE__,__LINE__)
+ def with_io_sneakiness_do_#{method}(*args,&block)
+ raise IOError, "stream closed", caller if #{condition}
+ send(:without_io_sneakiness_do_#{method},*args,&block)
+ end
+ EOF
+ private "with_io_sneakiness_do_#{method}"
+ end
+
+ WRAPPED_READ_METHODS.each do |method|
+ wrap_method_for_close(method,:closed_read?)
+ end
+
+ WRAPPED_WRITE_METHODS.each do |method|
+ wrap_method_for_close(method,:closed_write?)
+ end
+
+ WRAPPED_BOTH_METHODS.each do |method|
+ wrap_method_for_close(method,:closed?)
+ end
+
+ def with_io_sneakiness_do_reopen(*args, &block) #:nodoc:
+ @_closed_read = nil
+ @_closed_write = nil
+ without_io_sneakiness_do_reopen(*args,&block)
+ end
+
+ # After this method is called, future read operations will fail, and
+ # #closed_read? will read return true. If this method is redefined, it
+ # will be transparently wrapped to preserve this behavior.
+ def close_read(*args,&block)
+ closed_io_error if closed_read?
+ @_closed_read = true
+ without_io_sneakiness_do_close_read(*args,&block) if respond_to?(:without_io_sneakiness_do_close_read)
+ without_io_sneakiness_do_close(*args,&block) if closed_write? && respond_to?(:without_io_sneakiness_do_close)
+ end
+
+ # After this method is called, future write operations will fail, and
+ # #closed_write? will write return true. If this method is redefined, it
+ # will be transparently wrapped to preserve this behavior.
+ def close_write(*args,&block)
+ closed_io_error if closed_write?
+ @_closed_write = true
+ without_io_sneakiness_do_close_write(*args,&block) if respond_to?(:without_io_sneakiness_do_close_write)
+ without_io_sneakiness_do_close(*args,&block) if closed_read? && respond_to?(:without_io_sneakiness_do_close)
+ end
+
+ # Calls both close_read and close_write.
+ def close(*args,&block)
+ closed_io_error if closed?
+ close_read(*args,&block) unless closed_read?
+ close_write(*args,&block) unless closed_write?
+ end
+
+ [:close_read, :close_write, :close].each do |method|
+ alias_method("with_io_sneakiness_do_#{method}", method)
+ end
+
+
+ def self.included(base) #:nodoc:
+ # p base.instance_methods.sort
+ WRAPPED_METHODS.each do |method|
+ if method_defined?(method) && !private_method_defined?(without) #&& private_method_defined?(with)
+ base.send(:alias_method, without, method)
+ base.send(:alias_method, method, with)
+ base.send(:private, with, without)
+ base.send(:public, method)
+ end
+ end
+ ::IO::Sneakiness.extend_into(base)
+end
+
+ private
+ def closed_io_error
+ raise IOError, "stream closed", caller[1..-1]
+ end
+
+end
+
+# The IO::Openable mixin is a set of _class_ methods concerning opening a
+# stream. As such, it should be +extend+ed, not +include+d into a class.
+#
+# class MyIO
+# include IO::Readable
+# include IO::Writable
+# include IO::Seekable
+# extend IO::Openable
+# # ...
+# end
+module IO::Openable
+ # Currently the only method, this method creates a new object, and yields
+ # it if a block is given, in a manner similar to IO::open.
+ def open(*args)
+ io = new(*args)
+ if block_given?
+ begin
+ yield io
+ ensure
+ io.close
+ end
+ else
+ io
+ end
+ end
+end
+
+# The IO::Editable mixin allows for full emulation of the IO class by
+# including IO::Readable, IO::Writable, IO::Seekable, and IO::Closable. The
+# following is a partial implementation of a looped IO class which writes to
+# its own input.
+#
+# :include:../../test/io_loop.rb
+module IO::Editable
+ REQUIRED_METHODS = IO::Readable::REQUIRED_METHODS + IO::Writable::REQUIRED_METHODS + IO::Seekable::REQUIRED_METHODS
+ if false # for rdoc
+ include Readable
+ include Writable
+ include Seekable
+ include Closable
+ end
+
+ # Adds an +open+ class method which acts like IO::open.
+ def self.included(base)
+ unless base.respond_to?(:open)
+ base.extend(IO::Openable)
+ [ IO::Readable, IO::Writable, IO::Seekable, IO::Closable ].each do |mod|
+ base.send(:include,mod)
+ # mod.send(:included,base)
+ end
+ end
+ super
+ end
+end
+
+# We nest these in IO because otherwise, :nodoc: is ignored.
+class IO #:nodoc:
+
+ MIXINS_VERSION = '0.3'
+ module Sneakiness #:nodoc:
+ def method_added(id)
+ method = id.id2name
+ with = "with_io_sneakiness_do_#{method}"
+ without = "without_io_sneakiness_do_#{method}"
+ if !@io_sneakiness_disabled && (method_defined?(with) || private_method_defined?(with))
+ alias_method without, method
+ disable_sneakiness do
+ alias_method method, with
+ private with, without
+ public method
+ end
+ end
+ method_added_without_io_sneakiness(method)
+ end
+
+ def self.extend_into(base)
+ unless base.respond_to?(:method_added_without_io_sneakiness)
+ class << base
+ alias_method :method_added_without_io_sneakiness, :method_added
+ end
+ base.extend(self)
+ end
+ end
+
+ protected
+ def disable_sneakiness
+ old_crit = Thread.critical
+ Thread.critical = true
+ @io_sneakiness_disabled = true
+ yield
+ ensure
+ @io_sneakiness_disabled = false
+ Thread.critical = old_crit if Thread.critical != old_crit
+ end
+
+ end
+
+ # Deprecated.
+ module Simple #:nodoc:
+ include IO::Editable
+
+ def sysread(length)
+ return "" if length == 0
+ @_simple_buffer ||= ""
+ while @_simple_buffer.length < length && chunk = (readchunk rescue nil)
+ break if chunk == ""
+ @_simple_buffer << chunk
+ end
+ out = @_simple_buffer.slice!(0,length)
+ if out.length == 0
+ raise EOFError, "end of file reached", caller
+ else
+ out
+ end
+ end
+
+ end
+end
+
+# end
projects / ruby-io-mixins.git / commitdiff