rio 0.3.2 → 0.3.3

data/ChangeLog

@@ -1,4 +1,53 @@
 ------------------------------------------------------------------------
+r79 | kit | 2005-08-19 17:01:44 -0700 (Fri, 19 Aug 2005) | 1 line
+Changed paths:
+   M /rio/trunk/doc/ANNOUNCE
+   M /rio/trunk/doc/RELEASE_NOTES
+   A /rio/trunk/ex/passwd_report.rb
+   M /rio/trunk/lib/rio/version.rb
+
+Prepare for release
+------------------------------------------------------------------------
+r78 | kit | 2005-08-19 15:56:33 -0700 (Fri, 19 Aug 2005) | 1 line
+Changed paths:
+   M /rio/trunk/lib/rio/doc/INTRO.rb
+   M /rio/trunk/lib/rio/ext/csv.rb
+   M /rio/trunk/lib/rio/if/csv.rb
+   M /rio/trunk/lib/rio/if/internal.rb
+   M /rio/trunk/lib/rio.rb
+   M /rio/trunk/test/tc/all.rb
+   A /rio/trunk/test/tc/csv2.rb
+   A /rio/trunk/test/tc/csv_columns.rb
+   A /rio/trunk/test/tc/csvutil.rb
+   M /rio/trunk/test/tc/tempfile.rb
+
+CSV support and documentation for same
+------------------------------------------------------------------------
+r77 | kit | 2005-08-17 13:03:03 -0700 (Wed, 17 Aug 2005) | 1 line
+Changed paths:
+   M /rio/trunk/doc/ANNOUNCE
+   M /rio/trunk/ex/colx.rb
+   M /rio/trunk/lib/rio/argv.rb
+   M /rio/trunk/lib/rio/base.rb
+   M /rio/trunk/lib/rio/factory.rb
+   A /rio/trunk/lib/rio/if/csv.rb
+   M /rio/trunk/lib/rio/if/dir.rb
+   M /rio/trunk/lib/rio/if/fileordir.rb
+   M /rio/trunk/lib/rio/if/grande.rb
+   M /rio/trunk/lib/rio/if/internal.rb
+   M /rio/trunk/lib/rio/if/methods.rb
+   A /rio/trunk/lib/rio/if/string.rb
+   A /rio/trunk/lib/rio/if/temp.rb
+   M /rio/trunk/lib/rio/if.rb
+   M /rio/trunk/lib/rio/scheme/temp.rb
+   M /rio/trunk/lib/rio.rb
+   M /rio/trunk/test/tc/copy-from.rb
+   M /rio/trunk/test/tc/ext.rb
+   M /rio/trunk/test/tc/methods.rb
+   M /rio/trunk/test/tc/tempfile.rb
+
+documentation
+------------------------------------------------------------------------
 r74 | kit | 2005-08-16 11:00:55 -0700 (Tue, 16 Aug 2005) | 1 line
 Changed paths:
    M /rio/trunk/doc/ANNOUNCE

data/VERSION

@@ -1 +1 @@
-0.3.2
+0.3.3

data/doc/ANNOUNCE

@@ -10,7 +10,24 @@ provided by IO, File, and Dir to an appropriate object, Rio provides
 a "grande" interface that allows many common application-level I/O and
 file-system tasks to be expressed succinctly.
 
-
+== New for version 0.3.3
+* Expanded support and documentation for CSV files
+  Examples:
+  * Copy, changing the separator to a semicolon
+     rio('comma.csv').csv > rio('semicolon.csv').csv(';')
+  * Iterate through a file with each line parsed into an array
+     rio('afile.csv').csv { |array_of_fields| ...}
+  * Create an array of arrays of selected fields
+     array_of_arrays = rio('afile.csv').csv.columns(1..3,7).to_a
+  * Create a tab separated file of accounts in a UNIX passwd file,
+    listing only the username, uid, and realname fields
+     rio('/etc/passwd').csv(':').columns(0,2,4) > rio('report).csv("\t")
+
+Project:: http://rubyforge.org/projects/rio/
+Documentation:: http://rio.rubyforge.org/
+Bugs:: http://rubyforge.org/tracker/?group_id=821
+
+         
 == New for version 0.3.2
 
 * Based on a suggestion by Wybo Decker and code attributed to Nobu Nokada, 
@@ -82,6 +99,6 @@ Copyright (c) 2005, Christopher Kleckner. All rights reserved
 
 == License
 Rio is released under the GNU General Public License
-(http://www.gnu.org/licenses/gp l.html)
+(http://www.gnu.org/licenses/gpl.html)
 
 -Christopher Kleckner 

data/doc/RELEASE_NOTES

@@ -24,6 +24,23 @@ Suggested Reading
 * RIO::Doc::HOWTO
 * RIO::Rio
 
+== New for version 0.3.3
+* Expanded support and documentation for CSV files
+  Examples:
+  * Copy, changing the separator to a semicolon
+     rio('comma.csv').csv > rio('semicolon.csv').csv(';')
+  * Iterate through a file with each line parsed into an array
+     rio('afile.csv').csv { |array_of_fields| ...}
+  * Create an array of arrays of selected fields
+     array_of_arrays = rio('afile.csv').csv.columns(1..3,7).to_a
+  * Create a tab separated file of accounts in a UNIX passwd file,
+    listing only the username, uid, and realname fields
+     rio('/etc/passwd').csv(':').columns(0,2,4) > rio('report).csv("\t")
+
+Project:: http://rubyforge.org/projects/rio/
+Documentation:: http://rio.rubyforge.org/
+Bugs:: http://rubyforge.org/tracker/?group_id=821
+
 == New for version 0.3.2
 
 * Based on a suggestion by Wybo Decker and code attributed to Nobu Nokada, 

data/ex/colx.rb

@@ -1,6 +1,8 @@
 #!/usr/bin/env ruby
 require 'rio'
 
-rio('ex/rgb.txt.gz').gzip.lines(/^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S.+)/) do |line,ma| 
+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])
 end

data/ex/passwd_report.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+require 'rio'
+
+rio('/etc/passwd').csv(':').columns(0,2,4) > rio(?-).csv("\t")
+
+__END__
+
+From Seattle,Wa
+Take I-90 east, take exit 143 Gorge Amphitheatre. Follow amphitheatre signs approximately 6 miles.
+
+206-242-8738
+3:00

data/lib/rio.rb

@@ -111,20 +111,20 @@ module RIO
     end
 
     # returns the Rio#fspath, which is the path for the Rio on the underlying filesystem
-    def to_s(*args) target.to_s(*args) end
-
+    def to_s() target.to_s end
+    alias :to_str :to_s
     def dup
       self.class.new(self.to_s)
     end
 
-    def method_missing(sym,*args,&block) #:nodoc:
-      #p callstr('method_missing',sym,*args)
+  def method_missing(sym,*args,&block) #:nodoc:
+    #p callstr('method_missing',sym,*args)
 
-      result = target.__send__(sym,*args,&block)
-      return result unless result.kind_of? State::Base and result.equal? target
+    result = target.__send__(sym,*args,&block)
+    return result unless result.kind_of? State::Base and result.equal? target
 
-      self
-    end
+    self
+  end
 
     def inspect()
       cl = self.class.to_s[5..-1]
@@ -138,7 +138,6 @@ module RIO
       require 'rio/if'
       include Enumerable
     end
-
     protected
 
     def target() @state.target end

data/lib/rio/argv.rb

@@ -39,10 +39,6 @@
 require 'rio'
 
 module RIO
-  def argv()
-    ::ARGV.map { |path| rio(path) }
-  end
-  module_function :argv
   def ARGV()
     ::ARGV.map { |path| rio(path) }
   end

data/lib/rio/base.rb

@@ -44,6 +44,7 @@ module RIO
     KEEPSYM = {
       '__id__' => true,
       '__send__' => true,
+      'send' => true,
       'class' => true, 
       'kind_of?' => true, 
       'instance_of?' => true, 
@@ -52,7 +53,8 @@ module RIO
       'object_id' => true,
       'dup' => true,
       'clone' => true,
-
+      'nil?'  => true,
+#      'to_s'  => true,
     }.freeze
     instance_methods.each { |m| undef_method m unless KEEPSYM[m] }
   end

data/lib/rio/doc/INTRO.rb

@@ -43,7 +43,7 @@ module Doc
 
 Rio is a convenience class wrapping much of the functionality of 
 IO, File, Dir, Pathname, FileUtils,
-Tempfile, StringIO, and OpenURI and uses Zlib, and CSV 
+Tempfile, StringIO, and OpenURI and uses Zlib, and CSV
 to extend that functionality using a simple consistent interface. 
 Most of the instance methods of IO, File and Dir are simply forwarded to the appropriate handle
 to provide identical functionality. Rio also provides a "grande" interface that 
@@ -699,6 +699,79 @@ A Rio can also be opened explicitly using Rio#open. +open+ takes one parameter,
 This also will override all of Rio's automatic mode selection.
 
 
+==== CSV mode
+
+Rio uses the CSV class from the Ruby standard library to provide support for reading
+and writing comma-separated-value files. Normally using <tt>(no)records</tt> is
+identical to <tt>(no)lines</tt> because while +records+ only selects and does not
+specify the record-type, lines is the default, and so
+ rio('afile').records(1..2)
+effectively means
+ rio('afile').lines.records(1..2)
+
+The CSV extension distingishes between items selected using Rio#records and those 
+selected using Rio#lines. Rio returns records parsed into Arrays by the CSV
+library when +records+ is used, and returns Strings as normal when +lines+ is used.
++records+ is the default
+So:
+ rio('f.csv').puts!(["h0,h1","f0,f1"])                 
+
+ rio('f.csv').csv.records[]    #==>[["h0", "h1"], ["f0", "f1"]]
+ rio('f.csv').csv[]            #==> same thing
+ rio('f.csv').csv.lines[]      #==>["h0,h1\n", "f0,f1\n"]
+ rio('f.csv').csv.records[0]   #==>[["h0", "h1"]]
+ rio('f.csv').csv[0]           #==> same thing
+ rio('f.csv').csv.lines[0]     #==>["h0,h1\n"]
+ rio('f.csv').csv.norecords[0] #==>[["f0", "f1"]]
+ rio('f.csv').csv.nolines[0]   #==>["f0,f1\n"]
+
+This distinction, of course, applies equally when using the copy operators and +each+
+ rio('f.csv').csv[0] > rio('out').csv # out contains "f0,f1\n"
+ rio('f.csv').csv { |array_of_fields| ... }
+
+Notice that +csv+ mode is called on both the input and output Rios. The +csv+ on the 
+'out' Rio causes it to treat an array written to it as an array of records which is
+converted into CSV format before writing. Without the +csv+, the output would be
+written as if Array#to_s on [["f0","f1"]] had been called
+ rio('f.csv').csv[0] > rio('out') # out contains "f0f1"
+
+The String representing a record that is returned when using +lines+ is extended with a
++to_a+ method which will parse it into an array of fields. Likewise the Array returned
+when a record is returned using +records+ is extended with a modified +to_s+ which
+treats it as an array CSV fields, rather than just an array of strings.
+
+ array_of_lines = rio('f.csv').csv.lines[1]      #==>["f0,f1\n"]
+ array_of_records = rio('f.csv').csv.records[1]  #==>[["f0", "f1"]]
+
+ array_of_lines[0].to_a                          #==>["f0", "f1"]
+ array_of_records[0].to_s                        #==>"f0,f1"
+
+Rio#csv takes two optional parameters, which are passed on to the CSV library. They are
+the +field_separator+ and the +record_separator+. 
+ rio('semisep').puts!(["h0;h1","f0;f1"])                 
+
+ rio('semisep').csv(';').to_a  #==>[["h0", "h1"], ["f0", "f1"]]
+
+These are specified independently on the source and destination when using the
+copy operators, So:
+
+ rio('semisep').csv(';') > rio('colonsep').csv(':')
+ rio('colonsep').slurp  #==>"h0:h1\nf0:f1\n"
+
+Rio provides two methods for selecting fields from CSV records in a manner similar
+to that provided for selecting lines -- Rio#columns and Rio#nocolumns.
+
+ rio('f.csv').puts!(["h0,h1,h2,h3","f0,f1,f2,f3"])
+
+ rio('f.csv').csv.columns(0).to_a       #==>[["h0"], ["f0"]]
+ rio('f.csv').csv.nocolumns(0).to_a     #==>[["h1", "h2", "h3"], ["f1", "f2", "f3"]]
+ rio('f.csv').csv.columns(1..2).to_a    #==>[["h1", "h2"], ["f1", "f2"]]
+ rio('f.csv').csv.nocolumns(1..2).to_a  #==>[["h0", "h3"], ["f0", "f3"]]
+
+Rio#columns can, of course be used with the +each+ and the copy operators:
+
+ rio('f.csv').csv.columns(0..1) > rio('out').csv
+ rio('out').slurp  #==>"h0,h1\nf0,f1\n"
 
 
 ---

data/lib/rio/ext/csv.rb

@@ -59,6 +59,11 @@ module RIO
           cx['col_args'] = ranges.flatten
           cxx('columns',true,&block)
         end
+        def nocolumns(*ranges,&block)
+          @cnames = nil
+          cx['nocol_args'] = ranges.flatten
+          cxx('columns',true,&block)
+        end
         def columns?() 
           cxx?('columns') 
         end 
@@ -109,12 +114,36 @@ module RIO
         private
 
         def trim(fields)
-          return fields if cx['col_args'].nil? or cx['col_args'].empty?
+          ycols = cx['col_args']
+          ncols = cx['nocol_args']
+          return [] if ncols and ncols.empty?
+          if ycols.nil? and ncols.nil?
+            return fields
+          end
+          ncols = [] if ncols.nil?
+          ycols = [(0...fields.size)] if ycols.nil? or ycols.empty?
+          cols = []
+          fields.each_index { |i|
+            yes = nil
+            no = nil
+            ycols.each { |yc|
+              if yc === i
+                yes = true
+                break
+              end
+            }
+            ncols.each { |nc|
+              if nc === i
+                no = true
+                break
+              end
+            }
+
+            cols << i if yes and !no
+          }
           tfields = []
-          fields.each_index do |i|
-            cx['col_args'].each do |rng|
-              tfields << fields[i] if rng === i
-            end
+          cols.each do |i|
+            tfields << fields[i]
           end
           tfields
         end

data/lib/rio/factory.rb

@@ -173,8 +173,8 @@ module RIO
 
       'Temp::Reset' => 'rio/scheme/temp',
       'Temp::Stream::Open' => 'rio/scheme/temp',
-      'Temp::Stream::Close' => 'rio/scheme/temp',
-      'Temp::Stream::InOut' => 'rio/scheme/temp',
+      #'Temp::Stream::Close' => 'rio/scheme/temp',
+      #'Temp::Stream::InOut' => 'rio/scheme/temp',
 
       'FTP::State::Dir' => 'rio/ftp',
       'FTP::State::File' => 'rio/ftp',

data/lib/rio/if.rb

@@ -51,3 +51,6 @@ require 'rio/if/fileordir'
 require 'rio/if/file'
 require 'rio/if/dir'
 require 'rio/if/stream'
+require 'rio/if/temp'
+require 'rio/if/csv'
+require 'rio/if/string'

data/lib/rio/if/csv.rb

@@ -0,0 +1,76 @@
+#--
+# =============================================================================== 
+# 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 Rio
+    #def file() target.file end
+    #def dir() target.dir end
+    
+    # Puts a Rio in CSV mode and sets the field and record separators.
+    # In csv mode selecting with Rio#records will cause each line
+    # read to be parsed into a line with the CSV standard library.
+    # Specifying using Rio#lines to select will return unparsed strings
+    # as normal.
+    #
+    #  # copy a csv file, changing the field separator
+    #  rio('afile.csv').csv > rio('afile_semicolons.csv').csv(';')
+    #
+    # CSV mode also adds two methods Rio#columns and Rio#nocolumns which 
+    # allows selecting columns by column index using Fixnums or Ranges
+    # in a way similar to how lines are selected.
+    #
+    #  # iterate through every line but only get the first three columns
+    #  rio("afile.csv").csv.columns(0..2) { |array_of_fields| ... }
+    #
+    #  # iterate through every line but skip the columns 2 and 3 through 5
+    #  rio("afile.csv").csv.nocolumns(2,3..5) { |array_of_fields| ... }
+    #
+    #  # an array containg all but the first line returning columns 5,6 and 7
+    #  rio("afile.csv").csv.columns(5..7).nolines[0]
+    #
+    # See RIO::Doc::INTRO for complete documentation on csv mode.
+    def csv(field_separator=',',record_separator=nil,&block) 
+      target.csv(field_separator,record_separator,&block); 
+      self 
+    end
+    # Select columns from a CSV file. See Rio#csv and RIO::Doc::INTRO.
+    def columns(*ranges,&block) target.columns(*ranges,&block); self end
+    # Reject columns from a CSV file. See Rio#csv and RIO::Doc::INTRO.
+    def nocolumns(*ranges,&block) target.nocolumns(*ranges,&block); self end
+  end
+end
+