rio 0.3.1

data/lib/rio/cxdir.rb

@@ -0,0 +1,79 @@
+#--
+# =============================================================================== 
+# 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 CxDir #:nodoc: all
+    private
+    
+    def _ss_keys()  Cx::SS::ENTRY_KEYS + Cx::SS::STREAM_KEYS end
+    CX_ALL_SKIP_KEYS = ['retrystate']
+    def _add_recurse_iter_cx(ario)
+      new_cx = ario.cx
+      cx.keys.reject { |k| CX_ALL_SKIP_KEYS.include?(k) }.each { |k|
+        new_cx.set_(k,cx[k])
+      }
+      ario.cx = new_cx
+      ario
+    end
+    def _add_cx(ario,keys)
+      new_cx = ario.cx
+      keys.each {|k|
+        next unless cx.has_key?(k)
+        new_cx.set_(k,cx[k])
+      }
+      ario.cx = new_cx
+    end
+    CX_DIR_ITER_KEYS = %w[sel nosel]
+    CX_STREAM_ITER_KEYS = %w[stream_rectype stream_itertype stream_sel stream_nosel]
+    def _add_iter_cx(ario)
+      if nostreamenum?
+        _add_cx(ario,CX_DIR_ITER_KEYS)
+      end
+      _add_stream_iter_cx(ario)
+    end
+    def _add_stream_iter_cx(ario)
+      _add_cx(ario,CX_STREAM_ITER_KEYS)
+      new_cx = ario.cx
+      if stream_iter?
+        new_cx.set_('ss_args',cx['ss_args']) if cx.has_key?('ss_args')
+        new_cx.set_('ss_type',cx['ss_type']) if cx.has_key?('ss_type')
+      end
+      ario.cx = new_cx
+      ario
+    end
+  end
+end

data/lib/rio/dir.rb

@@ -0,0 +1,145 @@
+#--
+# =============================================================================== 
+# 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/ops/path'
+require 'rio/ops/dir'
+require 'rio/filter/closeoneof'
+require 'rio/ioh'
+module RIO
+  module Dir #:nodoc: all
+    class Base < State::Base
+      include Ops::Path::Str
+      def self.copy_(src,dst)
+        Impl::U.cp_r(src,dst) 
+      end
+      def open?() !ioh.nil? end
+    end
+
+    class NonExisting < Base
+      include Ops::Dir::NonExisting
+      def check?() not self.exist?  end
+      def when_missing(sym,*args)  gofigure(sym,*args) end
+    end # class EDir
+
+    class Existing < Base
+      include Ops::Dir::Existing
+
+      def check?() self.directory? end
+      def when_missing(sym,*args) dopen() end
+      def dopen() 
+        self.rl = RIO::Dir::RL.new(self.to_uri)
+        become 'Dir::Open'
+      end
+    end # class EDir
+    class Open < Base
+      def check?() true  end
+      def open(m=nil,*args)
+        open_(*args)
+      end
+      def open_() 
+        unless open?
+          ios = self.rl.open()
+          self.ioh = IOH::Dir.new(ios)
+#          self.ioh = self.rl.open()
+        end
+        self 
+      end
+      def when_missing(sym,*args) 
+        nobj = open_.dstream() 
+        return nobj unless nobj.nil?
+        gofigure(sym,*args)
+      end
+
+      def dstream() 
+        cl = 'Dir::Stream'
+        #p "LOOP: retry: #{cx['retrystate'].inspect} => #{cl}" 
+        return nil if cx['retrystate'] == cl
+        cx['retrystate'] = cl
+
+        become(cl)
+      end
+    end
+    class Stream < Base
+      include Ops::Dir::Stream
+      def check?() open? end
+      def when_missing(sym,*args) 
+        #p callstr('when_missing',sym,*args)
+        retryreset() 
+      end
+      def base_state() 'Dir::Close' end
+
+      def reset()
+        self.close.softreset()
+      end
+      alias :copyclose :reset
+    end
+    class Close < Base
+      def close() 
+        #p callstr('close')+" mode='#{mode?}' ioh=#{self.ioh} open?=#{open?}"
+        return self unless self.open? 
+        self.close_
+        cx['retrystate'] = nil
+        self
+      end
+
+       def close_() 
+         #p callstr('close_')+" ioh=#{self.ioh} open?=#{open?}"
+        return self unless self.open? 
+        self.clear_selection
+        self.ioh.close 
+        self.ioh = nil
+        self.rl.close
+        self
+      end
+      protected :close_
+
+      def clear_selection()
+        cx.delete('sel')
+        cx.delete('nosel')
+        cx.delete('nostreamenum')
+        self
+      end
+
+      def check?() true end
+      def when_missing(sym,*args) 
+#        p callstr('when_missing',sym,*args)
+        self.close_.retryreset()
+      end
+    end
+  end 
+
+end # module RIO

data/lib/rio/doc.rb

@@ -0,0 +1,45 @@
+#--
+# =============================================================================== 
+# 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
+  TITLE = "Rio"
+  SUMMARY = "Rio - Ruby I/O Comfort Class"
+  DESCRIPTION = "Rio is a convenience class wrapping much of the functionality of " +
+                "IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO, OpenURI, Zlib, and CSV.
+"
+end

data/lib/rio/doc/HOWTO.rb

@@ -0,0 +1,691 @@
+#--
+# =============================================================================== 
+# 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 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, OpenURI, Zlib, and CSV.
+
+== HOWTO...
+
+=== Read a single file
+   ario = rio('afile')
+   string = ""
+   array = []
+
+* Read a file into a string.
+   # method 1
+   string = ario.slurp
+   # method 2
+   ario > string
+
+* Append a file onto a string.
+   # method 1
+   ario >> string
+   # method 2
+   string += ario.slurp
+
+* Read lines of a file into an array
+   # method 1
+   array = ario[]
+   # method 2
+   ario > array
+   # method 3
+   array = ario.to_a
+   # method 4 
+   array = ario.readlines
+
+* Append lines of a file into an array
+   # method 1
+   ario >> array
+   # method 2
+   array += ario.lines[]
+
+* Read the first 10 lines of a file into an array
+   # method 1
+   array = ario[0...10]
+   # method 2
+   array = ario.lines[0...10]
+   # method 3
+   ario.lines(0...10) > array
+
+* Read lines of a file into an array, with each line chomped
+   # method 1
+   array = ario.chomp[]
+   # method 2
+   array = ario.chomp.lines[]
+   # method 3
+   ario.chomp > array
+
+* Append the first 10 lines of a file into an array, with each line chomped
+   # method 1
+   array += ario.chomp.lines[0...10]
+   # method 2
+   ario.chomp.lines(0...10) >> array
+
+* Read all lines starting with 'require' into an array, with each line chomped
+   # method 1
+   array = ario.chomp.lines(/^\s*require/)
+   # method 2
+   ario.chomp.lines(/^\s*require/) > array
+
+* Read a gzipped file into a string
+   # method 1
+   rio('afile.gz').gzip > string
+   # method 2
+   string = rio('afile.gz').gzip.slurp
+
+* Append a gzipped file into a string
+   # method 1
+   rio('afile.gz').gzip >> string
+   # method 2
+   string += rio('afile.gz').gzip.slurp
+
+* Iterate through all the lines of a file
+   # method 1
+   rio('afile').lines { |line| ... }
+   # method 2
+   rio('afile').each { |line| ... }
+   # method 3
+   rio('afile').each_line { |line| ... }
+
+
+* Iterate through the lines of a gzipped file
+   rio('afile.gz').gzip { |line| ... }
+
+* Iterate through all non-empty lines of a gzipped file, with each line chomped
+   rio('afile.gz').gzip.chomp.nolines(:empty?) { |line| ... }
+
+* Iterate through the first 100 lines of a file
+   # method 1
+   rio('afile').lines(0...100) { |line| ... }
+
+* Iterate through the first line and all ruby comment lines in a gzipped file
+   rio('afile.rb.gz').gzip.lines(0,/^\s*#/) { |line| ... }
+
+* Iterate through the lines of a ruby file that are neither empty nor comments, with all lines chomped
+   rio('afile.rb.gz').chomp.nolines(/^\s*#/,:empty?) { |line| ... }
+
+* Read all the comment lines from a ruby file into an array with all lines chomped
+   # method 1
+   array = rio('afile.rb').chomp.lines[/^\s*#/]
+   # method 2
+   rio('afile.rb').chomp.lines(/^\s*#/) > array
+  
+
+* Read lines of a file into an array, with each line chomped, skipping any lines longer than 1024 chars
+   # method 1
+   ario.chomp.lines(proc{ |line| line.length <= 1024}) > array
+   # method 2
+   array = ario.chomp.nolines[proc{ |line| line.length > 1024}]
+   # method 3
+   array = ario.chomp.lines(proc{ |line| line.length <= 1024}).to_a
+
+---
+
+=== Write to a single file
+
+   ario = rio('afile')
+   string = "A String\n"
+   array = ["Line 0\n","Line 1\n"]
+
+* Write a string to a file, leaving the Rio open
+   # method 1
+   ario.puts(string)
+   # method 2
+   ario.print(string)
+   # method 3
+   ario.noclose < string
+
+* Write a string to a file and close the file
+   # method 1
+   rio('afile') < string
+   # method 2
+   ario.print!(string)
+   # method 3
+   ario.print(string).close
+
+* Append a string to a file, leaving the Rio open
+   # method 1
+   ario.a.puts(string)
+   # method 2
+   ario.a.print(string)
+   # method 3
+   ario.noclose << string
+
+* Append a string to a file and close the file
+   # method 1
+   rio('afile') << string
+   # method 2
+   rio('afile').a.print!(string)
+   # method 3
+   rio('afile').a.print(string).close
+
+* Write an array to a file, leaving the Rio open
+   # method 1
+   ario = rio('afile').nocloseoncopy
+   ario << array
+   # method 2
+   ario.noclose < array
+
+* Write an array to a file and close the file
+   # method 1
+   rio('afile') < array
+
+
+---
+
+=== Select records
+   ario = rio('afile')
+   string = ""
+   array = []
+
+* Put lines one thru ten and line 100 into an array
+   # method 1
+   array = ario[0..9,99]
+   # method 2
+   array = ario[0...10,99..99]
+   # method 3
+   ario(0..9,99) > array
+  
+* Put lines one thru ten,line 100 and lines starting with 'zippy' into an array
+   # method 1
+   array = ario[0..9,99,/^zippy/]
+   # method 2
+   array = ario[0...10,99..99,/^zippy/]
+   # method 3
+   ario(0..9,99,/^zippy/) > array
+  
+* Put lines that are longer than 128 bytes into an array
+   # method 1
+   array = ario[proc{ |l| l.length > 128}]
+   # method 2
+   array = ario.lines[proc{ |l| l.length > 128}]
+   # method 3
+   array = ario.nolines[proc{ |l| l.length <= 128}]
+  
+* Copy all lines that do not start with 'zippy' into another file
+   # method 1
+   ario.nolines(/^zippy/) > rio('another_file')
+   # method 2
+   ario.lines.nolines(/^zippy/) > rio('another_file')
+   # method 3
+   rio('another_file') < ario.nolines(/^zippy/)
+  
+* Copy the first 10 lines and lines starting with 'zippy', but exclude any lines longer than 128 bytes
+   # method 1
+   ario.lines(0...10,/^zippy/).nolines(proc{ |l| l.length > 128}] > rio('another_file')
+   # method 2
+   rio('another_file') < ario.lines(0...10,/^zippy/).nolines(proc{ |l| l.length > 128})
+  
+
+
+---
+
+=== Select directory entries
+   ario = rio('adir')
+   string = ""
+   array = []
+
+* Put all entries with the extension '.txt' into an array
+   # method 1
+   array = ario['*.txt']
+   # method 2
+   array = ario[/\.txt/]
+   # method 3
+   array = ario.entries['*.txt']
+  
+* Put all files with the extension '.txt' into an array
+   # method 1
+   array = ario.files['*.txt']
+   # method 2
+   array = ario.files[/\.txt/]
+   # method 3
+   array = ario.files['*.txt']
+  
+* Put all entries with the extension '.txt' into an array, including those in subdirectories
+   # method 1
+   array = ario.all['*.txt']
+   # method 2
+   array = ario.all[/\.txt/]
+   # method 3
+   array = ario.all.entries['*.txt']
+  
+* Put all entries with the extension '.txt' into an array, including those in subdirectories, except those
+  in subdirectories name '.svn'
+   # method 1
+   array = ario.norecurse('.svn').all['*.txt']
+   # method 2
+   array = ario.norecurse(/^\.svn$/).all[/\.txt/]
+   # method 3
+   array = ario.norecurse('.svn').entries['*.txt']
+   # method 4
+   array = ario.entries('*.txt').norecurse('.svn').to_a
+   # method 5
+   array = ario.norecurse('.svn')['*.txt']
+  
+* Iterate through all ruby files in a directory structure except those in the '.svn' and 'pkg' directories
+   # method 1
+   ario.norecurse('.svn','pkg').files('*.rb',proc{ |f| f.executable? and f[0] =~ /^#!.+ruby/ }) { |f| ... }
+
+* Put all files excluding those that are symlinks to files in an array
+   # method 1
+   array = ario.nofiles[:symlink?]
+   # method 2
+   array = ario.nofiles(:symlink?).files[]
+   # method 3
+   array = ario.nofiles(:symlink?).to_a
+   # method 4
+   array = ario.files.nofiles[:symlink?]
+
+* Put all entries that are not files (or symlinks to files) into an array
+   # method 1
+   array = ario.nofiles[]
+   # method 2
+   array = ario.nofiles.to_a
+
+* Put all entries that are symlinks to files into an array
+   # method 1
+   array = ario.files[proc{|f| f.file? and f.symlink?}]
+   # method 2
+   array = ario.files(proc{|f| f.file? and f.symlink?}).to_a
+
+* Put all directories except those named '.svn' into an array
+   # method 1
+   array = ario.nodirs['.svn']
+   # method 2
+   array = ario.nodirs[/^\.svn/]
+   # method 3
+   array = ario.nodirs('.svn').to_a
+   # method 4
+   array = ario.nodirs('.svn').dirs[]
+   # method 5
+   array = ario.nodirs('.svn')[]
+
+
+---
+
+=== Read and writing files
+   ario = rio('afile')
+   string = ""
+   array = []
+
+* Copy the contents of one file into another file
+   # method 1
+   rio('srcfile') > rio('dstfile')
+   # method 2
+   rio('dstfile') < rio('srcfile')
+   # method 3
+   rip('dstfile').print!(rio('srcfile').slurp)
+
+* Append the contents of one file to another file
+   # method 1
+   rio('srcfile') >> rio('dstfile')
+   # method 2
+   rio('dstfile') << rio('srcfile')
+   # method 3
+   rip('dstfile').a.print!(rio('srcfile').slurp)
+
+* Copy the first 10 lines of one file to another file
+   # method 1
+   rio('srcfile').lines(0...10) > rio('dstfile')
+   # method 2
+   rio('dstfile') < rio('srcfile').lines(0...10)
+   # method 3
+   rio('dstfile') < rio('srcfile').lines[0...10]
+
+* Concatenate several files into one
+   # method 1
+   rio('dstfile') < [ rio('src1'), rio('src2'), rio('src3') ]
+   # method 2
+   rio('dstfile') < rio('src1') << rio('src2') << rio('src3')
+
+* Copy a web page into a file
+   # method 1
+   rio('http://ruby-doc.org/') > rio('afile')
+   # method 2
+   rio('afile') < rio('http://ruby-doc.org/')
+   # method 3
+   rio('afile').print!(rio('http://ruby-doc.org/').slurp)
+
+* Append the output of the daytime server running on the localhost to a file
+   # method 1
+   rio("tcp://localhost:daytime") >> rio('afile')
+   # method 2
+   rio("tcp:",'localhost','daytime') >> rio('afile')
+   # method 3
+   rio('afile') << rio("tcp://:daytime")
+   # method 4
+   rio('afile') << rio("tcp://:13")
+
+* Copy the first line and all lines containing 'http:' to a file
+   # method 1
+   rio('srcfile').lines(0,/http:/) > rio('dstfile')
+   # method 2
+   rio('dstfile') < rio('srcfile').lines(0,/http:/)
+   # method 3
+   rio('dstfile') < rio('srcfile').lines[0,/http:/]
+   # method 4
+
+* Create a gzipped copy of a file
+   # method 1
+   rio('afile') > rio('afile.gz').gzip
+   # method 2
+   rio('afile.gz').gzip < rio('afile')
+   # method 3
+   rio('afile.gz').gzip.print!( rio('afile').slurp )
+
+* Create an ungzipped copy of a gzipped file
+   # method 1
+   rio('afile') < rio('afile.gz').gzip
+   # method 2
+   rio('afile.gz').gzip > rio('afile')
+   # method 3
+   rio('afile').print!( rio('afile.gz').gzip.slurp )
+
+* Copy the first 100 lines of gzipped file on a webserver into a local file
+   # method 1
+   rio('http://aserver/afile.gz').gzip.lines(0...100) > rio('afile')
+
+
+* Create a file composed of a header from another file, the output of the 'ps' command, some text and 
+  its creation time pulled from the daytime server running on your localhost
+   # method 1
+   rio('out') < [ rio('header'), rio(?-,'ps'), "Created on ", rio('tcp://:daytime') ]
+   # method 2
+   rio('out') < rio('header') << rio(?-,'ps') << "Created on: " << rio("tcp://:daytime")
+
+
+---
+
+=== Reading multiple files 
+   ario = rio('adir')
+   string = ""
+   array = []
+
+* Count the lines of code in a directory tree of ruby source files
+   # method 1
+   cnt = ario.all.files('*.rb').chomp.nolines(/^\s*#/,/^\s*$/).inject(0) { |sum,l|  sum += 1 }
+   # method 2
+   cnt = ario.all.files('*.rb').chomp.nolines[/^\s*#/,/^\s*$/].size
+
+* Concatanate the contents of all .txt files in a directory into an array
+   # method 1
+   array = ario.lines.files['*.txt']
+   # method 2
+   array = ario.files('*.txt').lines[]
+   # method 3
+   ario.files('*.txt').lines > array
+
+* Concatanate the first line of all .txt files in a directory into an array
+   # method 1
+   array = ario.lines(0).files['*.txt']
+   # method 2
+   array = ario.files('*.txt').lines[0]
+   # method 3
+   ario.files('*.txt').lines(0) > array
+
+* Copy all .txt files (but only their first ten lines) in a directory into another directiory
+   # method 1
+   ario.files('*.txt').lines(0...10) > rio('another_dir')
+
+---
+
+=== Read and write using Standard IO
+   string = ""
+   array = []
+
+* Prompt for input and return what was typed
+   # method 1
+   ans = rio(?-).chomp.print("Type Something: ").gets
+   # method 2
+   stdio = rio(?-).chomp
+   ans = stdio.print("Type Something: ").gets
+
+* Create a Rio tied to stdin or stdout, depending on how it is used
+   stdio = rio(?-)
+
+* Create a Rio tied to stderr
+   stderr = rio(?=)
+
+* Write a string to stdout
+   # method 1
+   rio(?-).puts("Hello World")
+   # method 2
+   rio(?-) << "Hello World\n"
+   # method 3
+   rio(?-) < "Hello World\n"
+
+* Read a string from stdin with the input chomped
+   # method 1
+   ans = rio(?-).chomp.gets
+   # method 2
+   stdio = rio(?-).chomp
+   ans = stdio.gets
+
+* Read from stdin until end of file with the result going into a string
+   # method 1
+   rio(?-) >> string
+   # method 2
+   rio(?-) > string
+
+* Read from stdin until end of file with the chomped lines going into an array
+   # method 1
+   rio(?-).chomp >> array
+   # method 2
+   rio(?-).chomp > array
+
+* Read from stdin until end of file with the result going into a file
+   # method 1
+   rio(?-) > rio('afile')
+   # method 2
+   rio('afile') < rio(?-)
+
+* Read from stdin until end of file with the result appended to a file
+   # method 1
+   rio(?-) >> rio('afile')
+   # method 2
+   rio('afile') << rio(?-)
+
+* Write a message to stderr
+   # method 1
+   rio(?=).puts("Hello Error")
+   # method 2
+   rio(?=) << "Hello Error\n"
+   # method 3
+   rio(?=) < "Hello Error\n"
+
+* Dump a file to stdout
+   # method 1
+   rio(?-) << rio('afile')
+   # method 2
+   rio('afile') >> rio(?-)
+   # method 3
+   rio('afile') > rio(?-)
+   # method 4
+   rio(?-) < rio('afile')
+   # method 5
+   rio(?-).print(rio('afile').slurp)
+
+* Emulate a simplified unix 'head' command which reads from stdin and writes the first 10 lines to stdout
+   # method 1
+   rio(?-).lines(0..9) > rio(?-)
+
+---
+
+=== Reading and writing from processes as one might do with popen 
+
+* Read the output of the 'ps' command into an array without the header line or the line representing
+  the 'ps' command itself
+   ps =  rio(?-,'ps -a').nolines[0,/ps$/]
+
+* Run an external program, copying its input from one location and its output from another, 
+  and make it look very much like a shell command.
+   # method 1
+   ans = ""
+   cat = rio(?-,'cat').w!
+   cat <"Hello Kitty\n" >ans
+   
+---
+
+=== Renaming and moving files
+   string = ""
+   array = []
+
+* Rename the file 'a' to 'b'
+   # method 1
+   rio('a').rename('b')
+   # method 2
+   rio('a').rename.filename = 'b'
+
+* Rename a file and leave the Rio referencing the files old name
+   ario = rio('a')
+   # method 1
+   ario.rename('b')
+
+* Rename a file and change the Rio to reference the new file name
+   ario = rio('a')
+   # method 1
+   ario.rename!('b')
+
+* Rename the file 'index.htm' to 'index.html'
+   # method 1
+   rio('index.htm').rename('index.html')
+   # method 2
+   rio('index.htm').rename.extname = '.html'
+
+* Rename the file 'index.html' to 'welcome.html'
+   # method 1
+   rio('index.html').rename('welecome.html')
+   # method 2
+   rio('index.htm').rename.basename = 'welcome'
+
+* Move a file from directory 'src' to directory 'dst'
+   # method 1
+   rio('src/afile').rename('dst/afile')
+   # method 2
+   rio('src/afile').rename.dirname = 'dst'
+
+* Change a file to have the extension '.html' leaving the rest of it as is
+   # method 1
+   ario.rename.extname = '.html'
+
+* Change a files basename to 'zippy' without changing its extension
+   # method 1
+   ario.rename.basename = 'zippy'
+
+* Change a file ending with '.tar.gz' to end with '.tgz'
+   # method 1
+   ario.rename.ext('.tar.gz').extname = '.tgz'
+
+* Change the extension of all files with the extension '.htm' in a directory to have the 
+  extension '.html'
+   # method 1
+   rio('adir').rename.files('*.htm') do |htmfile|
+     htmlfile.extname = '.html'
+   end
+   # method 2
+   rio('adir').files('*.htm') do |htmfile|
+     htmlfile.rename.extname = '.html'
+   end
+
+* Change the extension of all files with the extension '.htm' in a directory and its
+  subdirectories to have the extension '.html'
+   # method 1
+   rio('adir').rename.all.files('*.htm') do |htmfile|
+     htmfile.extname = '.html'
+   end
+   # method 2
+   rio('adir').all.files('*.htm') do |htmfile|
+     htmfile.rename.extname = '.html'
+   end
+
+---
+
+=== Manipulate a Rio's path
+   string = ""
+   array = []
+
+* Create a Rio with an additional subdirectory appended
+   ap = rio('adir')
+   # method 1
+   ap /= 'subdirectory'   
+   # method 2
+   ap = ap.join('subdirectory')
+   # method 3
+   ap = rio(ap,'subdirectory')
+   # method 4
+
+* Create a Rio from an array of subdirectories
+   dirs = ['adir','subdir1','subdir2']
+   # method 1
+   ario = rio(dirs)
+
+* Create an array of subdirectories from a Rio
+   # method 1
+   anarray = rio('adir/subdir1/subdir2').split
+
+* Append a string to a path
+   # method 1
+   ario = rio('apath') + astring
+   # method 2
+   ario = rio('apath')
+   ario += astring
+
+* create a directory 'links' with a symlink pointing to each .rb file in directory 'lib' (including subdirectories)
+   lib = rio('lib')
+   links = rio('links').delete!.mkdir
+   lib.all.files("*.rb") do |f|
+     f.symlink( f.dirname.sub(/^#{lib}/,links).mkdir )
+   end
+
+----
+
+Suggested Reading
+* RIO::Doc::SYNOPSIS
+* RIO::Doc::INTRO
+* RIO::Rio
+
+=end
+module HOWTO
+end
+end
+end