wishdev-rio 0.4.3.1

data/lib/rio/if/grande_entry.rb

@@ -0,0 +1,379 @@
+#--
+# =============================================================================== 
+# Copyright (c) 2005,2006,2007 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
+#  ruby build_doc.rb
+# from the distribution directory.
+#
+# Suggested Reading
+# * RIO::Doc::SYNOPSIS
+# * RIO::Doc::INTRO
+# * RIO::Doc::HOWTO
+# * RIO::Doc::EXAMPLES
+# * RIO::Rio
+#
+
+
+module RIO
+  module IF
+    module GrandeEntry
+      # Grande Directory Selection Method 
+      #
+      # Sets the rio to return directories. _args_ can be used to select which directories are returned.
+      #  ario.dirs(*args) do |f|
+      #    f.directory?      #=> true
+      #  end
+      #
+      # No aguments selects all directories.
+      # if _args_ are:
+      # Regexp:: selects matching directories
+      # glob::   selects matching directories
+      # Proc::   called for each directory. the directory is processed unless the proc returns false
+      # Symbol:: sent to each directory. Each directory is processed unless the symbol returns false
+      # Fixnum:: matched against the "depth" of the directory
+      #
+      # If a block is given, behaves like <tt>ario.dirs(*args).each(&block)</tt>
+      #
+      # See also #files, #entries, #skipdirs
+      #
+      #  rio('adir').dirs { |frio| ... } # process all directories in 'adir'    
+      #  rio('adir').all.dirs { |frio| ... } #  same thing recursively
+      #  rio('adir').dirs(/^\./) { |frio| ...} # process dot directories
+      #  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 
+      #
+      # If no args are provided selects anything but directories.
+      #  ario.skipdirs do |el|
+      #    el.directory?     #=> false
+      #  end
+      # If args are provided, sets the rio to select directories as with #dirs, but the arguments are
+      # used to determine which directories will *not* be processed
+      #
+      # If a block is given behaves like 
+      #  ario.skipdirs(*args).each(&block)
+      #
+      # See #dirs
+      #
+      #  rio('adir').skipdirs { |ent| ... } # iterate through everything except directories
+      #  rio('adir').skipdirs(/^\./) { |drio| ... } # iterate through directories, skipping dot directories
+      # 
+      #
+      def skipdirs(*args,&block) target.skipdirs(*args,&block); self end
+
+
+      # Grande Directory Entry Selection Method 
+      #
+      # No aguments selects all entries.
+      #
+      # if +args+ are:
+      # Regexp:: selects matching entries
+      # glob::   selects matching entries
+      # Proc::   called for each entry. the entry is processed unless the proc returns false
+      # Symbol:: sent to each entry. Each entry is processed unless the symbol returns false
+      #
+      # If a block is given, behaves like <tt>ario.etries(*args).each(&block)</tt>
+      #
+      # See also #files, #dirs, #skipentries
+      #
+      #  rio('adir').entries { |frio| ... } # process all entries in 'adir'    
+      #  rio('adir').all.entries { |frio| ... } #  same thing recursively
+      #  rio('adir').entries(/^\./) { |frio| ...} # process entries starting with a dot
+      #  rio('adir').entries[/^\./] # return an array of all entries starting with a dot
+      #  rio('adir').entries[:symlink?] # an array of symlinks in 'adir'
+      #
+      def entries(*args,&block) target.entries(*args,&block); self end
+
+      # Grande Directory Entry Rejection Method 
+      #
+      # No aguments rejects all entries.
+      #
+      # Behaves like #entries, except that matching entries are excluded.
+      #
+      # See also #entries, IF::Grande#skip
+      #
+      def skipentries(*args,&block) target.skipentries(*args,&block); self end
+
+      
+      # Grande File Selection Method 
+      #
+      # Configures the rio to process files. +args+ can be used to select which files are returned.
+      #  ario.files(*args) do |f|
+      #    f.file?      #=> true
+      #  end
+      # No aguments selects all files.
+      #
+      # +args+ may be zero or more of the following:
+      #
+      # Regexp:: selects matching files
+      # String:: treated as a glob, and selects matching files
+      # Proc::   called for each file. the file is processed unless the proc returns false
+      # Symbol:: sent to each file. Each file is processed unless the symbol returns false
+      #
+      # +files+ returns the Rio which called it. This might seem counter-intuitive at first. 
+      # One might reasonably assume that
+      #  rio('adir').files('*.rb')
+      # would return files. It does not. It configures the rio to return files and returns
+      # the Rio. This enables chaining for further configuration so constructs like
+      #  rio('adir').all.files('*.rb').norecurse('.svn')
+      # are possible.
+      #
+      # If a block is given, behaves like 
+      #  ario.files(*args).each
+      #
+      # 
+      # See also #dirs, #entries, #skipfiles
+      #
+      #  rio('adir').files { |frio| ... } # process all files in 'adir'    
+      #  rio('adir').all.files { |frio| ... } #  same thing recursively
+      #  rio('adir').files('*.rb') { |frio| ...} # process .rb files
+      #  rio('adir').files['*.rb'] # return an array of .rb files
+      #  rio('adir').files[/\.rb$/] # same thing using a regular expression
+      #  rio('adir').files[:symlink?] # an array of symlinks to files
+      #  rio('adir').files >> rio('other_dir') # copy files to 'other_dir'
+      #  rio('adir').files('*.rb') >> rio('other_dir') # only copy .rb files
+      #
+      # For Rios that refer to files, <tt>files(*args)</tt> causes the file to be processed only if 
+      # it meets the criteria specified by the args.
+      #
+      #  rio('afile.z').files['*.z'] #=> [rio('afile.z')]
+      #  rio('afile.q').files['*.z'] #=> []
+      #
+      # === Example Problem
+      #
+      # Fill the array +ruby_progs+ with all ruby programs in a directory and its subdirectories, 
+      # skipping those in _subversion_ (.svn) directories. 
+      #
+      #  ruby_progs = []
+      # 
+      # For the purposes of this problem, a Ruby program is defined as a file ending with .rb or a file
+      # that is executable and whose shebang line contains 'ruby':
+      #
+      #  is_ruby_exe = proc{ |f| f.executable? and f.gets =~ /^#!.+ruby/ }
+      #
+      # ==== Solution 1. Use the subscript operator.
+      #
+      #  ruby_progs = rio('adir').norecurse('.svn').files['*.rb',is_ruby_exe]
+      #
+      # Explanation:
+      #
+      # 1. Create the Rio
+      #
+      #    Create a Rio for a directory
+      #     rio('adir')
+      #
+      # 2. Configure the Rio
+      #
+      #    Specify recursion and that '.svn' directories should not be included.
+      #     rio('adir').norecurse('.svn')
+      #    Select files
+      #     rio('adir').norecurse('.svn').files
+      #    Limit to files ending with '.rb'
+      #     rio('adir').norecurse('.svn').files('*.rb')
+      #    Also allow files for whom +is_ruby_exe+ returns true
+      #     rio('adir').norecurse('.svn').files('*.rb',is_ruby_exe)
+      #
+      # 3. Do the I/O
+      #
+      #    Return an array rather than iterating thru them
+      #     ruby_progs = rio('adir').norecurse('.svn').files['*.rb',is_ruby_exe]
+      #
+      # ==== Solution  2. Use the copy-to operator
+      #
+      #  rio('adir').files('*.rb',is_ruby_exe).norecurse('.svn') > ruby_progs
+      #
+      # Explanation:
+      #
+      # 1. Create the Rio
+      #
+      #    Create a Rio for a directory
+      #     rio('adir')
+      #
+      # 2. Configure the Rio
+      #
+      #    Select only files
+      #     rio('adir').files
+      #    Limit to files ending with '.rb'
+      #     rio('adir').files('*.rb')
+      #    Also allow files for whom +is_ruby_exe+ returns true
+      #     rio('adir').files('*.rb',is_ruby_exe)
+      #    Specify recursion and that '.svn' directories should not be included.
+      #     rio('adir').files('*.rb',is_ruby_exe).norecurse('.svn')
+      #
+      # 3. Do the I/O
+      #
+      #    Copy the Rio to ruby_progs
+      #     rio('adir').files('*.rb',is_ruby_exe).norecurse('.svn') > ruby_progs
+      #
+      # ==== Example Discussion
+      #
+      # Note that the only difference between Step 2 of Solution 1 and that of Solution 2 is 
+      # the order of the configuration methods. Step 2 of Solution 1 would have worked equally 
+      # well:
+      #
+      #  rio('adir').norecurse('.svn').files('*.rb',is_ruby_exe) > ruby_progs
+      #
+      # Furthermore if our problem were changed slightly and instead of having our results
+      # ending up in an array, we wished to iterate through them, we could use:
+      #
+      #  rio('adir').norecurse('.svn').files('*.rb',is_ruby_exe) { |ruby_prog_rio| ... }
+      #
+      # Note the similarities. In fact, solution 1 could have been written:
+      #  
+      #  rio('adir').norecurse('.svn').files('*.rb',is_ruby_exe).to_a
+      # or
+      #  rio('adir').norecurse('.svn').files('*.rb',is_ruby_exe)[]
+      #
+      # Passing the arguments for +files+ to the subscript operator is syntactic sugar.
+      # The subscript operator does not really take any arguments of its own. It always
+      # passes them to the most recently called of the grande selection methods (or the
+      # default selection method, if none have been called). So,
+      #
+      #  rio('adir').files['*.rb']
+      # is a shortcut for
+      #  rio('adir').files('*.rb').to_a
+      #
+      # and
+      #
+      #  rio('adir')['*.rb']
+      # is a shortcut for
+      #  rio('adir').entries('*.rb').to_a
+      #
+      # and
+      #
+      #  rio('afile').lines[0..10]
+      # is a shortcut for
+      #  rio('afile').lines(0..10).to_a
+      #
+      # And so on.
+      # 
+      #
+      #
+      def files(*args,&block) target.files(*args,&block); self end
+
+      # Grande File Exclude Method 
+      #
+      # If no args are provided selects anything but files.
+      #  ario.skipfiles do |el|
+      #    el.file?     #=> false
+      #  end
+      # If args are provided, sets the rio to select files as with #files, but the arguments are
+      # used to determine which files will *not* be processed
+      #
+      # If a block is given behaves like <tt>ario.skipfiles(*args).each(&block)</tt>
+      #
+      # See #files, IF::Grande#skip
+      #
+      #  rio('adir').skipfiles { |ent| ... } # iterate through everything except files
+      #  rio('adir').skipfiles('*~') { |frio| ... } # iterate through files, skipping those ending with a tilde
+      # 
+      #
+      def skipfiles(*args,&block) target.skipfiles(*args,&block); self end
+
+
+      # Returns +true+ if the rio is in +all+ (recursive) mode. See #all
+      #
+      #  adir = rio('adir').all.dirs
+      #  adir.all? # true
+      #  adir.each do |subdir|
+      #    subdir.all?  # true
+      #  end
+      #
+      #  rio('adir').all? # false
+      #  
+      def all?() target.all?() end
+
+
+      # Grande Directory Recursion Method
+      # 
+      # Sets the Rio to all mode (recursive)
+      # 
+      # When called with a block, behaves as if all.each(&block) had been called
+      # 
+      # +all+ causes subsequent calls to +files+ or +dirs+ to be applied recursively
+      # to subdirectories
+      #
+      #  rio('adir').all.files('*.[ch]').each { |file| ... } # process all c language source files in adir 
+      #                                                      # and all subdirectories of adir
+      #  rio('adir').all.files(/\.[ch]$/) { |file| ... }     # same as above
+      #  rio('adir').files("*.[ch]").all { |file| ... }      # once again
+      #  rio('adir').all.files["*.[ch]"]                     # same, but return an array instead of iterating
+      #  
+      def all(arg=true,&block) target.all(arg,&block); self end
+
+
+      # Grande Directory Recursion Selection Method
+      # 
+      # Sets the Rio to recurse into directories like #all. If no args are provided behaves like #all. 
+      # If args are provided, they are processed like #dirs to select which subdirectories should 
+      # be recursed into. #recurse always implies #all.
+      #
+      # +args+ may be one or more of:
+      # Regexp::  recurse into matching subdirectories
+      # glob::    recurse into matching subdirectories
+      # Proc::    called for each directory. The directory is recursed into unless the proc returns false
+      # Symbol::  sent to each directory. Each directory is recursed into unless the symbol returns false
+      # Fixnum::  recurse into directories only at the given depth
+      # Range::   recurse into directories at a range of depths
+      #
+      # If a block is given, behaves like <tt>ario.recurse(*args).each(&block)</tt>
+      #
+      # See also #norecurse, #all, #dirs
+      #
+      #  rio('adir').recurse('test*') { |drio| ... } # process all entries and all entries in subdirectories
+      #                                              # starting with 'test' -- recursively
+      #
+      def recurse(*args,&block) target.recurse(*args,&block); self end
+
+
+      # Grande Directory Recursion Exclude Method
+      # 
+      # Sets the Rio to recurse into directories like #all. If no args are provided, no
+      # directories will be recursed into. If args are provided, behaves like #recurse, except
+      # that matching directories will *not* be recursed into
+      #
+      #  rio('adir').norecurse('.svn') { |drio| ... } # recurse, skipping subversion directories
+      #
+      #  rio('adir').norecurse(3) {|drio| ... } # only recurse 2 levels deep into a directory structure
+      #
+      def norecurse(*args,&block) target.norecurse(*args,&block); self end
+
+
+    end
+  end
+end
+
+module RIO
+  class Rio
+    include RIO::IF::GrandeEntry
+  end
+end

data/lib/rio/if/grande_stream.rb

@@ -0,0 +1,693 @@
+#--
+# =============================================================================== 
+# Copyright (c) 2005,2006,2007 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
+#  ruby build_doc.rb
+# from the distribution directory.
+#
+# Suggested Reading
+# * RIO::Doc::SYNOPSIS
+# * RIO::Doc::INTRO
+# * RIO::Doc::HOWTO
+# * RIO::Doc::EXAMPLES
+# * RIO::Rio
+#
+
+
+module RIO
+  module IF
+    module GrandeStream
+
+      # Calls #lines(*args) but when used with the subscript operator
+      # returns the first element of the returned array instead of the array.
+      #
+      # If afile contains ["line 0\n","line 1\n"]
+      #  rio('afile').line[0]       #=> "line 0\n"
+      #  rio('afile').line[1]       #=> "line 1\n"
+      #  rio('afile').lines[0]      #=> ["line 0\n"]
+      #  rio('afile').lines[1]      #=> ["line 1\n"]
+      #  rio('afile').lines[0][0]   #=> "line 0\n"
+      #  rio('afile').lines[1][0]   #=> "line 1\n"
+      def line(*args,&block) target.line(*args,&block); self end
+
+
+      # See #line.
+      def record(*args,&block) target.record(*args,&block); self end
+
+
+      # See #line.
+      def row(*args,&block) target.row(*args,&block); self end
+      
+
+      # Sets the rio to read lines and returns the Rio
+      # 
+      # If called with a block behaves as if <tt>lines(*args).each(&block)</tt> had been called
+      # 
+      # +lines+ returns the Rio which called it. This might seem counter-intuitive at first. 
+      # One might reasonably assume that
+      #  rio('adir').lines(0..10)
+      # would return lines. It does not. It configures the rio to return lines and returns
+      # the Rio. This enables chaining for further configuration so constructs like
+      #  rio('afile').lines(0..10).skiplines(/::/)
+      # are possible.
+      #
+      # If args are provided they may be one or more of the following:
+      # Regexp::  any matching record will be processed
+      # Range::   specifies a range of records (zero-based) to be included
+      # Integer:: interpreted as a one element range of lines to be processed
+      # 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
+      # Array::   an array of other selectors. records are selected unless any of the matches fail.
+      #
+      #  rio('f.txt').lines(/^\s*#/) { |line| ... } # iterate over comment-only lines
+      #  rio('f.txt').lines(/^\s*#/).each { |line| ... } # same as above
+      #
+      #  rio('f.txt').lines(1,7..9) > rio('anotherfile.txt') # copy lines 1,7,8 and 9 to anotherfile.txt
+      #
+      #  rio('f.txt').lines(1...3).to_a # return an array containing lines 1 and 2 of f.txt
+      #  rio('f.txt').lines[1...3]      # same thing
+      #
+      def lines(*args,&block) target.lines(*args,&block); self end
+
+      # 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::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#[]
+      # 
+      # If called with a block behaves as if <tt>ario.bytes(n,*args).each(&block)</tt> had been called
+      # 
+      #  rio('f.dat').bytes(1024) { |rec| ... }      # iterate through f.txt 1024 bytes at a time
+      #  rio('f.dat').bytes(1024).each { |rec| ... } # same as above
+      #
+      #  rio('f.dat').bytes(1024,0..4) { |rec| ... } # iterate through the first five 1024 byte blocks
+      #
+      #  rio('f.dat').bytes(64).to_a # return the contents of f.dat as an array of 64 byte chunks
+      #
+      #  rio('f.dat').bytes(512).records(0,7..9) > rio('dfile.dat') # copy 512-byte blocks 0,7,8 and 9 to dfile.dat
+      #
+      #  rio('f.dat').bytes(2048).records[0...10] # return an array containing the first 10 2K blocks of f.dat
+      #  rio('f.dat').bytes(2048)[0...10]         # same thing
+      #
+      #  rio('f.dat').bytes { |bytestr| ... } # iterate over f.dat 1 byte at a time. 
+      #  rio('f.dat').bytes[0...100]          # returns an array of the first 100 bytes of f.dat
+      #
+      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::GrandeStream#getrec
+      # 
+      # If called with a block behaves as if <tt>records(*args).each(&block)</tt> had been called
+      # 
+      # Returns the Rio
+      #
+      # If no args are provided, all records are selected. 
+      # What constitutes a record is affected by #lines,#bytes,
+      # 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::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
+      # Array::   an array of any of above. All must match for a line to be included
+      #
+      # Any other argument type is compared with the record using its <tt>===</tt> method.
+      #
+      # If the argument is a ::Proc it may be called with one, two or three paramaters.
+      # 1. the record
+      # 2. the recno (optional)
+      # 3. the rio (optional)
+      #
+      # Note in the following examples that since +lines+ is the default <tt>ario.records(*args)</tt>
+      # is effectively the same as <tt>ario.lines(*args)</tt>.
+      #
+      #  rio('afile').records(0) { |line| ... } # iterate over the first line of 'afile'
+      #  rio('afile').records(0,5..7)) { |line| ... } # iterate over lines 0,5,6 and 7
+      #  rio('afile').records(/Zippy/) { |line| ... } # iterate over all lines containing 'Zippy'
+      #
+      # 
+      #  rio('f.csv').puts!(["h0,h1","f0,f1"]) # Create f.csv                
+      #
+      #  rio('f.csv').csv.records[]    #==>[["h0", "h1"], ["f0", "f1"]]
+      #  rio('f.csv').csv.lines[]      #==>["h0,h1\n", "f0,f1\n"]
+      #  rio('f.csv').csv.records[0]   #==>[["h0", "h1"]]
+      #
+      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::GrandeStream#getrec
+      # 
+      # If called with a block behaves as if <tt>skiprecords(*args).each(&block)</tt>
+      # had been called
+      # 
+      # Returns the Rio
+      #
+      # See also #records, #skiplines, #lines, IF::Grande#skip
+      #
+      # If no args are provided, no records are rejected. What constitutes a record is affected by #lines,#bytes,
+      # 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 not be processed
+      # Integer:: specifies a record-number (zero-based) to be skipped
+      # Range::   specifies a range of records (zero-based) to be excluded
+      # Proc::    a proc which will be called for each record, records are excluded unless nil or false is returned
+      # Symbol::  a symbol which will _sent_ to each record, records are excluded unless nil or false is returned
+      # Array::   an array of any of the above, all of which must match for the array to match.
+      #
+      # Note in the following examples that since +lines+ is the default record 
+      # type <tt>ario.skiprecords(*args)</tt> is effectively 
+      # the same as <tt>ario.skiplines(*args)</tt>.
+      #
+      #  rio('afile').skiprecords(0) { |line| ... } # iterate over all but the first line of 'afile'
+      #  rio('afile').skiprecords(0,5..7)) { |line| ... } # don't iterate over lines 0,5,6 and 7
+      #  rio('afile').skiprecords(/Zippy/) { |line| ... } # skip all lines containing 'Zippy'
+      #  rio('afile').chomp.skiplines(:empty?) { |line| ... } # skip empty lines
+      #
+      def skiprecords(*args,&block) target.skiprecords(*args,&block); self end
+
+
+      # Sets the Rio to read lines and specifies lines 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>skiplines(*args).each(&block)</tt> had been called
+      # 
+      # Returns the Rio
+      #
+      # See also #lines, #records, IF::Grande#skip
+      #
+      # If no args are provided, no lines are rejected.
+      #
+      # If args are provided they may be one or more of the following:
+      # Regexp::  any matching line will not be processed
+      # Integer:: specifies a line-number (zero-based) to be skipped
+      # Range::   specifies a range of lines (zero-based) to be excluded
+      # Proc::    a proc which will be called for each line, lines are excluded unless nil or false is returned
+      # Symbol::  a symbol which will _sent_ to each line, lines are excluded unless nil or false is returned
+      # Array::   an array of any of above. All must match for a line to be included
+      #
+      #  rio('afile').skiplines(0) { |line| ... } # iterate over all but the first line of 'afile'
+      #  rio('afile').skiplines(0,5..7)) { |line| ... } # don't iterate over lines 0,5,6 and 7
+      #  rio('afile').skiplines(/Zippy/) { |line| ... } # skip all lines containing 'Zippy'
+      #  rio('afile').chomp.skiplines(:empty?) { |line| ... } # skip empty lines
+      #
+      def skiplines(*args,&block) target.skiplines(*args,&block); self end
+
+
+      # Sets the Rio to read rows and specifies rows which should be iterated through 
+      # 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::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
+
+
+      # Temporarily set the Rio to read records, and call IF::Grande#get
+      #
+      # See also IF::GrandeStream#records, IF::GrandeStream#lines, IF::Grande#each, IF::Grande#[]
+      #
+      def getrec() target.getrec() end
+
+
+      # Temporarily set the Rio to read rows, and call IF::Grande#get
+      #
+      # See also IF::GrandeStream#rows, IF::GrandeStream#lines, IF::Grande#each, IF::Grande#[]
+      #
+      def getrow() target.getrow() end
+
+
+      # Temporarily set the Rio to read lines, and call IF::Grande#get
+      #
+      # See also IF::GrandeStream#records, IF::GrandeStream#lines, IF::Grande#each, IF::Grande#[]
+      #
+      def getline() target.getline() end
+
+
+      # Slurps the contents of the rio into a string.
+      #
+      #  astring = rio('afile.txt').contents # slurp the entire contents of afile.txt into astring
+      # 
+      def contents() target.contents() end
+
+
+      # Writes a single record to a Rio
+      def putrec(el) target.putrec(el) end
+
+
+      # Sets the implicit output mode to 'a'.
+      # 
+      # This is the mode Rio will use for output when no mode is specified
+      #
+      # Rios normally don't need to be opened or have their open mode specified. A Rio determines the mode
+      # based on the file system object and on the action specified. For instance when a Rio encounters
+      # a +read+ on a file it opens the file for reading using File#open and calls IO#read; when it encounters
+      # a +read+ on a directory it knows to use Dir#open and call Dir#read. When it encounters a IF::RubyIO#puts, it knows
+      # to perform a File#open, and call IO#puts on the returned handle. By default when a method requires
+      # a file be opened for writing the file is opened with a mode of 'w'. #a changes this implicit 
+      # output mode to 'a'. 
+      #
+      # Note that this is not the same as setting the output mode *explicitly*, as in rio('afile').mode('a').
+      # When the mode is set explicitly using IF::RubyIO#mode, the mode specified will be used regardless of
+      # the operation being performed. The #a method only affects how Rio opens a file when
+      # it sees an operator that requires writing, and must determine for itself how to open it.
+      #
+      #  rio('afile').puts!('Hello World') # call IO#puts on a file handle opened in 'w' mode
+      #  rio('afile').a.puts!('Hello World') # call IO#puts on a file handle opened in 'a' mode
+      # 
+      # See also #a!, #w! for setting the implicit output mode 'a+' and 'w+' respectively
+      #
+      # The methods #a, #a!, #w, #w!, #r, #r! set the +implicit+ open mode 
+      # to 'a','a+','w','w+','r' and 'r+' respectively. 
+      #
+      # See also #+@
+      def a() target.a(); self end
+
+
+      # Unary Plus. Alternate form of #a
+      #  rio('f1') > rio('f2')     # copy f1 to f2
+      #  rio('f1') > rio('f2').a   # append f1 to f2
+      #  rio('f1') > +rio('f2')    # same thing
+      #  rio('f1') >> rio('f2')    # same thing
+      # 
+      def +@()
+        RIO::no_warn { +target }
+        self
+      end
+
+
+      # Sets the implicit output mode to 'a+'. 
+      # 
+      # The implicit output mode is the mode Rio will use for output when no mode is specified.
+      #
+      # Returns the Rio
+      #
+      # See the discussion for #a. 
+      #
+      def a!() target.a!(); self end
+
+
+      # Sets the implicit input mode to 'r'. 
+      # 
+      # The implicit input mode is the mode Rio will use for input when no mode is specified.
+      #
+      # Returns the Rio
+      #
+      # See the discussion for #a. 
+      #
+      # Since 'r' is the implicit input mode used by default, this method
+      # is probably uneeded.
+      #
+      def r() target.r(); self end
+
+
+      # Sets the implicit input mode to 'r+'. 
+      # 
+      # The implicit input mode is the mode Rio will use for input when no mode is specified.
+      #
+      # Returns the Rio
+      #
+      # See the discussion for #a. 
+      #
+      def r!() target.r!(); self end
+
+
+      # Sets the implicit output mode to 'w'. 
+      # 
+      # The implicit output mode is the mode Rio will use for output when no mode is specified.
+      #
+      # Returns the Rio
+      #
+      # See the discussion for #a. 
+      #
+      # Since 'w' is the implicit output mode used by default, this method
+      # is uneeded, but is provided for completeness..
+      #
+      def w() target.w(); self end
+
+
+      # Sets the implicit output mode to 'w+'. 
+      # 
+      # The implicit output mode is the mode Rio will use for output when no mode is specified.
+      #
+      # Returns the Rio
+      #
+      #  rio(?-,'cat').w!.puts!("Hello Kitty").readline #=> "Hello Kitty"
+      #
+      # See the discussion for #a. 
+      #
+      def w!() target.w!(); self end
+
+
+      # Set the Rio's closeoneof mode. 
+      #
+      #  ario.closeoneof(&block) => ario
+      #
+      # +closeoneof+ causes a Rio to be closed automatically whenever the end of
+      # file is reached. This affects# all methods that read from 
+      # a rio (IF::RubyIO#readlines, #to_a, IF::Grande#each IF::RubyIO#gets etc.)
+      # Because +closeoneof+ must be on for many of Rio's most useful idioms,
+      # it is on by default. +closeoneof+ can be turned off using #nocloseoneof.
+      # 
+      # If a block is given behaves like <tt>ario.closeoneof.each(&block)</tt> had been called
+      # 
+      # Returns the Rio
+      # 
+      #  ario = rio('afile')
+      #  lines = ario.readlines
+      #  ario.closed?     #=> true
+      #
+      #  ario = rio('afile').nocloseoneof
+      #  lines = ario.readlines
+      #  ario.closed?     #=> false
+      #  ario.close       # must be explicitly closed
+      #
+      # +closeoneof+ is ignored by directory Rios, however, setting it on a directory Rio 
+      # causes each file Rio returned while iterating to inherit the directory's setting
+      #
+      #  rio('adir').files do |file|
+      #    file.closeoneof?    #=> true
+      #  end
+      #
+      #  rio('adir').files.nocloseoneof do |file|
+      #    file.closeoneof?    #=> false
+      #  end
+      #
+      #  rio('adir').files.nocloseoneof['*.rb'] # array of .rb file Rios in adir with closeoneof off
+      #
+      #  drio = rio('adir').files
+      #  frio1 = drio.read
+      #  frio1.closeoneof?    #=> true
+      #  drio.nocloseoneof
+      #  frio2 = drio.read 
+      #  frio2.closeoneof?    #=> false
+      #
+      #  
+      def closeoneof(arg=true,&block) target.closeoneof(arg,&block); self end
+
+
+      # Set the Rio's closeoneof mode to false
+      #  ario.nocloseoneof(&block) => ario
+      # See #closeoneof
+      # 
+      # If a block is given behaves like
+      #  ario.nocloseoneof.each(&block)
+      # 
+      # Returns the Rio
+      # 
+      #  ario = rio('afile')
+      #  lines = ario.to_a
+      #  ario.closed?     #=> true
+      #
+      #  ario = rio('afile').nocloseoneof
+      #  lines = ario.to_a
+      #  ario.closed?     #=> false
+      #  ario.close       # must be explicitly closed
+      def nocloseoneof(arg=false,&block) target.nocloseoneof(arg,&block); self end
+
+
+      # Query a Rio's closeoneof mode
+      #  ario.closeoneof?    => true or false
+      #
+      # See #closeoneof and #nocloseoneof
+      # 
+      #  ario = rio('afile')
+      #  ario.closeoneof?  #=> true
+      #  lines = ario.to_a
+      #  ario.closed?     #=> true
+      #
+      #  ario = rio('afile').nocloseoneof
+      #  ario.closeoneof?  #=> false
+      #  lines = ario.to_a
+      #  ario.closed?     #=> false
+      #  ario.close       # must be explicitly closed
+      def closeoneof?() target.closeoneof?() end
+
+
+
+      # Set a Rio's closeoncopy mode
+      #
+      #  ario.closeoncopy(&block) => ario
+      #
+      # #closeoncopy causes the Rio being written to to be closed when using 
+      # a grande copy operator. While #closeoneof causes all Rio's to be closed
+      # when reading to the end of file, it does not affect Rios being written to.
+      # #closeoncopy only affects the Rio being written to and only when a 
+      # grande copy operator is used. +closeoncopy+ is on by default, with one exception. 
+      # 
+      #  dest = rio('destfile')
+      #  dest < rio('srcfile')
+      #  dest.closed?   #=> true
+      #
+      #  dest = rio('destfile').nocloseoncopy
+      #  dest < rio('srcfile')
+      #  dest.closed?   #=> false
+      #  dest.close     # must be explicitly closed
+      # 
+      #  dest = rio('destfile')
+      #  dest.print(rio('srcfile').contents)
+      #  dest.closed?   #=> false (IF::RubyIO#print is not a copy operator)
+      #  dest.close
+      #
+      #
+      # ==== The Exception
+      #
+      # When a block is passed directly to the rio constructor +closeoncopy+ is turned off.
+      #
+      #  rio('afile') { |file|
+      #    file.closeoncopy? #=> false
+      #    file < a_string
+      #    file.closed?  #=> false
+      #  }
+      #  # The file is now closed. See IF::GrandeStream#rio for more informatioin
+      # 
+      # ==== Why?
+      #
+      # Some of my favorite Rio idioms are its copy one-liners
+      #
+      #  rio('afile') < a_string # put a string into a file
+      #  rio('afile') < an_array # put an array into a file
+      #  rio('afile') < rio('anotherfile').lines(0..9) # copy the first 10 lines of anotherfile into afile
+      #  rio('afile.gz').gzip < rio('anotherfile').lines(0..9) # same thing into a gzipped file
+      #
+      # In each of these cases, 'afile' would remain open after the copy and furthermore
+      # since the destination Rio was not saved in a variable, There is no way to close file.
+      # Without closeoncopy Something like this would be required:
+      #
+      #  ario = rio('afile')
+      #  ario < something_else
+      #  ario.close
+      #
+      # Or this...
+      #
+      #  ario = rio('afile') < something_else
+      #  ario.close
+      #
+      # Or this...
+      #
+      #  (rio('afile') < something_else).close
+      # One line, but ugly, and prone to error.
+      #
+      # What I want is this:
+      #
+      #  rio('afile') < something_else
+      #
+      # Simple. I want to copy this to that, I point the arrow and it works.
+      #
+      # In perl the rio's destructor would be called, because there are no remaining references to the Rio
+      # However, it my understanding and experience that in Ruby the finalizer will not necessarily be 
+      # called at this point. 
+      #
+      def closeoncopy(arg=true,&block) target.closeoncopy(arg,&block); self end
+
+
+      # Set a Rio's closeoncopy mode to false
+      #
+      #     ario.nocloseoncopy(&block) => ario
+      #
+      # See #closeoncopy
+      #
+      def nocloseoncopy(arg=false,&block) target.nocloseoncopy(arg,&block); self end
+
+
+      # Query a Rio's closeoncopy mode
+      #
+      #     ario.closeoncopy? => true or false
+      #
+      # See #closeoncopy
+      #
+      def closeoncopy?() target.closeoncopy?() end
+
+
+      # Turns off both closeoneof and closeoncopy.
+      # Equivelent to:
+      #  ario.nocloseoneof.nocloseoncopy
+      # Returns the Rio
+      #  ario.noautoclose(&block) => ario
+      # If a block is given, acts as if 
+      #  ario.noautoclose.each(&block) 
+      # had been called.
+      #
+      # See #nocloseoneof and #nocloseoncopy
+      #
+      def noautoclose(arg=false,&block) target.noautoclose(arg,&block); self end
+
+
+      # Queries the Rio's chomp-mode.
+      # See #chomp.
+      #
+      def chomp?() target.chomp?() end
+
+
+      # Sets the Rio to chomp lines and returns the Rio
+      # 
+      # When called with a block, behaves as if <tt>chomp.each(&block)</tt> had been called
+      #
+      # chomp causes lines returned by each, to_a, readlines, readline, gets, each_line etc.
+      # to be chomped before iterated over or assigned
+      #
+      #  rio('f.txt').chomp.each { |line| ... } # Block is called with lines already chomped
+      #
+      #  rio('f.txt').chomp { |line| ... } # same as above
+      #
+      #  rio('f.txt').chomp.to_a # returns the lines of f.txt chomped
+      # 
+      #  rio('f.txt').chomp.lines(1..2).to_a # returns an array containg lines 1 and 2 of the file after being chomped
+      #
+      #    This would have similar results to rio('f.txt').lines(1..2).to_a.map{ |line| line.chomp}
+      #
+      #  rio('f.txt').lines(1..2).chomp.to_a # same as above
+      #
+      #  rio('f.txt').chomp.readlines # returns the lines of f.txt chomped
+      #
+      #  rio('f.txt').chomp.gets # returns the first line of 'f.txt' chomped
+      #
+      #  rio('f.txt').chomp > an_array # copies the chomped lines of f.txt into an_array
+      #
+      #  # fill an array with all the 'require' lines in all the .rb files (recursively) in adir
+      #  # chomping each line
+      #
+      #  an_array = []
+      #  rio('adir').chomp.all.files("*.rb") { |file| 
+      #    an_array += file.lines[/^\s*require/]
+      #  }
+      #
+      #  or simply
+      #
+      #  an_array = rio('adir').chomp.all.files("*.rb").lines[/^\s*require/]
+      #
+      def chomp(arg=true,&block) target.chomp(arg,&block); self end
+
+
+      # Queries the Rio's strip-mode.
+      # See #strip.
+      #
+      def strip?() target.strip?() end
+
+
+      # Sets the Rio to strip lines and returns the Rio
+      # 
+      # When called with a block, behaves as if strip.each(&block) had been called
+      #
+      # +strip+ causes lines returned by each, to_a, readlines, readline, gets, each_line etc.
+      # to be stripped with String#strip before iterated over or assigned
+      #
+      #  ans = rio(?-).print("A Prompt> ").strip.gets # prompt the user
+      #
+      # See also #chomp
+      def strip(arg=true,&block) target.strip(arg,&block); self end
+
+
+      # Sets the Rio to gzip mode. 
+      #     ario.gzip    #=> ario
+      # If applied to a Rio that is being read from Reads
+      # through a <tt>Zlib::GzipReader</tt>; If applied to a Rio that is being written to 
+      # writes through a <tt>Zlib::GzipWriter</tt>.
+      #
+      # Returns the Rio
+      #
+      # If a block is given, acts like <tt>ario.gzip.each(&block)</tt>
+      #
+      #  rio('afile') > rio('afile.gz').gzip # gzip a file
+      #  rio('afile.gz').gzip < rio('afile') # same thing
+      #
+      #  rio('afile.gz').gzip > rio('afile') # ungzip a file
+      #  rio('afile') < rio('afile.gz').gzip # same thing
+      #
+      #  rio('afile.gz').gzip.chomp { |line| ...} # process each chomped line of a gzipped file
+      #  rio('afile.gz').gzip[0..9] # an array containing the first 10 lines of a gzipped file
+      #
+      def gzip(&block) target.gzip(true,&block); self end
+
+
+      # Queries the Rio's gzip-mode
+      #  ario.gzip?     #=> true or false
+      # See #gzip
+      #
+      def gzip?() target.gzip?() end
+
+
+      # #inputmode?
+      #
+      #
+      #def inputmode?() target.inputmode?() end
+
+
+
+      # This causes String#split(arg) to be called on every line
+      # before it is returned. An array of the split lines is
+      # returned when iterating
+      #
+      #  rio('/etc/passwd').split(':').columns(0,2) { |ary|
+      #    username,uid = ary
+      #  }
+      #  
+      #  rio('/etc/passwd').split(':').columns(0,2).to_a #=> [[user1,uid1],[user2,uid2]]
+      #
+      # See also IF::Grande#split
+      #  
+      def splitlines(*args,&block) target.splitlines(*args,&block) end
+
+
+
+      # #outputmode?
+      #
+      #
+      #def outputmode?() target.outputmode?() end
+
+
+    end
+  end
+end
+module RIO
+  class Rio
+    include RIO::IF::GrandeStream
+  end
+end