rio 0.3.1 → 0.3.2

data/ex/findinruby

@@ -1,16 +1,20 @@
 #!/usr/bin/env ruby
 
 require 'rio'
+require 'rio/argv'
 
 re = ARGV.shift
 
-require 'rio/argv'
-RIO::argv.each do |path|
-  rio(path).norecurse('.svn','pkg').files('*.rb',proc{ |f| f.executable? and f[0] =~ /^#!.+ruby/ }) do |f|
+is_ruby_exe = proc{ |f| f.executable? and f[0][0] =~ /^#!.+ruby/ }
+
+RIO.ARGV.each do |rpath|
+  rpath.norecurse('.svn','pkg').files('*.rb',is_ruby_exe) do |f|
     print f.lines[/#{re}/].map{ |line| "#{f}: #{line}" }
   end
+
 end
 __END__
+
 ARGV.each do |path|
   rio(path).norecurse('.svn','pkg').files('*.rb',proc{ |f| f.executable? and f[0] =~ /^#!.+ruby/ }) do |f|
     print f.lines[/#{re}/].map{ |line| "#{f}: #{line}" }

data/ex/findruby

@@ -1,9 +1,13 @@
 #!/usr/bin/env ruby
 
 require 'rio'
+require 'rio/argv'
 
-ARGV.each do |path|
-  rio(path).norecurse('.svn').files('*.rb',proc{ |f| f.executable? and f[0] =~ /^#!.+ruby/ }) do |f|
+#is_ruby_exe = proc{ |f| f.executable? and f[0][0] =~ /^#!.+ruby/ }
+is_ruby_exe = proc{ |f| f.executable? and f.gets =~ /^#!.+ruby/ }
+
+RIO.ARGV.each do |rpath|
+  rpath.norecurse('.svn','pkg').files('*.rb',is_ruby_exe) do |f|
     puts f
   end
 end

data/lib/rio.rb

@@ -44,7 +44,7 @@ require 'extensions/symbol'
 require 'extensions/enumerable'
 require 'extensions/string'
 require 'forwardable'
-
+$trace_states = false
 module RIO 
   # See also: RIO::Doc::SYNOPSIS; RIO::Doc::INTRO; RIO::Doc::HOWTO.
   class Rio < Base #:doc:

data/lib/rio/argv.rb

@@ -43,6 +43,10 @@ module RIO
     ::ARGV.map { |path| rio(path) }
   end
   module_function :argv
+  def ARGV()
+    ::ARGV.map { |path| rio(path) }
+  end
+  module_function :ARGV
 end
 
 if $0 == __FILE__

data/lib/rio/constructor.rb

@@ -135,6 +135,23 @@ module RIO
   #  rio(??)
   #  rio(??,basename='rio',tmpdir=Dir::tmpdir)
   #
+  # To create a temporary object that will become a file
+  # or a directory, depending on how you use it:
+  #  rio(??)
+  #  rio(??,basename='rio',tmpdir=Dir::tmpdir)
+  #
+  # To force it to become a file
+  #  rio(??).file
+  # or just write to it.
+  #
+  # To force it to become a directory:
+  #  rio(??).dir
+  # or
+  #  rio(??).mkdir
+  # or
+  #  rio(??).chdir
+  #
+  #
   # ===== Creating a Rio that refers to an arbitrary TCPSocket
   #
   #  rio('tcp:',hostname,port)

data/lib/rio/context.rb

@@ -90,7 +90,7 @@ module RIO
         p = {}
         ncx = Vars.new(q,p)
         keys.each { |key|
-          ncx.set_(key,@values[key])
+          ncx.set_(key,@values[key]) if @values.has_key?(key)
         }
         ncx
       end

data/lib/rio/context/dir.rb

@@ -42,6 +42,7 @@ require 'rio/entrysel'
 module RIO
   module Cx
     module Methods
+      def dir_iter?() cx.has_key?('sel') || cx.has_key?('nosel') end
       
       private
 

data/lib/rio/context/methods.rb

@@ -85,13 +85,13 @@ module RIO
 
   module Cx
     module Methods
-      def noclose(arg=false,&block)
+      def noautoclose(arg=false,&block)
         closeoncopy(arg).closeoneof(arg,&block)
       end
-      def noclose_(arg=false)
+      def noautoclose_(arg=false)
         closeoncopy_(arg).closeoneof_(arg)
       end
-      protected :noclose_
+      protected :noautoclose_
     end
   end
 

data/lib/rio/dir.rb

@@ -70,9 +70,9 @@ module RIO
       def open(m=nil,*args)
         open_(*args)
       end
-      def open_() 
+      def open_(*args) 
         unless open?
-          ios = self.rl.open()
+          ios = self.rl.open(*args)
           self.ioh = IOH::Dir.new(ios)
 #          self.ioh = self.rl.open()
         end

data/lib/rio/doc/HOWTO.rb

@@ -103,7 +103,7 @@ IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO, OpenURI, Zlib, and CSV.
 
 * Read all lines starting with 'require' into an array, with each line chomped
    # method 1
-   array = ario.chomp.lines(/^\s*require/)
+   array = ario.chomp.lines[/^\s*require/]
    # method 2
    ario.chomp.lines(/^\s*require/) > array
 
@@ -173,7 +173,7 @@ IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO, OpenURI, Zlib, and CSV.
    # method 2
    ario.print(string)
    # method 3
-   ario.noclose < string
+   ario.noautoclose < string
 
 * Write a string to a file and close the file
    # method 1
@@ -189,7 +189,7 @@ IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO, OpenURI, Zlib, and CSV.
    # method 2
    ario.a.print(string)
    # method 3
-   ario.noclose << string
+   ario.noautoclose << string
 
 * Append a string to a file and close the file
    # method 1
@@ -204,7 +204,7 @@ IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO, OpenURI, Zlib, and CSV.
    ario = rio('afile').nocloseoncopy
    ario << array
    # method 2
-   ario.noclose < array
+   ario.noautoclose < array
 
 * Write an array to a file and close the file
    # method 1
@@ -302,9 +302,14 @@ IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO, OpenURI, Zlib, and CSV.
    # method 5
    array = ario.norecurse('.svn')['*.txt']
   
-* Iterate through all ruby files in a directory structure except those in the '.svn' and 'pkg' directories
+* Iterate through ruby files in a directory and subdirectories skipping 
+  those in the '.svn', and 'pkg' directories
    # method 1
-   ario.norecurse('.svn','pkg').files('*.rb',proc{ |f| f.executable? and f[0] =~ /^#!.+ruby/ }) { |f| ... }
+   is_ruby_exe = proc{ |f| f.executable? and f[0][0] =~ /^#!.+ruby/ }
+   ario.norecurse('.svn','pkg').files('*.rb',is_ruby_exe) { |f| ... }
+   # method 2
+   is_ruby_exe = proc{ |f| f.executable? and f.gets =~ /^#!.+ruby/ }
+   ario.norecurse('.svn','pkg').files('*.rb',is_ruby_exe) { |f| ... }
 
 * Put all files excluding those that are symlinks to files in an array
    # method 1

data/lib/rio/doc/INTRO.rb

@@ -67,7 +67,7 @@ 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 path manipulation methods)
+* Creating a Rio (using the constructor or as the result of one of the path manipulation methods)
 * Configuring a Rio 
 * Rio I/O
 
@@ -139,8 +139,8 @@ character.
 <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 +stdio:+ Rio does not know whether it will connect
-to stdin or stdout until an io operation is specified. 
+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.
 
@@ -167,12 +167,28 @@ to stdin or stdout until an io operation is specified.
  astring = ""
  rio(?","")
 
-===== Creating a Rio that refers to a Tempfile object
+===== Creating a Rio that refers to a Temporary object
 
 <tt>rio(??)</tt> (mnemonic: '?' you don't know its name)
+
+To create a temporary object that will become a file
+or a directory, depending on how you use it:
  rio(??)
  rio(??,basename='rio',tmpdir=Dir::tmpdir)
 
+To force it to become a file
+ rio(??).file
+or just write to it.
+
+To force it to become a directory:
+ rio(??).dir
+or
+ rio(??).mkdir
+or
+ rio(??).chdir
+
+
+
 ===== Creating a Rio that refers to an arbitrary TCPSocket
 
  rio('tcp:',hostname,port)
@@ -196,10 +212,10 @@ the return values converted to a Rio.
 
 ==== Creating a Rio from a Rio's component parts.
 
-The Rio methods for creating a Rio from a Rio's component parts are Rio#dirname, 
-Rio#filename, Rio#basename,
-and Rio#extname. 
-The behavior of Rio#basename depends on the setting of the +ext+ configuration variable
+The Rio methods for creating a Rio from a Rio's component parts are 
+Rio#dirname, Rio#filename, Rio#basename, and Rio#extname. 
+The behavior of Rio#basename depends on the setting of the +ext+ 
+configuration variable
 and is different from its counterpart in the File class. The default value of the +ext+ configuration variable
 is the string returned File#extname. The +ext+ configuration variable can be changed using Rio#ext and Rio#noext
 and can be queried using Rio#ext?. This value is used by calls to Rio#basename.
@@ -562,10 +578,131 @@ symlinks to non-existant object even though the symlink itself exists).
 The deleting methods' purpose is to make things not exist, so
 calling one of them on something that already does not exist is considered a success.
 
-To create a clean copy of a directory whether or not anything with that name exists you might do this
-   rio('adir').delete!.mkpath.chdir do
-    # do something in adir
-   end
+To create a clean copy of a directory whether or not anything with that name exists one might do this
+ rio('adir').delete!.mkpath.chdir do
+   # do something in adir
+ end
+
+---
+
+== Miscellany
+
+
+==== Using Symbolic Links
+
+To create a symbolic link (symlink) to the file-system entry refered to by a Rio, use Rio#symlink. 
+Rio#symlink differs from File#symlink in that it calculates the path from the symlink location to 
+the Rio's position. So:
+
+ File#symlink('adir/afile','adir/alink')
+
+creates a symlink in the directory 'adir' named 'alink' which references 'adir/afile'. From the 
+perspective of 'alink', 'adir/afile' does not exist. While:
+
+ rio('adir/afile').symlink('adir/alink')
+
+creates a symlink in the directory 'adir' named 'alink' which references 'afile'. This is the route
+to 'adir/afile' from the perspective of 'adir/alink'. 
+
+Note that the return value from +symlink+ is the calling Rio and not a Rio refering to the symlink.
+This is done for consistency with the rest of Rio.
+
+Rio#symlink? can be used to test if a file-system object is a symlink. A Rio is extended with
+Rio#readlink, and Rio#lstat only if Rio#symlink? returns true. So for non-symlinks, these
+will raise a NoMethodError. These are both passed to their counterparts in File. Rio#readlink
+returns a Rio refering to the result of File#readlink.
+
+==== Using A Rio as an IO (or File or Dir)
+
+Rio supports so much of IO's interface that one might be tempted to pass it to a method that 
+expects an IO. While Rio is not and is not intended to be a stand in for IO, this can work. 
+It requires knowledge of every IO method that will be called, under any circumstances. 
+
+Even in cases where Rio supports the required IO interface, A Rio feature that seems to 
+cause the most incompatibility, is its automatic closing of files. To turn off all of Rio's
+automatic closing use Rio#noautoclose.
+
+For example:
+ require 'yaml'
+ yrio = rio('ran.yaml').delete!.noautoclose
+ YAML.dump( ['badger', 'elephant', 'tiger'], yrio )
+ obj = YAML::load( yrio ) #=> ["badger", "tiger", "elephant"]
+
+==== Automatic Closing of Files
+
+Rio closes files automatically in three instances. 
+
+When reading from an IO it is closed when the end of file is reached. While 
+this is a reasonable thing to do in many cases, sometimes this is not desired.
+To turn Rio's automatic closing on end of file use Rio#nocloseoneof (it can
+be turned back on via Rio#closeoneof)
+
+ ario = rio('afile').nocloseoneof
+ lines = ario[]
+ ario.closed?   #=> false
+
+Closing on end-of-file is necessary for many of Rio's "one-liners", but has an 
+implication that may be surprising at first. A Rio starts life as a path, not 
+much more than a string. When one of its read methods is called it becomes an
+input stream. When the stream is closed, it becomes a path again. This means 
+that when reading from a Rio, the end-of-file condition is seen only once before it 
+becomes a path again, and will be reopened if another read operation is attempted.
+
+Another time a Rio will be closed atomatically is when writing to it with one
+of the copy operators (<tt><, <<, >, >></tt>).
+This behavior can be turned off with Rio#nocloseoncopy.
+
+To turn off both of thes types of automatic closing use Rio#noautoclose.
+
+The third instance when Rio will close a file automatically is when a file opened
+for one type of access receives a method which that access mode does not support.
+So, the code
+ rio('afile').puts("Hello World").gets
+will open the file for write access when the +puts+ method is received. When +gets+ is
+called the file is closed and reopened with read access.
+
+==== Explicit Closing of Files
+
+Rio can not determine when the client is finished writing to it, as it does 
+using +eof+ on read. It is the author's understanding that Ruby does not support
+a mechanism to have code run when there are no more references to it -- that finalizers 
+are not necessarily run immediatly upon an object's reference count reaching 0.
+If this understanding is incorrect, some of Rio's extranious ways of closing a file
+may be rethought.
+
+That being said, Rio support several ways to explicitly close a file. Rio#close will close
+any open Rio. The output methods Rio#puts!, Rio#putc!, Rio#printf!, Rio#print!, and Rio#write!
+behave as if their counterparts without the exclamation point had been called and
+then call Rio#close or Rio#close_write if the underlying IO object is opened for duplex access.
+
+
+==== Open mode selection
+
+A Rio is typically not explicitly opened. It opens a file automatically when an
+input or output methed is called. For output methods Rio opens a file with mode 'w',
+and otherwise opens a file with mode 'r'. This behavior can be modified using the
+tersely named methods Rio#a, Rio#a!, Rio#r, Rio#r!, Rio#w, and Rio#w!, which cause
+the Rio to use modes 'a','a+','r','r+','w',and 'w+' respectively.
+
+One way to append a string to a file and close it in one line is
+ rio('afile').a.puts!("Hello World") 
+
+Run a cmd that must be opened for read and write
+ ans = rio(?-,'cat').w!.puts!("Hello Kitty").readlines
+
+The automatic selection of mode can be bypassed entirely using Rio#mode and Rio#open.
+
+If a mode is specified using +mode+, the file will still be opened automatically, but 
+the mode specified in the +mode+ method will be used regardless of whether it makes sense.
+
+A Rio can also be opened explicitly using Rio#open. +open+ takes one parameter, a mode.
+This also will override all of Rio's automatic mode selection.
+
+
+
+
+---
+
 
 See also:
 * RIO::Doc::SYNOPSIS

data/lib/rio/doc/SYNOPSIS.rb

@@ -63,6 +63,9 @@ For the following assume:
 Copy a file into a string
  rio('afile') > astring 
 
+Copy a string into a file
+ rio('afile') < astring 
+
 Copy the chomped lines of a file into an array
  rio('afile').chomp > anarray
  
@@ -78,18 +81,18 @@ Copy an entire directory structure into another directory
 Copy a web page into a file
  rio('http://rubydoc.org/') > rio('afile')
 
-Copy a file from a ftp server into a file
+Copy a file from a ftp server into a local file
  rio('ftp://host/afile.gz') > rio('afile.gz')
 
 Copy a gzipped file un-gzipping it
  rio('afile.gz').gzip > rio('afile')
 
-Copy a file from a ftp server into a local file un-gzipping it
- rio('ftp://host/afile.gz').gzip > rio('afile')
-
 Copy a plain file, gzipping it
  rio('afile.gz').gzip < rio('afile')
 
+Copy a file from a ftp server into a local file un-gzipping it
+ rio('ftp://host/afile.gz').gzip > rio('afile')
+
 Iterate over the entries in a directory
  rio('adir').entries { |entrio| ... }
 
@@ -99,6 +102,15 @@ Iterate over only the files in a directory
 Iterate over only the .rb files in a directory
  rio('adir').files('*.rb') { |entrio| ... }
 
+Iterate over only the directories in a directory
+ rio('adir').dirs { |entrio| ... }
+
+Iterate over only the _dot_ files in a directory
+ rio('adir').dirs(/^\./) { |entrio| ... }
+
+Iterate over the files in a directory and its subdirectories, skipping '.svn' and 'CVS' directories 
+ rio('adir').norecurse(/^\.svn$/,'CVS').files { |entrio| ... }
+
 Create an array of the .rb entries in a directory
  anarray = rio('adir')['*.rb']
 
@@ -111,8 +123,7 @@ Create an array of the .rb entries in a directory and its subdirectories
 Create an array of the .rb files in a directory and its subdirectories
  anarray = rio('adir').all.files['*.rb']
 
-Copy an entire directory structure but only the .rb files from a directory and its subdirectories 
-into another directory
+Copy an entire directory structure and the .rb files within it
  rio('adir').dirs.files('*.rb') > rio('another_directory')
 
 Iterate over the chomped lines of a file
@@ -133,14 +144,17 @@ Copy the first 10 lines of a file into another file
 Copy the first 10 lines of a file to stdout
  rio('afile').lines(0..9) > rio(?-)
 
-Copy the first 10 lines of a gzipped file to stdout
- rio('afile.gz').gzip.lines(0..9) > rio(?-)
-
 Copy the first 10 lines of a gzipped file on an ftp server to stdout
  rio('ftp://host/afile.gz').gzip.lines(0..9) > rio(?-)
 
 Put the first 100 chomped lines of a gzipped file into an array
- anarray =  rio('afile.gz').gzip[0...100] 
+ anarray =  rio('afile.gz').chomp.gzip[0...100] 
+
+Put chomped lines that start with 'Rio' into an array
+ anarray = rio('afile').chomp[/^Rio/]
+
+Iterate over the non-empty, non-comment chomped lines of a file
+ rio('afile').chomp.nolines(:empty?,/^\s*#/) { |line| ... }
 
 Copy the output of th ps command into an array, skipping the header line and the ps command entry
  rio(?-,'ps -a').nolines(0,/ps$/) > anarray 
@@ -148,14 +162,13 @@ Copy the output of th ps command into an array, skipping the header line and the
 Prompt for input and return what was typed
  ans = rio(?-).print("Type Something: ").chomp.gets 
 
-Change the extension of all files with the extension '.htm' in a directory and its
-subdirectories to have the extension '.html'
+Change the extension of all .htm files in a directory and its subdirectories to .html
  rio('adir').rename.all.files('*.htm') do |htmfile|
    htmfile.extname = '.html'
  end
 
 Create a symbolic link 'asymlink' in 'adir' which refers to 'adir/afile'
- rio('adir/afile').symlinke('adir/asymlink')
+ rio('adir/afile').symlink('adir/asymlink')
 
 === SUGGESTED READING