rio 0.3.7 → 0.3.8

data/lib/rio/doc/INTRO.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================== 
-# Copyright (c) 2005, Christopher Kleckner
+# Copyright (c) 2005, 2006 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -22,7 +22,7 @@
 #++
 #
 # To create the documentation for Rio run the command
-#  rake rdoc
+#  ruby build_doc.rb
 # from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
 #
 # Suggested Reading
@@ -47,8 +47,8 @@ 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 accomplished in line or
-two of code.
+allows many application level IO tasks to be expressed succinctly.
+
 
 Rio functionality can be broadly broken into three categories
 * path manipulation
@@ -70,7 +70,7 @@ the presence of a block as an implied +each+.
 == Using a Rio
 
 Using a Rio can be described as having 3 steps:
-* Creating a Rio (using the constructor or as the result of one of the path manipulation methods)
+* Creating a Rio
 * Configuring a Rio 
 * Rio I/O
 
@@ -93,64 +93,97 @@ that have a path and those that don't.
 
 To create a Rio that has a path the arguments to +rio+ may be:
 
-* a string representing the entire path. The separator used for Rios is as specified in RFC1738 ('/').
+* a string representing the entire path. The separator used for Rios
+  is as specified in RFC1738 ('/').
+
    rio('adir/afile')
+
 * a string representing a fully qualified +file+ URI as per RFC1738
+
    rio('file:///atopleveldir/adir/afile')
+
 * a +URI+ object representing a +file+ or generic +URI+
+
    rio(URI('adir/afile'))
+
 * the components of a path as separate arguments
+
    rio('adir','afile')
+
 * the components of a path as an array
+
    rio(%w/adir afile/)
+
 * another Rio
+
    another_rio = rio('adir/afile')
    rio(another_rio)
+
 * any object whose +to_s+ method returns one of the above
+
    rio(Pathname.new('apath'))
-* any combination of the above either as separate arguments or as elements of an array,
+
+* any combination of the above either as separate arguments or as
+  elements of an array,
+
    another_rio = rio('dir1/dir2')
    auri = URI('dir4/dir5)
    rio(another_rio,'dir3',auri,'dir6/dir7')
 
 ===== Creating a Rio that refers to a web page
 
-To create a Rio that refers to a web page the arguments to +rio+ may be:
+To create a Rio that refers to a web page the arguments to +rio+ may
+be:
 
 * a string representing a fully qualified +http+ URI
+
    rio('http://ruby-doc.org/index.html')
+
 * a +URI+ object representing a +http+ +URI+
+
    rio(URI('http://ruby-doc.org/index.html'))
+
 * either of the above with additional path elements
+
    rio('http://www.ruby-doc.org/','core','classes/Object.html')
    
+
 ===== Creating a Rio that refers to a file or directory on a FTP server
 
-To create a Rio that refers to a file on a FTP server the arguments to +rio+ may be:
+To create a Rio that refers to a file on a FTP server the arguments to
++rio+ may be:
 
 * a string representing a fully qualified +ftp+ URI
+
    rio('ftp://user:password@ftp.example.com/afile.tar.gz')
+
 * a +URI+ object representing a +ftp+ +URI+
+
    rio(URI('ftp://ftp.example.com/afile.tar.gz'))
+
 * either of the above with additional path elements
+
    rio('ftp://ftp.gnu.org/pub/gnu','emacs','windows','README')
    
 ==== Creating Rios that do not have a path
 
-To create a Rio without a path, the first argument to +rio+ is usually a single
-character.
+To create a Rio without a path, the first argument to +rio+ is usually
+a single character.
 
 ===== Creating a Rio that refers to a clone of your programs stdin or stdout.
 
-<tt>rio(?-)</tt> (mnemonic: '-' is used by some Unix programs to specify stdin or stdout in place of a file)
+<tt>rio(?-)</tt> (mnemonic: '-' is used by some Unix programs to
+specify stdin or stdout in place of a file)
 
-Just as a Rio that refers to a file, does not know whether that file will be opened for reading or
-writing until an io operation is specified, a <tt>stdio:</tt> Rio does not know whether it will connect
-to stdin or stdout until an I/O operation is specified. 
+Just as a Rio that refers to a file, does not know whether that file
+will be opened for reading or writing until an io operation is
+specified, a <tt>stdio:</tt> Rio does not know whether it will connect
+to stdin or stdout until an I/O operation is specified.
 
 ===== Creating a Rio that refers to a clone of your programs stderr.
 
-<tt>rio(?=)</tt> (mnemonic: '-' refers to fileno 1, so '=' refers to fileno 2)
+<tt>rio(?=)</tt> (mnemonic: '-' refers to fileno 1, so '=' refers to
+fileno 2)
 
 ===== Creating a Rio that refers to an arbitrary IO object.
 
@@ -195,14 +228,15 @@ or
 or
  rio('tcp://hostname:port')
 
-===== Creating a Rio that runs an external program and connects to its
-      stdin and stdout
+===== Creating a Rio that runs an external program and connects to its stdin and stdout
 
-<tt>rio(?-,cmd)</tt> (mnemonic: '-' is used by some Unix programs to specify stdin or stdout in place of a file)
+<tt>rio(?-,cmd)</tt> (mnemonic: '-' is used by some Unix programs to
+specify stdin or stdout in place of a file)
 
 or
 
-<tt>rio(?`,cmd)</tt> (mnemonic: '`' (backtick) runs an external program in ruby)
+<tt>rio(?`,cmd)</tt> (mnemonic: '`' (backtick) runs an external
+program in ruby)
 
 This is Rio's interface to IO#popen
 
@@ -258,7 +292,7 @@ that this behavior differs from File#split.)
 
    rio('a/b/c').split   #=> [rio('a'),rio('b'),rio('c')]
 
-The array returned is extended wwith a +to_rio+ method, which will put
+The array returned is extended with a +to_rio+ method, which will put
 the parts back together again.
 
    ary = rio('a/b/c').split   #=> [rio('a'),rio('b'),rio('c')]
@@ -447,7 +481,7 @@ accessed, no socket has been opened, not so much as a test for a files
 existance has been done. When an I/O method is called on a Rio, the
 sequence of events required to complete that operation on the
 underlying object takes place. Rio takes care of creating the
-apropriate object (eg IO,Dir), opening the object with the apropriate
+appropriate object (eg IO,Dir), opening the object with the appropriate
 mode, performing the operation, closing the object if required, and
 returning the results of the operation.
 
@@ -458,7 +492,7 @@ Rio's I/O operations can be divide into two catagories:
 ==== Proxy operations
   
 These are calls which are forwarded to the underlying object (eg
-IO,Dir,Net::FTP), after apropriately creating and configuring that
+IO,Dir,Net::FTP), after appropriately creating and configuring that
 object. The result produced by the method is returned, and the object
 is closed.
 

data/lib/rio/doc/MISC.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================== 
-# Copyright (c) 2005, Christopher Kleckner
+# Copyright (c) 2005, 2006 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -22,7 +22,7 @@
 #++
 #
 # To create the documentation for Rio run the command
-#  rake rdoc
+#  ruby build_doc.rb
 # from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
 #
 # Suggested Reading

data/lib/rio/doc/OPTIONAL.rb

@@ -0,0 +1,134 @@
+#--
+# =============================================================================== 
+# Copyright (c) 2005, 2006 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. 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, 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.
+
+
+Please read the following first:
+* RIO::Doc::INTRO
+* RIO::Doc::SYNOPSIS
+* RIO::Doc::HOWTO
+* RIO::Rio
+
+= Rio Optional Componants
+
+This document describes various optional Rio components, that must be
+explicitly 'required' to be available. These are not included in
+rio.rb either because they change classes that should not be changed
+without the developers explicit permission, or because they are not of
+general enough interest.
+
+== to_rio
+
+This option comprises 4 options
+* Object#to_rio
+
+    require 'rio/to_rio/object' 
+    ario = any_object.to_rio
+
+  This option adds a to_rio method to the Object class which calls the
+  object's #to_s method and passes it to the Rio constructor. Like:
+
+    ario = rio(any_object.to_s)
+
+* String#to_rio and String#/
+
+    require 'rio/to_rio/string'
+    ario = "a/file/represented/as/a/string".to_rio
+    ario = 'strings'/'used'/'with'/'subdirectory'/'operator'
+
+  This option adds a to_rio method and the subdirectory operator '/'
+  to the String class. Note that due to operator precedance one must
+  use parenthesis when calling a method directly on a Rio created
+  using the subdirectory operator with Strings
+
+    array_of_first_ten_lines = ('adir'/'asubdir'/'afile').lines[0...10]  
+
+* Array#to_rio
+
+    require 'rio/to_rio/array'
+    ario = %w[an array of path components].to_rio #=> rio('an/array/of/path/components')
+
+  This option adds a to_rio method to the Array class. This behaves as
+  if 
+   rio(%w[an array of path components]) had been called.
+
+* require 'rio/to_rio/all' will make all of the above available.
+
+== RIO.ARGV
+
+ require 'rio/argv'
+ arguments_as_rios = RIO.ARGV
+
+This option provides a function which converts each element of ruby's
+ARGV into a Rio.  Useful when writing programs that take a list of
+files as its arguments
+
+== RIO.popen3
+
+ require 'rio/open3'
+ input,output,errput = RIO.popen3
+ RIO.popen3 { |input,output,errput| ... }
+
+This options provides a wrapper around the Open3#popen3 call with the
+IO objects converted to Rios
+
+== RIO.prompt
+
+ require 'rio/prompt'
+ the_anwser = RIO.prompt('What is the answer? ')
+
+This option provides a module function to prompt for input.
+
+
+=end
+module OPTIONAL
+end
+end
+end

data/lib/rio/doc/SYNOPSIS.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================== 
-# Copyright (c) 2005, Christopher Kleckner
+# Copyright (c) 2005, 2006 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -22,7 +22,7 @@
 #++
 #
 # To create the documentation for Rio run the command
-#  rake rdoc
+#  ruby build_doc.rb
 # from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
 #
 # Suggested Reading
@@ -52,10 +52,17 @@ module Doc #:doc:
 
 = 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.
+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.
+
 
 == SYNOPSIS
+
 For the following assume:
  astring = ""
  anarray = []

data/lib/rio/doc.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================== 
-# Copyright (c) 2005, Christopher Kleckner
+# Copyright (c) 2005, 2006 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -22,7 +22,7 @@
 #++
 #
 # To create the documentation for Rio run the command
-#  rake rdoc
+#  ruby build_doc.rb
 # from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
 #
 # Suggested Reading

data/lib/rio/entrysel.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================== 
-# Copyright (c) 2005, Christopher Kleckner
+# Copyright (c) 2005, 2006 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -22,7 +22,7 @@
 #++
 #
 # To create the documentation for Rio run the command
-#  rake rdoc
+#  ruby build_doc.rb
 # from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
 #
 # Suggested Reading
@@ -56,6 +56,11 @@ module RIO
         abstract_method :=~
                 
       end
+      class Depth < Base
+        def =~(entry)
+          @match_to === entry.rl.pathdepth
+        end
+      end
       class Any < Base
         def =~(entry) true end
       end
@@ -63,10 +68,24 @@ module RIO
         def =~(entry) false end
       end
       class Glob < Base
-        def =~(entry) Impl::U.fnmatch?(entry.filename.to_s,@match_to) end
+        def =~(entry) 
+          ::File.fnmatch?(@match_to,entry.filename.to_s) 
+        end
       end
       class Regexp < Base
-        def =~(entry) @match_to =~ entry.filename.to_s end
+        def =~(entry) 
+          @match_to =~ entry.filename.to_s 
+        end
+      end
+      class PathGlob < Base
+        def =~(entry) 
+          ::File.fnmatch?(@match_to,entry.to_s) 
+        end
+      end
+      class PathRegexp < Base
+        def =~(entry) 
+          @match_to =~ entry.to_s 
+        end
       end
       class Proc < Base
         def =~(entry) @match_to[entry] end
@@ -84,6 +103,8 @@ module RIO
       end
       def create(arg)
         case arg
+        when ::Fixnum     then Depth.new(arg)
+        when ::Range     then Depth.new(arg)
         when ::String     then Glob.new(arg)
         when ::Regexp     then Regexp.new(arg)
         when ::Proc       then Proc.new(arg)
@@ -128,8 +149,6 @@ module RIO
       end
       class Sels < Array
         def <<(entry_list)
-          #p callstr('<<',entry_list)
-          
           same_sym = self.grep(entry_list)
           if same_sym.empty?
             super

data/lib/rio/exception/copy.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================== 
-# Copyright (c) 2005, Christopher Kleckner
+# Copyright (c) 2005, 2006 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -22,7 +22,7 @@
 #++
 #
 # To create the documentation for Rio run the command
-#  rake rdoc
+#  ruby build_doc.rb
 # from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
 #
 # Suggested Reading

data/lib/rio/exception/notsupported.rb

@@ -0,0 +1,47 @@
+#--
+# =============================================================================== 
+# Copyright (c) 2005, 2006 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. 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/exception'
+module RIO
+  module Exception  
+    class NotSupported < Base  #:nodoc: all
+      def self.emsg(fname,obj)
+        "#{fname}() is not supported for #{obj.class} objects" 
+      end
+    end
+  end
+end

data/lib/rio/exception/open.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================== 
-# Copyright (c) 2005, Christopher Kleckner
+# Copyright (c) 2005, 2006 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -22,7 +22,7 @@
 #++
 #
 # To create the documentation for Rio run the command
-#  rake rdoc
+#  ruby build_doc.rb
 # from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
 #
 # Suggested Reading

data/lib/rio/exception/state.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================== 
-# Copyright (c) 2005, Christopher Kleckner
+# Copyright (c) 2005, 2006 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -22,7 +22,7 @@
 #++
 #
 # To create the documentation for Rio run the command
-#  rake rdoc
+#  ruby build_doc.rb
 # from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
 #
 # Suggested Reading

data/lib/rio/exception.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================== 
-# Copyright (c) 2005, Christopher Kleckner
+# Copyright (c) 2005, 2006 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -22,7 +22,7 @@
 #++
 #
 # To create the documentation for Rio run the command
-#  rake rdoc
+#  ruby build_doc.rb
 # from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
 #
 # Suggested Reading