rio 0.3.9 → 0.4.0

data/lib/rio/doc/INTRO.rb

@@ -38,15 +38,15 @@ module RIO
 module Doc
 =begin rdoc
 
-= Rio - Ruby I/O Comfort Class
+= Rio - Ruby I/O Facilitator
 
-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 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
-allows many application level IO tasks to be expressed succinctly.
+fa-cil-i-tate:  To make easy or easier [http://www.thefreedictionary.com/facilitate]
+
+Rio is a facade for most of the standard ruby classes that deal with I/O;
+providing a simple, intuitive, succinct interface to the functionality
+provided by IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO, OpenURI
+and others. Rio also provides an application level interface which allows many
+common I/O idioms to be expressed succinctly.
 
 
 Rio functionality can be broadly broken into three categories
@@ -863,7 +863,7 @@ One way to append a string to a file and close it in one line is
 
 Run a cmd that must be opened for read and write
 
- ans = rio(?-,'cat').w!.puts!("Hello Kitty").readlines
+ ans = rio(?-,'cat').w!.puts!("Hello Kitty").readline
 
 The automatic selection of mode can be bypassed entirely using
 IF::RubyIO#mode and IF::FileOrDir#open.
@@ -872,7 +872,7 @@ If a mode is specified using +mode+, the file will still be opened
 automatically, but the mode specified in the +mode+ method will be
 used regardless of whether it makes sense.
 
-A Rio can also be opened explicitly using IF::RubyIO#open. +open+ takes one
+A Rio can also be opened explicitly using IF::FileOrDir#open. +open+ takes one
 parameter, a mode.  This also will override all of Rio's automatic
 mode selection.
 

data/lib/rio/doc/OPTIONAL.rb

@@ -38,16 +38,13 @@ module RIO
 module Doc #:doc:
 =begin rdoc
 
-= Rio - Ruby I/O Comfort Class
-
-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 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
-allows many application level IO tasks to be expressed succinctly.
+= Rio - Ruby I/O Facilitator
 
+Rio is a facade for most of the standard ruby classes that deal with I/O;
+providing a simple, intuitive, succinct interface to the functionality
+provided by IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO, OpenURI
+and others. Rio also provides an application level interface which allows many
+common I/O idioms to be expressed succinctly.
 
 Please read the following first:
 * RIO::Doc::INTRO

data/lib/rio/doc/SYNOPSIS.rb

@@ -49,15 +49,15 @@ module RIO
 module Doc #:doc:
 =begin rdoc
 
-= Rio - Ruby I/O Comfort Class
+= Rio - Ruby I/O Facilitator
 
-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 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
-allows many application level IO tasks to be expressed succinctly.
+fa-cil-i-tate:  To make easy or easier [http://www.thefreedictionary.com/facilitate]
+
+Rio is a facade for most of the standard ruby classes that deal with I/O;
+providing a simple, intuitive, succinct interface to the functionality
+provided by IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO, OpenURI
+and others. Rio also provides an application level interface which allows many
+common I/O idioms to be expressed succinctly.
 
 
 == SYNOPSIS
@@ -66,6 +66,21 @@ For the following assume:
  astring = ""
  anarray = []
 
+Iterate over the .rb files in a directory.
+ rio('adir').files('*.rb') { |entrio| ... }
+
+Return an array of the .rb files in a directory.
+ rio('adir').files['*.rb']
+
+Copy the .rb files in a directory.to another directory.
+ rio('adir').files('*.rb') > rio('another_directory')
+
+Iterate over the .rb files in a directory and its subdirectories.
+ rio('adir').all.files('*.rb') { |entrio| ... }
+
+Return an array of the .rb files in a directory and its subdirectories.
+ rio('adir').all.files['*.rb']
+
 Copy or append a file to a string
  rio('afile') > astring      # copy
  rio('afile') >> astring     # append
@@ -85,18 +100,39 @@ Copy or append a file to another file
 Copy a file to a directory
  rio('adir') << rio('afile')
 
-Copy a directory structure to another directory
+Copy a directory to another directory
  rio('adir') >> rio('another_directory')
 
 Copy a web-page to a file
  rio('http://rubydoc.org/') > rio('afile')
 
+Read a web-page into a string
+ astring = rio('http://rubydoc.org/').read
+
 Ways to get the chomped lines of a file into an array
  anarray = rio('afile').chomp[]         # subscript operator
  rio('afile').chomp > anarray           # copy-to operator
  anarray = rio('afile').chomp.to_a      # to_a
  anarray = rio('afile').chomp.readlines # IO#readlines
  
+Iterate over selected lines of a file
+ rio('adir').lines(0..3) { |aline| ... }       # a range of lines
+ rio('adir').lines(/re/) { |aline| ... }       # by regular expression
+ rio('adir').lines(0..3,/re/) { |aline| ... }  # or both
+ 
+Return selected lines of a file as an array
+ rio('adir').lines[0..3]       # a range of lines
+ rio('adir').lines[/re/]       # by regular expression
+ rio('adir').lines[0..3,/re/]  # or both
+ 
+Iterate over selected chomped lines of a file
+ rio('adir').chomp.lines(0..3) { |aline| ... }       # a range of lines
+ rio('adir').chomp.lines(/re/) { |aline| ... }       # by regular expression
+
+Return selected chomped lines of a file as an array
+ rio('adir').chomp[0..3]  # a range of lines
+ rio('adir').chomp[/re/]  # by regular expression
+ 
 Copy a gzipped file un-gzipping it
  rio('afile.gz').gzip > rio('afile')
 
@@ -106,56 +142,20 @@ Copy a plain file, gzipping it
 Copy a file from a ftp server into a local file un-gzipping it
  rio('ftp://host/afile.gz').gzip > rio('afile')
 
-Iterate over the entries in a directory
- rio('adir').entries { |entrio| ... }
-
-Iterate over only the files in a directory
- rio('adir').files { |entrio| ... }
+Return an array of .rb files excluding symlinks to .rb files
+ rio('adir').files('*.rb').skip[:symlink?]
 
-Iterate over only the .rb files in a directory
- rio('adir').files('*.rb') { |entrio| ... }
-
-Iterate over only the _dot_ files in a directory
- rio('adir').files(/^\./) { |entrio| ... }
-
-Iterate over the files in a directory and its subdirectories, skipping '.svn' and 'CVS' directories 
- rio('adir').norecurse(/^\.svn$/,'CVS').files { |entrio| ... }
-
-Create an array of the .rb entries in a directory
- anarray = rio('adir')['*.rb']
-
-Create an array of the .rb entries in a directory and its subdirectories
- anarray = rio('adir').all['*.rb']
-
-Iterate over the .rb files in a directory and its subdirectories
- rio('adir').all.files('*.rb') { |entrio| ... }
+Put the first 10 chomped lines of a gzipped file into an array
+ anarray =  rio('afile.gz').chomp.gzip[0...10] 
 
-Copy an entire directory structure and the .rb files within it
- rio('adir').dirs.files('*.rb') > rio('another_directory')
+Copy lines 0 and 3 thru 5 of a gzipped file on an ftp server to stdout
+ rio('ftp://host/afile.gz').gzip.lines(0,3..5) > ?-
 
-Iterate over the first 10 chomped lines of a file
- rio('afile').chomp.lines(0..9) { |line| ... }
-
-Put the first 10 chomped lines of a file into an array
- anarray = rio('afile').chomp.lines[0..9]
-
-Copy the first 10 lines of a file into another file
- rio('afile').lines(0..9) > rio('another_file')
-
-Copy the first 10 lines of a file to stdout
- rio('afile').lines(0..9) > rio(?-)
-
-Copy the first 10 lines of a gzipped file on an ftp server to stdout
- rio('ftp://host/afile.gz').gzip.lines(0..9) > rio(?-)
-
-Put the first 100 chomped lines of a gzipped file into an array
- anarray =  rio('afile.gz').chomp.gzip[0...100] 
-
-Put chomped lines that start with 'Rio' into an array
- anarray = rio('afile').chomp[/^Rio/]
+Return an array of files in a directory and its subdirectories, without descending into .svn directories. 
+ rio('adir').norecurse(/^\.svn$/).files[]
 
 Iterate over the non-empty, non-comment chomped lines of a file
- rio('afile').chomp.skiplines(:empty?,/^\s*#/) { |line| ... }
+ rio('afile').chomp.skip(:empty?,/^\s*#/) { |line| ... }
 
 Copy the output of th ps command into an array, skipping the header line and the ps command entry
  rio(?-,'ps -a').skiplines(0,/ps$/) > anarray 
@@ -168,9 +168,6 @@ Change the extension of all .htm files in a directory and its subdirectories to
    htmfile.extname = '.html'
  end
 
-Create a symbolic link 'asymlink' in 'adir' which refers to 'adir/afile'
- rio('adir/afile').symlink('adir/asymlink')
-
 === SUGGESTED READING
 
 * RIO::Doc::INTRO

data/lib/rio/ext/csv.rb

@@ -208,7 +208,11 @@ module RIO
               fields.csv_rec_to_s = _rec_to_s_proc(fs,rs)
             end
           end
-          fields
+#          p "csv#fields: #{fields}"
+#          fields.each do |f|
+#            p f
+#          end
+          fields.map{ |f| f.to_s }
         end
         def cnames(num)
           @cnames ||= trim((0...num).map { |n| "Col#{n}" })

data/lib/rio/ext/yaml.rb

@@ -54,6 +54,8 @@ module RIO
         protected :yaml_
         def objects(*args) records(*args) end
         def documents(*args) rows(*args) end
+        def object(*args) record(*args) end
+        def document(*args) row(*args) end
         def skipobjects(*args) skiprecords(*args) end
         def skipdocuments(*args) skiprows(*args) end
       end
@@ -85,16 +87,6 @@ module RIO
             YAML.dump(recs,ioarg)
           end
         end
-        def cpto_obj_(arg)
-          self.each { |obj|
-            
-          }
-        end
-        def cpto_array_(array)
-          self.each { |el|
-            array << el
-          }
-        end
         def cpto_string_(string)
           string << ::YAML.dump_stream(self.contents)
         end
@@ -122,21 +114,6 @@ module RIO
           getrec()
         end
 
-        def add_filters
-          cx['yaml_close_eof'],cx['closeoneof'] = cx['closeoneof'],false
-          super
-        end
-        def each_(&block)
-          #old_close_eof,cx['closeoneof'] = cx['closeoneof'],false
-          super
-          cx['closeoneof'] = cx.delete('yaml_close_eof') 
-          
-          if closeoneof?
-            add_filter(Filter::CloseOnEOF)
-            ioh.oncloseproc = proc { self.on_closeoneof }
-          end
-          closeoneof? ? ioh.close_on_eof_(self) : self
-        end
       end
     end
 
@@ -145,23 +122,25 @@ module RIO
         protected
 
         def cpfrom_(arg)
-            case arg
-            #when ::Array then cpfrom_array_(arg)
-            when Rio,::IO,::StringIO then super
-            else self.put_(arg)
-            end
-            self
-        end
-        def cpfrom_array_(array)
-          array.each { |el|
-            self.put_(el)
-          }
-          self
-        end
-        def cpfrom_rio_(ario)
-          ioh.puts(::YAML.dump_stream(*ario[]))
+          #p "yaml#cpfrom_(#{arg})"
+          case arg
+          #when ::Array then cpfrom_array_(arg)
+          when Rio,::IO,::StringIO then super
+          else self.put_(arg)
+          end
           self
         end
+#        def cpfrom_array_(array)
+#          array.each { |el|
+#            self.put_(el)
+#          }
+#          self
+#        end
+#        def cpfrom_rio_(ario)
+#          p "yaml#cpfrom_rio_(#{ario})"
+#          ioh.puts(::YAML.dump_stream(*ario[]))
+#          self
+#        end
         def put_(obj)
           #p callstr('put_',obj)
           ioh.puts(obj.to_yaml)

data/lib/rio/if/fileordir.rb

@@ -109,7 +109,7 @@ module RIO
       def rename(*args,&block) target.rename(*args,&block); self end
       
 
-      # Behaves like IF::GrandeStream#rename, but also changes the calling Rio to 
+      # Behaves like IF::FileOrDir#rename, but also changes the calling Rio to 
       # refer to the renamed path
       def rename!(*args,&block) target.rename!(*args,&block); self end
       

data/lib/rio/if/grande.rb

@@ -126,15 +126,15 @@ module RIO
       # As with IF::Grande#each:
       # * Files and directories are returned as Rios
       # * The types of entries is also affected by IF::GrandeEntry#files and IF::GrandeEntry#dirs.
-      #    rio('adir').files['*.txt'] # array of all _.txt_ files
+      #    rio('adir').files['*.txt'] # array of all .txt files
       #    rio('adir').dirs(/^\./) # array of all dot directories
       # * Recursion is enabled using IF::GrandeEntry#all
-      #    rio('adir').all.files['*.[ch]'] # array of c source files in _adir_ and its subdirecories
-      #    rio('adir').all.dirs[/^\.svn/]  # array of subversion directories in _adir_ and subdirectories
+      #    rio('adir').all.files['*.[ch]'] # array of c source files in adir and its subdirecories
+      #    rio('adir').all.dirs[/^\.svn/]  # array of subversion directories in adir and subdirectories
       # * IF::GrandeEntry#files and IF::GrandeEntry#dirs act independetly of each other. 
       #   Specifying both will cause both to be returned. 
       #   The argument list to IF::Grande#[] will be applied to the closest.
-      #    rio('adir').files('*.rb').dirs['ruby*'] # array of _.rb_ files and 
+      #    rio('adir').files('*.rb').dirs['ruby*'] # array of .rb files and 
       #                                            # directories starting with 'ruby'
       #    rio('adir').dirs('ruby*').files['*.rb'] # same thing
       #

data/lib/rio/if/grande_entry.rb

@@ -62,6 +62,12 @@ module RIO
       #  rio('adir').dirs[/^\./] # return an array of dot directories
       #  rio('adir').dirs[:symlink?] # an array of symlinks to directories
       #
+      # Given the directory structure 'adir/a/b/c/d'
+      #
+      #  rio('adir').all.dirs[2]          #=> 'adir/a/b'
+      #  rio('adir').all.dirs[0..2]       #=> 'adir/a','adir/a/b'
+      #  rio('adir').all.skipdirs[0..2]   #=> 'adir/a/b/c','adir/a/b/c/d'
+      #
       def dirs(*args,&block) target.dirs(*args,&block); self end
       
       # Grande Directory Exclude Method 

data/lib/rio/if/grande_stream.rb

@@ -91,7 +91,7 @@ module RIO
 
       # Sets the rio to read bytes and returns the rio
       #
-      # _n_ specifies the number of bytes to be returned on each iteration of IF::Grande#each or by IF::Grande#getrec. If _args_
+      # _n_ specifies the number of bytes to be returned on each iteration of IF::Grande#each or by IF::GrandeStream#getrec. If _args_
       # are provided, they are treated as record selectors as if <tt>ario.bytes(n).records(*args)</tt> had been
       # called. See also #records, #lines, IF::Grande#each, IF::Grande#[]
       # 
@@ -115,7 +115,7 @@ module RIO
       def bytes(n=1,*args,&block) target.bytes(n,*args,&block); self end
 
 
-      # Specifies which records will be iterated through by IF::Grande#each or returned by IF::Grande#getrec
+      # Specifies which records will be iterated through by IF::Grande#each or returned by IF::GrandeStream#getrec
       # 
       # If called with a block behaves as if <tt>records(*args).each(&block)</tt> had been called
       # 
@@ -126,8 +126,8 @@ module RIO
       # and extensions such as IF::CSV#csv and IF::YAML#yaml.
       #
       # If args are provided they may be one or more of the following:
-      # Regexp::  any matching record will be iterated over by IF::Grande#each or returned by IF::Grande#getrec
-      # Integer:: specifies a record-number (zero-based) to be iterated over by IF::Grande#each or returned by IF::Grande#getrec
+      # Regexp::  any matching record will be iterated over by IF::Grande#each or returned by IF::GrandeStream#getrec
+      # Integer:: specifies a record-number (zero-based) to be iterated over by IF::Grande#each or returned by IF::GrandeStream#getrec
       # Range::   specifies a range of records (zero-based) to included in the iteration
       # Proc::    a proc which will be called for each record, records are included unless nil or false is returned
       # Symbol::  a symbol which will _sent_ to each record, records are included unless nil or false is returned
@@ -157,7 +157,7 @@ module RIO
       def records(*args,&block) target.records(*args,&block); self end
 
 
-      # Specifies records which should *not* be iterated through by IF::Grande#each or returned by IF::Grande#getrec
+      # Specifies records which should *not* be iterated through by IF::Grande#each or returned by IF::GrandeStream#getrec
       # 
       # If called with a block behaves as if <tt>skiprecords(*args).each(&block)</tt>
       # had been called
@@ -190,7 +190,7 @@ module RIO
 
 
       # Sets the Rio to read lines and specifies lines which should *not* be iterated through by IF::Grande#each or 
-      # returned by IF::Grande#getrec
+      # returned by IF::GrandeStream#getrec
       # 
       # If called with a block behaves as if <tt>skiplines(*args).each(&block)</tt> had been called
       # 
@@ -217,14 +217,14 @@ module RIO
 
 
       # Sets the Rio to read rows and specifies rows which should be iterated through 
-      # by IF::Grande#each or returned by IF::Grande#getrec.
+      # by IF::Grande#each or returned by IF::GrandeStream#getrec.
       # #rows is intended for use by extensions, where the concept of a row is reasonable. 
       # In the absensence of an extension behaves like #records.
       def rows(*args,&block) target.rows(*args,&block); self end
 
 
       # Sets the Rio to read rows and specifies lines which should *not* be iterated 
-      # through by IF::Grande#each or returned by IF::Grande#getrec
+      # through by IF::Grande#each or returned by IF::GrandeStream#getrec
       # #skiprows is intended for use by extensions, where the concept of a row is 
       # reasonable. In the absence of an extension behaves like #skiprecords
       def skiprows(*args,&block) target.skiprows(*args,&block); self end
@@ -359,6 +359,8 @@ module RIO
       #
       # Returns the Rio
       #
+      #  rio(?-,'cat').w!.puts!("Hello Kitty").readline #=> "Hello Kitty"
+      #
       # See the discussion for #a. 
       #
       def w!() target.w!(); self end

data/lib/rio/if/path.rb

@@ -120,7 +120,7 @@ module RIO
       # to the value returned by File#extname. Returns the Rio.
       #
       #  ario = rio('afile.tar.gz')
-      #  ario.ext?                        #=> '.ext'
+      #  ario.ext?                        #=> '.gz'
       #  ario.basename                    #=> rio('afile.tar')
       #  ario.ext('.tar.gz').basename     #=> rio('afile')
       #  ario.ext?                        #=> '.tar.gz'