rio 0.3.3 → 0.3.4

data/doc/RELEASE_NOTES

@@ -1,6 +1,6 @@
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 Rio is pre-alpha software. 
-The documented interface and behavior is subject to change without notice.
+The documented interface and behaviour is subject to change without notice.
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
 === Rio - Ruby I/O Comfort Class
@@ -24,6 +24,75 @@ Suggested Reading
 * RIO::Doc::HOWTO
 * RIO::Rio
 
+== New for version 0.3.4
+* New Grande Selection parameter.
+
+  A major weakness of Rio's selection methods (lines, files, etc.)
+  has always been that it only implemented a logical OR.
+
+   rio('afile').lines(0..10,/Rio/) {...}
+  iterates through lines that are in the range 0..10 OR 
+  contain 'Rio'.
+
+   rio('adir').files(:executable?,'*.rb') {...}
+  iterates through files that are executable OR match '*.rb'
+
+  Selecting files that matched both required using a proc.
+   rio('adir').files(proc{ |f| f.executable? and f.fnmatch?('*.rb')}) {...}
+
+  Rio's grande selection methods will now accept an array of conditions
+  which must all be matched, in order to be selected. A logical AND.
+
+   rio('adir').files([:executable?,'*.rb']) {...}
+  
+  The array, of course, need not be the only paramter. 
+
+   rio('adir').files('*.exe',[:executable?,'*.rb']) {...}
+
+  selects .exe files and .rb files that are executable.
+
+* Renamed some of grande rejection methods. 
+  (based on a suggestion by Gavin Sinclair)
+   nolines => skiplines
+   nofiles => skipfiles
+  etc.
+
+* New skip() grande method
+   rio('afile').skip.lines(/Rio/)       # same as skiplines(/Rio/)
+   rio('afile').lines(/Rio/).skip(0..9) # lines with 'Rio', exclude 
+                                        # the first ten lines
+
+* Alternative syntaxes for creating Rios that have no path.
+
+   rio(?-)          # create a Rio refering to stdio
+   rio(:stdio)      # same thing.
+   rio.stdio        # same thing
+   RIO.stdio        # ditto
+   RIO::Rio.stdio   # once again
+
+* From Pathname added
+  * root?
+  * mountpoint?
+  * realpath
+  * cleanpath
+
+* Removed Rio#slurp in favor of Rio#contents.
+
+
+* Added aliases for the copy operators. (suggested by Dave Burt)
+   * copy_to >
+   * append_to >>
+   * copy_from <
+   * append_from <<
+
+
+* Bug fixes and corrections    
+  
+Project:: http://rubyforge.org/projects/rio/
+Documentation:: http://rio.rubyforge.org/
+Bugs:: http://rubyforge.org/tracker/?group_id=821
+Email:: rio4ruby@rubyforge.org
+
 == New for version 0.3.3
 * Expanded support and documentation for CSV files
   Examples:
@@ -137,7 +206,7 @@ Put the first 100 chomped lines of a gzipped file into an array
  anarray =  rio('afile.gz').gzip[0...100] 
 
 Copy the output of th ps command into an array, skipping the header line and the ps command entry
- rio(?-,'ps -a').nolines(0,/ps$/) > anarray 
+ rio(?-,'ps -a').skiplines(0,/ps$/) > anarray 
 
 Prompt for input and return what was typed
  ans = rio(?-).print("Type Something: ").chomp.gets 

data/ex/colx.rb

@@ -4,5 +4,5 @@ require 'rio'
 RGBFILE = rio(__FILE__).dirname/'rgb.txt.gz'
 
 RGBFILE.gzip.lines(/^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S.+)/) do |line,ma| 
-  printf("#%02x%02x%02x\t%s\n",ma[1],ma[2],ma[3],ma[4])
+  printf("#%02x%02x%02x\t%s\n",*ma[1..4])
 end

data/ex/passwd_report.rb

@@ -1,12 +1,8 @@
-#!/usr/bin/env ruby
+#!/usr/local/bin/ruby
 require 'rio'
 
-rio('/etc/passwd').csv(':').columns(0,2,4) > rio(?-).csv("\t")
-
-__END__
+# Create a tab separated file of accounts in a UNIX passwd file,
+# listing only the username, uid, and realname fields
 
-From Seattle,Wa
-Take I-90 east, take exit 143 Gorge Amphitheatre. Follow amphitheatre signs approximately 6 miles.
+rio('/etc/passwd').csv(':').columns(0,2,4) > rio(?-).csv("\t")
 
-206-242-8738
-3:00

data/ex/riocat

@@ -6,11 +6,11 @@ require 'rio'
 # 
 # explanation:
 #
-# rio('-')
-#   rio('-'): a rio that will be connected to stdin or stdout depending how it is used
+# rio(?-)
+#   rio(?-): a rio that will be connected to stdin or stdout depending how it is used
 #
-# rio('-')
-#   rio('-'): a rio that will be connected to stdin or stdout depending how it is used
+# rio(?-)
+#   rio(?-): a rio that will be connected to stdin or stdout depending how it is used
 #
 # <
 #   <: copy operator indicating rio on left is written to and the rio on the right is read from
@@ -22,7 +22,7 @@ rio(?-) < rio(?-)
 # rio(?-) > rio(?-)
 #
 # this is similar but reads the entire file before writing
-#rio('-').print!( rio('-').slurp )
+#rio(?-).print!( rio(?-).slurp )
 
 
 

data/ex/riogunzip

@@ -24,7 +24,7 @@ rio(?-).gzip > rio(?-)
 # rio(?-) < rio(?-).gzip
 #
 # this is similar, but reads the entire file in before writing it out
-#    rio('-').print!( rio('-').gzip.contents )
+#    rio(?-).print!( rio(?-).gzip.contents )
 #
 #rio(?-).gzip.each_record do |rec|
 #  rio(?-).print(rec)

data/ex/riogzip

@@ -6,19 +6,19 @@ require 'rio'
 # 
 # explanation:
 #
-# rio('-').gzip
-#   rio('-'): a rio that will be connected to stdin or stdout depending how it is used
+# rio(?-).gzip
+#   rio(?-): a rio that will be connected to stdin or stdout depending how it is used
 #   .gzip: filter the input or output through Zlib:Gzip[Reader or Writer]
 #
-# rio('-')
-#   rio('-'): a rio that will be connected to stdin or stdout depending how it is used
+# rio(?-)
+#   rio(?-): a rio that will be connected to stdin or stdout depending how it is used
 #
 # <
 # rio copy operator indicating the direction of data
 
-rio('-').gzip < rio('-')
+rio(?-).gzip < rio(?-)
 
 # 
 # could also be written:
-# rio('-') > rio('-').gzip
+# rio(?-) > rio(?-).gzip
 # 

data/ex/rioprompt.rb

@@ -0,0 +1,6 @@
+#!/usr/local/bin/ruby
+
+require 'rio/prompt'
+
+ans = RIO.prompt("Name: ")
+puts "You typed '#{ans}'"

data/lib/rio.rb

@@ -40,6 +40,7 @@
 require 'rio/version'
 require 'rio/base'
 require 'rio/exception'
+
 require 'extensions/symbol'
 require 'extensions/enumerable'
 require 'extensions/string'
@@ -53,6 +54,7 @@ end
 
 require 'rio/kernel'
 require 'rio/constructor'
+require 'rio/construct'
 
 module RIO
   SEEK_SET = IO::SEEK_SET
@@ -97,19 +99,6 @@ module RIO
       ario
     end
 
-    def open(m,*args,&block) 
-      target.open(m,*args)
-      if block_given?
-        old_closeoncopy,old_closeoneof = closeoncopy?,closeoneof?
-        begin
-          return yield(nocloseoncopy.nocloseoneof)
-        ensure
-          reset.closeoncopy(old_closeoncopy).closeoneof(old_closeoneof)
-        end
-      end
-      self 
-    end
-
     # returns the Rio#fspath, which is the path for the Rio on the underlying filesystem
     def to_s() target.to_s end
     alias :to_str :to_s
@@ -138,6 +127,7 @@ module RIO
       require 'rio/if'
       include Enumerable
     end
+
     protected
 
     def target() @state.target end

data/lib/rio/arycopy.rb

@@ -38,7 +38,7 @@
 module RIO
   module AryCopy #:nodoc: all
     def >>(dest)
-      rio(?$) << self >> dest
+      rio(?") << self >> dest
     end
   end
 end

data/lib/rio/base.rb

@@ -37,10 +37,6 @@
 
 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,
@@ -54,7 +50,7 @@ module RIO
       'dup' => true,
       'clone' => true,
       'nil?'  => true,
-#      'to_s'  => true,
+      'open'  => true,
     }.freeze
     instance_methods.each { |m| undef_method m unless KEEPSYM[m] }
   end

data/lib/rio/construct.rb

@@ -0,0 +1,75 @@
+#--
+# =============================================================================== 
+# 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
+  def strio(*args) rio(:strio,*args) end
+  def stdio(*args) rio(:stdio,*args) end
+  def stderr(*args) rio(:stderr,*args) end
+  def temp(*args)  rio(:temp,*args)  end
+  def tempfile(*args)  rio(:tempfile,*args)  end
+  def tempdir(*args)  rio(:tempdir,*args)  end
+  def tcp(*args)  rio(:tcp,*args)  end
+  def cmdio(*args)  rio(:cmdio,*args)  end
+  def sysio(*args)  rio(:sysio,*args)  end
+  def fd(*args)  rio(:fd,*args)  end
+
+  module_function :strio
+  module_function :stdio
+  module_function :stderr
+  module_function :temp
+  module_function :tempfile
+  module_function :tempdir
+  module_function :tcp
+  module_function :cmdio
+  module_function :sysio
+  module_function :fd
+end
+
+module RIO
+  class Rio
+    def self.strio(*args) rio(:strio,*args) end
+    def self.stdio(*args) rio(:stdio,*args) end
+    def self.stderr(*args) rio(:stderr,*args) end
+    def self.temp(*args)  rio(:temp,*args)  end
+    def self.tempfile(*args)  rio(:tempfile,*args)  end
+    def self.tempdir(*args)  rio(:tempdir,*args)  end
+    def self.tcp(*args)  rio(:tcp,*args)  end
+    def self.cmdio(*args)  rio(:cmdio,*args)  end
+    def self.sysio(*args)  rio(:sysio,*args)  end
+    def self.fd(*args)  rio(:fd,*args)  end
+  end
+end

data/lib/rio/constructor.rb

@@ -92,21 +92,31 @@ module RIO
   #
   # ==== 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.
+  # To create a Rio without a path, the first argument to +rio+ is usually 
+  # either a single character or a symbol.
   #
   # ===== 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)
+  #
+  # <tt>rio(:stdio)</tt>
   # 
   # 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. 
   #
+  # Currently :stdin and :stdout are allowed as synonyms for :stdio. This allows one to write
+  #  rio(:stdout).puts("Hello :stdout")
+  # which is reasonable. It also allows one to write 
+  #  rio(:stdin).puts("Hello :stdin")
+  # which is not reasonable and will be disallowed in future releases.
+  #
   # ===== 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)
   #
+  # <tt>rio(:stderr)</tt>
+  #
   # ===== Creating a Rio that refers to an arbitrary IO object.
   #
   #  an_io = ::File.new('afile')
@@ -114,7 +124,9 @@ module RIO
   #
   # ===== Creating a Rio that refers to a file descriptor
   #
-  # <tt>rio(?#,fd)</tt> (mnemonic: a file descriptor is a number '#')
+  # <tt>rio(?#,file_descriptor)</tt> (mnemonic: a file descriptor is a number '#')
+  #
+  # <tt>rio(:fd,file_descriptor)</tt>
   #
   #  an_io = ::File.new('afile')
   #  fnum = an_io.fileno
@@ -123,15 +135,33 @@ module RIO
   # ===== Creating a Rio that refers to a StringIO object
   #
   # <tt>rio(?")</tt> (mnemonic: '"' surrounds strings)
+  #
+  # <tt>rio(:strio)</tt>
+  #
+  # Alpha note: Should :strio be changed to :stringio, or even :string.
+  # Should more than one be allowed? I am leaning toward :string
+  #
   # * 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
+  # ===== Creating a Rio that refers to a temporary object
+  #
+  # To create a temporary object that will become a file (Tempfile)
+  # or a temporary directory, depending on how it is used.
   #
   # <tt>rio(??)</tt> (mnemonic: '?' you don't know its name)
+  #
+  # <tt>rio(:temp)</tt>
+  #
+  # The following are also supported, to specify file or directory
+  #
+  # <tt>rio(:tempfile)</tt>
+  #
+  # <tt>rio(:tempdir)</tt>
+  # 
   #  rio(??)
   #  rio(??,basename='rio',tmpdir=Dir::tmpdir)
   #
@@ -145,8 +175,6 @@ module RIO
   # or just write to it.
   #
   # To force it to become a directory:
-  #  rio(??).dir
-  # or
   #  rio(??).mkdir
   # or
   #  rio(??).chdir
@@ -154,19 +182,22 @@ module RIO
   #
   # ===== Creating a Rio that refers to an arbitrary TCPSocket
   #
-  #  rio('tcp:',hostname,port)
-  # or
-  #  rio('tcp://hostname:port')
+  # <tt>rio('tcp:',hostname,port)</tt>
+  #
+  # <tt>rio('tcp://hostname:port')</tt>
+  #
+  # <tt>rio(:tcp,hostname,port)</tt>
   #
   # ===== 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)
   #
+  # <tt>rio(:cmdio,cmd)</tt>
+  #
   # This is Rio's interface to IO#popen
+  #
   def rio(*args,&block)  # :yields: self
     Rio.rio(*args,&block) 
   end