rio 0.3.1

data/lib/rio/arrayio.rb

@@ -0,0 +1,199 @@
+#--
+# =============================================================================== 
+# Copyright (c) 2005, 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
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# Rio is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Rio; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+# =============================================================================== 
+#++
+#
+# To create the documentation for Rio run the command
+#  rake rdoc
+# from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
+#
+# Suggested Reading
+# * RIO::Doc::SYNOPSIS
+# * RIO::Doc::INTRO
+# * RIO::Doc::HOWTO
+# * RIO::Rio
+#
+# <b>Rio is pre-alpha software. 
+# The documented interface and behavior is subject to change without notice.</b>
+
+
+
+module RIO
+  class NotSupportedException < ArgumentError  #:nodoc: all
+    def self.emsg(fname,obj)
+      "#{fname}() is not supported for #{obj.class} objects" 
+    end
+
+  end
+  class AIOMode #:nodoc: all
+    def initialize(mode_string)
+      @str = mode_string
+    end
+    def to_s() @str end
+    def can_write?
+      @str =~ /^[aw]/ or @str =~ /\+/
+    end
+    def can_read?
+      @str =~ /^r/ or @str =~ /\+/
+    end
+    def appends?
+      @str =~ /^a/
+    end
+    def =~(re)
+      re =~ @str
+    end
+  end
+  class AIOH  #:nodoc: all
+    attr_accessor :array,:lineno,:mode,:ln
+    def initialize(a,m)
+      @array = a || []
+      @mode = AIOMode.new(m)
+      @lineno = 0
+      @ln = 0
+    end
+  end
+
+  class ArrayIO  #:nodoc: all
+    def initialize(a=nil,m='r')
+#      p "#{callstr('initialize',a,m)} hnd=#{@hnd.inspect}"
+      raise ArgumentError,"ArrayIO.new() requires an array but got #{a.inspect}" unless a.kind_of?(::Array)
+      a = a.array if a.kind_of?(ArrayIO)
+      @hnd = AIOH.new(a,m)
+      _open(@hnd.mode)
+    end
+    def array() @hnd.array end
+    def array=(a) @hnd.array = a end
+    def lineno() @hnd.lineno end
+    def lineno=(a) @hnd.lineno = a end
+    def to_a() array.dup end
+
+    def _open(m)
+      @hnd.mode = AIOMode.new(m.to_s)
+      @hnd.ln = 0
+#      p m.to_s,@hnd.mode.to_s,@hnd.array
+      @hnd.array.clear if @hnd.mode.to_s =~ /^w/
+      @hnd.ln = @hnd.array.size if @hnd.mode.to_s =~ /^a/
+    end
+    def self.open(a=nil,m='r',&block)
+      rtn = io = self.class.new(a,m)
+      if block_given?
+        rtn = yield(io)
+        io.close
+      end
+      rtn
+    end
+    def fileno() nil end
+    def flush() nil end
+    def fsync() nil end
+    def isatty() false end
+    def tty?() false end
+    def pos() @hnd.ln end
+    def pos=(n) @hnd.ln = n end
+
+    def readchar() raise NotSupportedException,NotSupportedException.emsg('readchar',self) end
+    def read() raise NotSupportedException,NotSupportedException.emsg('read',self) end
+    def getc() raise NotSupportedException,NotSupportedException.emsg('getc',self) end
+
+    def closed?
+      @hnd.ln.nil?
+    end
+    def close_read
+      @hnd.ln = @hnd.lineno = nil
+    end
+    def close_write
+      @hnd.ln = nil
+    end
+    def close
+      close_read
+      close_write
+    end
+    def eof?()
+      raise IOError,"ArrayIO is not open for reading" unless @hnd.mode.can_read?
+      @hnd.ln >= @hnd.array.size
+    end
+    def each_line(sep_string=$/,&block) 
+      while line = gets(sep_string)
+        yield(line)
+      end
+      self
+    end
+    alias each each_line
+    def gets(sep_string=$/)
+      raise IOError,"ArrayIO is not open for reading" unless @hnd.mode.can_read?
+      return nil if @hnd.ln >= @hnd.array.size
+      str = nil
+      if sep_string.nil?
+        str = @hnd.array[@hnd.ln...@hnd.array.size].join('')
+        @hnd.lineno += @hnd.array.size - @hnd.ln
+        @hnd.ln = @hnd.array.size
+      else
+        str = @hnd.array[@hnd.ln]
+        @hnd.lineno += 1
+        @hnd.ln += 1
+      end
+      $_ = str
+    end
+    def readline(sep_string=$/)
+      raise EOFError unless str = gets(sep_string)
+      str
+    end
+    
+    def readlines(sep_string=$/)
+      ary = []
+      until eof?
+        ary.push(gets(sep_string))
+      end
+      ary
+    end
+    def rewind
+      @hnd.ln = @hnd.lineno = 0
+    end
+    def print(*objs)
+      raise IOError,"ArrayIO is not open for writing" unless @hnd.mode.can_write?
+      if objs.empty?
+        @hnd.array[@hnd.ln] = $_
+        @hnd.ln += 1
+      else
+        for obj in objs
+          @hnd.array[@hnd.ln] = obj.to_s
+          @hnd.ln += 1
+        end
+      end
+      nil
+    end
+    def <<(obj)
+      print(obj.to_s)
+      self
+    end
+    def puts(*objs)
+      for obj in objs
+        print(obj.to_s.chomp + $/)
+      end
+    end
+    def printf(fmt,*args)
+      print(sprintf(fmt,*args))
+    end
+    def callstr(func,*args)
+      self.class.to_s+'['+self.to_s+']'+'.'+func.to_s+'('+args.join(',')+')'
+    end
+    
+  end
+end

data/lib/rio/arycopy.rb

@@ -0,0 +1,44 @@
+#--
+# =============================================================================== 
+# Copyright (c) 2005, 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
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# Rio is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Rio; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+# =============================================================================== 
+#++
+#
+# To create the documentation for Rio run the command
+#  rake rdoc
+# from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
+#
+# Suggested Reading
+# * RIO::Doc::SYNOPSIS
+# * RIO::Doc::INTRO
+# * RIO::Doc::HOWTO
+# * RIO::Rio
+#
+# <b>Rio is pre-alpha software. 
+# The documented interface and behavior is subject to change without notice.</b>
+
+
+module RIO
+  module AryCopy #:nodoc: all
+    def >>(dest)
+      rio(?$) << self >> dest
+    end
+  end
+end

data/lib/rio/assert.rb

@@ -0,0 +1,115 @@
+#--
+# =============================================================================== 
+# Copyright (c) 2005, 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
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# Rio is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Rio; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+# =============================================================================== 
+#++
+#
+# To create the documentation for Rio run the command
+#  rake rdoc
+# from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
+#
+# Suggested Reading
+# * RIO::Doc::SYNOPSIS
+# * RIO::Doc::INTRO
+# * RIO::Doc::HOWTO
+# * RIO::Rio
+#
+# <b>Rio is pre-alpha software. 
+# The documented interface and behavior is subject to change without notice.</b>
+
+
+#!/usr/bin/env ruby
+
+require 'rio/kernel'
+module RIO
+  module Assert #:nodoc: all
+    def ok(a,b,msg=nil)
+      puts "PASS" + (msg.nil? ? "" : ": #{msg}")
+    end
+    def nok(a,b,msg=nil)
+      puts "FAIL" + (msg.nil? ? "" : ": #{msg}")
+      puts "   exp: #{a.inspect}"
+      puts "   was: #{b.inspect}"
+    end
+    
+    def assert(a,msg=nil)
+      assert_equal(true,a,msg)
+    end
+    def assert_equal(a,b,msg=nil)
+      if a == b
+        ok(a,b,msg)
+      else
+        nok(a,b,msg)
+      end
+    end
+    def assert_case_equal(a,b,msg=nil)
+      if a == b
+        ok(a,b,msg)
+      else
+        nok(a,b,msg)
+      end
+    end
+    def assert_block(msg=nil)
+      if yield
+        ok(nil,nil,msg)
+      else
+        nok(nil,nil,msg)
+      end
+    end
+      
+    def assert_not_equal(a,b,msg=nil)
+      if a != b
+        ok(a,b,msg)
+      else
+        nok(a,b,msg)
+      end
+    end
+    def assert_nil(a,msg=nil)
+      if a.nil?
+        ok(nil,a)
+      else
+        nok(nil,a)
+      end
+    end
+    def assert_same(a,b,msg=nil)
+      if a.equal? b
+        ok(a,b)
+      else
+        nok(a,b)
+      end
+    end
+    def assert_match(a,b,msg=nil)
+      if a =~ b
+        ok(a,b)
+      else
+        nok(a,b)
+      end
+    end
+    def assert_kind_of(a,b,msg=nil)
+      if b.kind_of?(a)
+        ok(a,b.class)
+      else
+        nok(a,b.class)
+      end
+    end
+    def assert_equal_s(a,b,msg=nil) assert_equal(a.to_s,b.to_s,msg) end
+    def assert_equal_a(a,b,msg=nil) assert_equal(a.sort,b.sort,msg) end
+  end
+end

data/lib/rio/base.rb

@@ -0,0 +1,59 @@
+#--
+# =============================================================================== 
+# Copyright (c) 2005, 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
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# Rio is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Rio; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+# =============================================================================== 
+#++
+#
+# To create the documentation for Rio run the command
+#  rake rdoc
+# from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
+#
+# Suggested Reading
+# * RIO::Doc::SYNOPSIS
+# * RIO::Doc::INTRO
+# * RIO::Doc::HOWTO
+# * RIO::Rio
+#
+# <b>Rio is pre-alpha software. 
+# The documented interface and behavior is subject to change without notice.</b>
+
+
+module RIO
+  class Base < ::Object #:nodoc: all
+#    KIOSYMS = [:gets,:open,:readline,:readlines,
+#               :chop,:chomp!,:chop!,
+#               :to_a,:putc,:puts,:print,:printf,:split,:=~]
+#    @@kernel_cleaned ||= KIOSYMS.each { |sym| undef_method(sym) } 
+    KEEPSYM = {
+      '__id__' => true,
+      '__send__' => true,
+      'class' => true, 
+      'kind_of?' => true, 
+      'instance_of?' => true, 
+      'equal?' => true,
+      'respond_to?' => true,
+      'object_id' => true,
+      'dup' => true,
+      'clone' => true,
+
+    }.freeze
+    instance_methods.each { |m| undef_method m unless KEEPSYM[m] }
+  end
+end

data/lib/rio/constructor.rb

@@ -0,0 +1,183 @@
+#--
+# =============================================================================== 
+# Copyright (c) 2005, 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
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# Rio is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Rio; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+# =============================================================================== 
+#++
+#
+# To create the documentation for Rio run the command
+#  rake rdoc
+# from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
+#
+# Suggested Reading
+# * RIO::Doc::SYNOPSIS
+# * RIO::Doc::INTRO
+# * RIO::Doc::HOWTO
+# * RIO::Rio
+#
+# <b>Rio is pre-alpha software. 
+# The documented interface and behavior is subject to change without notice.</b>
+
+#
+
+require 'rio'
+
+module RIO
+  # Rio Constructor 
+  #
+  # For purposes of discussion, we divide Rios into two catagories, those that have a path
+  # and those that don't.
+  #
+  # ==== Creating a Rio that has a path
+  #
+  # To create a Rio that has a path the arguments to +rio+ may be:
+  #
+  # * a string representing the entire path. The separator used for Rios is as specified in RFC1738 ('/').
+  #    rio('adir/afile')
+  # * a string representing a fully qualified +file+ URL as per RFC1738
+  #    rio('file:///atopleveldir/adir/afile')
+  # * a +URI+ object representing a +file+ or generic +URL+
+  #    rio(URI('adir/afile'))
+  # * the components of a path as separate arguments
+  #    rio('adir','afile')
+  # * the components of a path as an array of separate arguments
+  #    rio(%w/adir afile/)
+  # * another Rio
+  #    another_rio = rio('adir/afile')
+  #    rio(another_rio)
+  # * any object whose +to_s+ method returns one of the above
+  #    rio(Pathname.new('apath'))
+  # * any combination of the above either as separate arguments or as elements of an array,
+  #    another_rio = rio('dir1/dir2')
+  #    auri = URI('dir4/dir5)
+  #    rio(another_rio,'dir3',auri,'dir6/dir7')
+  #
+  # ===== Creating a Rio that refers to a web page
+  #
+  # To create a Rio that refers to a web page the arguments to +rio+ may be:
+  #
+  # * a string representing a fully qualified +http+ URL
+  #    rio('http://ruby-doc.org/index.html')
+  # * a +URI+ object representing a +http+ +URL+
+  #    rio(URI('http://ruby-doc.org/index.html'))
+  # * either of the above with additional path elements
+  #    rio('http://www.ruby-doc.org/','core','classes/Object.html')
+  #
+  # ===== Creating a Rio that refers to a file or directory on a FTP server
+  #
+  # To create a Rio that refers to a file on a FTP server the arguments to +rio+ may be:
+  #
+  # * a string representing a fully qualified +ftp+ URL
+  #    rio('ftp://user:password@ftp.example.com/afile.tar.gz')
+  # * a +URI+ object representing a +ftp+ +URL+
+  #    rio(URI('ftp://ftp.example.com/afile.tar.gz'))
+  # * either of the above with additional path elements
+  #    rio('ftp://ftp.gnu.org/pub/gnu','emacs','windows','README')
+  #
+  # ==== Creating Rios that do not have a path
+  #
+  # To create a Rio without a path, the first argument to +rio+ is usually a single
+  # character.
+  #
+  # ===== Creating a Rio that refers to a clone of your programs stdin or stdout.
+  # 
+  # <tt>rio(?-)</tt> (mnemonic: '-' is used by some Unix programs to specify stdin or stdout in place of a file)
+  # 
+  # Just as a Rio that refers to a file, does not know whether that file will be opened for reading or
+  # writing until an I/O operation is specified, a <tt>stdio:</tt> Rio does not know whether it will connect
+  # to stdin or stdout until an I/O operation is specified. 
+  #
+  # ===== Creating a Rio that refers to a clone of your programs stderr.
+  #
+  # <tt>rio(?=)</tt> (mnemonic: '-' refers to fileno 1, so '=' refers to fileno 2)
+  #
+  # ===== Creating a Rio that refers to an arbitrary IO object.
+  #
+  #  an_io = ::File.new('afile')
+  #  rio(an_io)
+  #
+  # ===== Creating a Rio that refers to a file descriptor
+  #
+  # <tt>rio(?#,fd)</tt> (mnemonic: a file descriptor is a number '#')
+  #
+  #  an_io = ::File.new('afile')
+  #  fnum = an_io.fileno
+  #  rio(?#,fnum)
+  #
+  # ===== Creating a Rio that refers to a StringIO object
+  #
+  # <tt>rio(?")</tt> (mnemonic: '"' surrounds strings)
+  # * create a Rio that refers to a string that it creates
+  #    rio(?")
+  # * create a Rio that refers to a string of your choosing
+  #    astring = ""
+  #    rio(?",astring)
+  #
+  # ===== Creating a Rio that refers to a Tempfile object
+  #
+  # <tt>rio(??)</tt> (mnemonic: '?' you don't know its name)
+  #  rio(??)
+  #  rio(??,basename='rio',tmpdir=Dir::tmpdir)
+  #
+  # ===== Creating a Rio that refers to an arbitrary TCPSocket
+  #
+  #  rio('tcp:',hostname,port)
+  # or
+  #  rio('tcp://hostname:port')
+  #
+  # ===== Creating a Rio that runs an external program and connects to its stdin and stdout
+  #
+  # <tt>rio(?-,cmd)</tt> (mnemonic: '-' is used by some Unix programs to specify stdin or stdout in place of a file)
+  #
+  # or
+  #
+  # <tt>rio(?`,cmd)</tt> (mnemonic: '`' (backtick) runs an external program in ruby)
+  #
+  # This is Rio's interface to IO#popen
+  def rio(*args,&block)  # :yields: self
+    Rio.rio(*args,&block) 
+  end
+  module_function :rio
+
+  # Create a Rio as with RIO#rio which refers to the current working directory 
+  #  wd = RIO.cwd
+  def cwd(*args,&block)  # :yields: self
+    Rio.new.getwd(*args,&block) 
+  end
+  module_function :cwd
+
+  # Create a Rio as with RIO#rio which refers to a directory at the root of the file system
+  #  tmpdir = RIO.root('tmp') #=> rio('/tmp')
+  def root(*args,&block) # :yields: self
+    Rio.new.rootpath(*args,&block) 
+  end
+  module_function :root
+
+end
+
+if $0 == __FILE__
+  eval DATA.read, nil, $0, __LINE__+4
+end
+
+__END__
+
+puts
+puts("Run the tests that came with the distribution")
+puts("From the distribution directory use 'test/runtests.rb'")
+puts