rio 0.3.4 → 0.3.6

data/lib/rio/constructor.rb

@@ -198,6 +198,19 @@ module RIO
   #
   # This is Rio's interface to IO#popen
   #
+  # ===== Creating a Rio Pipe
+  #
+  # A Rio Pipe is a sequence of Rios that are run with the output of each being
+  # copied to the input of the next.
+  #
+  # <tt>rio(?|, ario, ...)</tt> (mnemonic: '|' is the Unix pipe operator)
+  #
+  # <tt>rio(:cmdpipe, ario, ...)</tt>
+  #
+  #
+  # See also Rio#|
+  #
+  #
   def rio(*args,&block)  # :yields: self
     Rio.rio(*args,&block) 
   end

data/lib/rio/context/copying.rb

@@ -0,0 +1,56 @@
+#--
+# =============================================================================== 
+# 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/context/cxx.rb'
+module RIO
+  module Cx
+    module Methods
+      def copying_to() cx['copying_to'] = true; self end
+      def copying_to?() cx['copying_to'] end
+      def copying_to_done() cx.delete('copying_to'); self end
+
+      def copying_from() cx['copying_from'] = true; self end
+      def copying_from?() cx['copying_from'] end
+      def copying_from_done() cx.delete('copying_from'); self end
+
+      def copying(dest) dest.copying_to; copying_from end
+      def copying?() copying_to? or copying_from? end
+      def copying_done(dest) dest.copying_to_done; copying_from_done end
+    end
+  end
+end
+      

data/lib/rio/context/methods.rb

@@ -44,6 +44,7 @@ require 'rio/context/skip'
 require 'rio/filter'   
 require 'rio/context/closeoneof'   
 require 'rio/context/gzip'   
+require 'rio/context/copying'   
 
 module RIO
   module Cx #:nodoc: all

data/lib/rio/cp.rb

@@ -101,35 +101,53 @@ module RIO
         include Util::Input
         def >>(arg)
           cpclose(arg) {
-            case arg
-            when ::Array,::String,::IO then cpto_obj_(arg)
-            else _cpto_rio(arg,:<<)
-            end
-            self
+            apto_(arg)
           }
         end
         def >(arg)
           cpclose(arg) {
-            case arg 
-            when ::Array,::String then cpto_obj_(arg.clear)
-            when ::IO then cpto_obj_(arg)
-            else _cpto_rio(arg,:<)
-            end
-            self
+            cpto_(arg)
           }
         end
         alias :copy_to :>
         alias :append_to :>>
-        private
 
-        def _cpto_rio(arg,sym)
+        protected
+        def cpto_(arg)
+          case arg 
+          when ::Array then cpto_array_(arg.clear)
+          when ::String then cpto_string_(arg.clear)
+          when ::IO then cpto_obj_(arg)
+          else cpto_rio_(arg,:<)
+          end
+          self
+        end
+        def apto_(arg)
+          case arg
+          when ::Array then cpto_array_(arg)
+          when ::String then cpto_string_(arg)
+          when ::IO then cpto_obj_(arg)
+          else cpto_rio_(arg,:<<)
+          end
+          self
+        end
+
+        def cpto_array_(arg)
+          cpto_obj_(arg)
+        end
+        def cpto_string_(arg)
+          cpto_obj_(arg)
+        end
+
+        def cpto_rio_(arg,sym)
           ario = ensure_rio(arg)
           ario = ario.join(self.filename) if ario.dir?
           ario.cpclose {
             ario = ario.iostate(sym)
-            self.each do |el|
-              ario << el
-            end
+            self.copying(ario).each { |el|
+              ario.putrec(el)
+#              ario << el
+            }.copying_done(ario)
             ario
           }
         end
@@ -137,26 +155,27 @@ module RIO
 
       module Output
         include Util::Output
-        def <<(arg) cpclose { _cpfrom(arg) } end
-        def <(arg) cpclose { _cpfrom(arg) } end
+        def <<(arg) cpclose { cpfrom_(arg) } end
+        def <(arg) cpclose { cpfrom_(arg) } end
         alias :copy_from :<
         alias :append_from :<<
 
-        private
+        protected
 
-        def _cpfrom(arg)
+        def cpfrom_(arg)
             case arg
             when ::Array then cpfrom_array_(arg)
             when ::IO then cpfrom_obj_(arg)
             when ::String then self.put_(arg)
-            else _cpfrom_rio(arg)
+            else cpfrom_rio_(arg)
             end
             self
         end
-        def _cpfrom_rio(arg)
-          ensure_rio(arg).each do |el|
-            self << el
-          end
+        def cpfrom_rio_(arg)
+          ensure_rio(arg).copying(self).each { |el|
+            self.putrec(el)
+#            self << el
+          }.copying_done(self)
         end
       end
     end
@@ -222,21 +241,21 @@ module RIO
     module Dir
       module Output
         include Util::Output
-        def <<(arg)  _cpfrom(arg); self  end
-        def <(arg)  _cpfrom(arg); self end
+        def <<(arg)  cpfrom_(arg); self  end
+        def <(arg)  cpfrom_(arg); self end
         alias :copy_from :<
         alias :append_from :<<
 
         private
 
-        def _cpfrom(arg)
+        def cpfrom_(arg)
           case arg
           when ::Array then cpfrom_array_(arg)
-          else _cpfrom_rio(ensure_rio(arg))
+          else cpfrom_rio_(ensure_rio(arg))
           end
         end
-        def _cpfrom_rio(ario)
-          #p callstr('_cpfrom_rio',ario)
+        def cpfrom_rio_(ario)
+          #p callstr('cpfrom_rio_',ario)
           dest = self.join(ario.filename)
           case
           when ario.symlink?
@@ -256,14 +275,14 @@ module RIO
         def >>(arg)
           case arg
           when ::Array then cpto_obj_(arg)
-          else _cpto_rio(ensure_rio(arg))
+          else cpto_rio_(ensure_rio(arg))
           end
           self
         end
         def >(arg)
           case arg
           when ::Array then cpto_obj_(arg.clear)
-          else _cpto_rio(ensure_rio(arg))
+          else cpto_rio_(ensure_rio(arg))
           end
           self
         end
@@ -272,7 +291,7 @@ module RIO
 
         private
 
-        def _cpto_rio(ario)
+        def cpto_rio_(ario)
           ario = ario.join(self.filename) if ario.exist?
           nostreamenum.cpto_obj_(ario.mkdir)
         end

data/lib/rio/doc/HOWTO.rb

@@ -562,12 +562,18 @@ IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO, OpenURI, Zlib, and CSV.
   the 'ps' command itself
    ps =  rio(?-,'ps -a').skiplines[0,/ps$/]
 
-* Run an external program, copying its input from one location and its output from another, 
+* Run an external program, copying its input from one location and its output to another, 
   and make it look very much like a shell command.
+
+   infile = rio(?","Hello Kitty\n")
+   outfile = rio('out.txt')
+
    # method 1
-   ans = ""
    cat = rio(?-,'cat').w!
-   cat <"Hello Kitty\n" >ans
+   cat <infile >outfile
+
+   # method 2
+   infile | 'cat' | outfile
    
 ---
 

data/lib/rio/doc/INTRO.rb

@@ -918,14 +918,14 @@ using the copy operators.
 
 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#skipcolumns.
 
  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.skipcolumns(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('f.csv').csv.skipcolumns(1..2).to_a  #==>[["h0", "h3"], ["f0", "f3"]]
 
 Rio#columns can, of course be used with the +each+ and the copy
 operators:
@@ -934,6 +934,116 @@ operators:
  rio('out').contents  #==>"h0,h1\nf0,f1\n"
 
 
+==== YAML mode
+
+Rio uses the YAML class from the Ruby standard library to provide
+support for reading and writing YAML files. Normally
+using <tt>(skip)records</tt> is identical to <tt>(skip)lines</tt> because
+while +records+ only selects and does not specify the record-type,
++lines+ is the default. 
+
+The YAML extension distingishes between items selected using
+Rio#records, Rio#rows and Rio#lines. Rio returns objects
+loaded via YAML#load when +records+ is used; returns the YAML text
+as a String when +rows+ is used; and
+returns lines as Strings as normal when +lines+ is used.  
++records+ is the default. In yaml-mode, <tt>(skip)records</tt> can be called
+as <tt>(skip)objects</tt> and <tt>(skip)rows</tt> can be called as
+<tt>(skip)documents</tt>
+
+To read a single YAML document, Rio provides #getobj and #load
+For example, consider the following partial 'database.yml' from
+the rails distribution:
+
+ development:
+   adapter: mysql
+   database: rails_development
+
+ test:
+   adapter: mysql
+   database: rails_test
+
+
+To get the object represented in the yaml file:
+
+ rio('database.yml').yaml.load
+    ==>{"development"=>{"adapter"=>"mysql", "database"=>"rails_development"}, 
+        "test"=>{"adapter"=>"mysql", "database"=>"rails_test"}}
+
+Or one could read parts of the file like so:
+
+ rio('database.yml').yaml.getobj['development']['database']
+    ==>"rails_development"
+
+Single objects can be written using #putobj and #putobj!
+which is aliased to #dump
+
+ anobject = {
+   'production' => {
+     'adapter' => 'mysql',
+     'database' => 'rails_production',
+   }
+ }
+ rio('afile.yaml').yaml.dump(anobject)
+
+The YAML extension changes the way the grande copy operators
+interpret their argument. Rio#< (copy-from) and Rio#<< (append-from)
+treat an array as an array of objects which are converted using their 
+#to_yaml method before writing.
+
+ rio('afile.yaml').yaml < [obj1, obj2, obj3]
+
+Because of this, copying an ::Array must be done like this:
+
+ rio('afile.yaml').yaml < [anarray]
+
+If their argument is a Rio or ::IO it is iterate through as normal, 
+with each record converted using its to_yaml method.
+
+For all other objects, the result of their +to_yaml+ operator is simply written.
+
+ rio('afile.yaml').yaml < anobject
+
+Rio#> (copy-to) and Rio#>> (append-to) will fill an array with with all selected
+YAML documents in the Rio. For non-arrays, the yaml text is copied. (This may change
+if a useful reasonable alternative can be found)
+ 
+ rio('afile.yaml').yaml > anarray # load all YAML documents from 'afile.yaml'
+
+Single objects can be written using Rio#putrec (aliased to Rio#putobj and Rio#dump)
+
+ rio('afile.yaml').yaml.putobj(anobject)
+
+Single objects can be loaded using Rio#getrec (aliase to Rio#getobj and Rio#load)
+
+ anobject = rio('afile.yaml').yaml.getobj
+
+Note that other than this redefinition of what a record is and how the copy
+operators interpret their argument, a Rio in yaml-mode is just like any other
+Rio. And all the things you can do with any Rio come for free.
+They can be iterated over using #each and read into an array using #[]
+just like any other Rio. All the selection criteria are identical also.
+
+Get the first three objects into an array:
+
+ array_of_objects = rio('afile.yaml').yaml[0..2]
+
+Iterate over only YAML documents that are a kind_of ::Hash use:
+
+ rio('afile.yaml').yaml(::Hash) {|ahash| ...} 
+
+This takes advantage of the fact that the default for matching records is <tt>===</tt>
+
+Selecting records using a Proc can be used as normal:
+
+ anarray = rio('afile.yaml').yaml(proc{|anobject| ...}).to_a
+
+One could even use the copy operator to convert a CSV file to a YAML representation of
+the same data:
+
+ rio('afile.yaml').yaml < rio('afile.csv').csv 
+
+
 ---
 
 

data/lib/rio/ext.rb

@@ -36,17 +36,22 @@
 
 
 require 'rio/ext/csv'
+require 'rio/ext/yaml'
 module RIO
   module Ext #:nodoc: all
-    OUTPUT_SYMS = CSV::Output.instance_methods.build_hash { |sym| [sym.to_s,1] }
+    OUTPUT_SYMS = (CSV::Output.instance_methods + YAML::Output.instance_methods).build_hash { |sym| [sym.to_s,1] }
+
     module Cx
       include CSV::Cx
+      include YAML::Cx
     end
   end
   module Ext
     module Input
       def add_extensions(obj)
+        #p "add_extensions(#{obj.inspect})"
         obj.extend(CSV::Input) if obj.csv?
+        obj.extend(YAML::Input) if obj.yaml?
         obj
       end
       module_function :add_extensions
@@ -54,6 +59,7 @@ module RIO
     module Output
       def add_extensions(obj)
         obj.extend(CSV::Output) if obj.csv?
+        obj.extend(YAML::Output) if obj.yaml?
         obj
       end
       module_function :add_extensions

data/lib/rio/ext/csv.rb

@@ -55,11 +55,16 @@ module RIO
         end
         protected :csv_
         def columns(*ranges,&block)
-          @cnames = nil
-          cx['col_args'] = ranges.flatten
-          cxx('columns',true,&block)
+          if skipping?
+            cx['skipping'] = false
+            skipcolumns(*args,&block)
+          else
+            @cnames = nil
+            cx['col_args'] = ranges.flatten
+            cxx('columns',true,&block)
+          end
         end
-        def nocolumns(*ranges,&block)
+        def skipcolumns(*ranges,&block)
           @cnames = nil
           cx['nocol_args'] = ranges.flatten
           cxx('columns',true,&block)
@@ -99,8 +104,10 @@ module RIO
           #p "#{callstr('to_rec_',raw_rec,@recno)} ; itertype=#{cx['stream_itertype']}"
           case cx['stream_itertype']
           when 'lines' 
-            raw_rec.extend(RIO::Ext::CSV::Str)
-            raw_rec.csv_s_to_rec = _s_to_rec_proc(cx['csv_fs'],cx['csv_rs'])
+            unless copying_from?
+              raw_rec.extend(RIO::Ext::CSV::Str)
+              raw_rec.csv_s_to_rec = _s_to_rec_proc(cx['csv_fs'],cx['csv_rs'])
+            end
             raw_rec
           when 'records'
             _l2record(raw_rec,cx['csv_fs'],cx['csv_rs'])
@@ -153,8 +160,10 @@ module RIO
         def _l2record(line,fs,rs)
           #p callstr('_l2record',line,fs,rs,cols)
           fields = trim(::CSV.parse_line(line,fs,rs))
-          fields.extend(RIO::Ext::CSV::Ary)
-          fields.csv_rec_to_s = _rec_to_s_proc(fs,rs)
+          unless copying_from?
+            fields.extend(RIO::Ext::CSV::Ary)
+            fields.csv_rec_to_s = _rec_to_s_proc(fs,rs)
+          end
           fields
         end
         def cnames(num)