grande.rb in rio-0.4.2

- old
+ new

@@ -1,8 +1,8 @@
 #--
 # =============================================================================== 
-# Copyright (c) 2005,2006,2007 Christopher Kleckner
+# Copyright (c) 2005,2006,2007,2008 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
@@ -126,15 +126,15 @@
       #
       # As with IF::Grande#each:
       # * Files and directories are returned as Rios
       # * The types of entries is also affected by IF::GrandeEntry#files and IF::GrandeEntry#dirs.
       #    rio('adir').files['*.txt'] # array of all .txt files
-      #    rio('adir').dirs(/^\./) # array of all dot directories
+      #    rio('adir').dirs[/^\./] # array of all dot directories
       # * Recursion is enabled using IF::GrandeEntry#all
       #    rio('adir').all.files['*.[ch]'] # array of c source files in adir and its subdirecories
       #    rio('adir').all.dirs[/^\.svn/]  # array of subversion directories in adir and subdirectories
-      # * IF::GrandeEntry#files and IF::GrandeEntry#dirs act independetly of each other. 
+      # * IF::GrandeEntry#files and IF::GrandeEntry#dirs act independently of each other. 
       #   Specifying both will cause both to be returned. 
       #   The argument list to IF::Grande#[] will be applied to the closest.
       #    rio('adir').files('*.rb').dirs['ruby*'] # array of .rb files and 
       #                                            # directories starting with 'ruby'
       #    rio('adir').dirs('ruby*').files['*.rb'] # same thing
@@ -327,13 +327,16 @@
       #  rio('adir').delete # delete adir
       #  rio('something').delete # delete something
       #
       def delete() target.delete(); self end
 
+      # See IF::Grande#delete
+      def unlink() target.unlink(); self end
+
       # For a file IF::Grande#delete! calls FileUtils#rm. 
-      # For a directory IF::Grande#delete! calls FileUtils#rmtree
-      # Returns the Rio. If the rio does not exist, simply return itself.
+      # For a directory IF::Grande#delete! calls FileUtils#rmtree.
+      # Returns the Rio. If the rio does not exist, simply returns itself.
       #
       #  rio('afile,txt').delete! # delete f.txt
       #  rio('adir').delete! # delete adir
       #
       #  # create a directory, after deleting anything that previously had its name
@@ -344,11 +347,11 @@
       # * To delete an empty directory use IF::Dir#rmdir
       # * To delete an entire directory tree use IF::Dir#rmtree
       # * To delete anything except a populated directory use IF::Grande#delete
       # * To delete anything use IF::Grande#delete!
       #
-      # In all cases, deleting something that does not exist is considered successful
+      # In all cases, deleting something that does not exist is considered successful.
       #
       def delete!() target.delete!(); self end
 
       # Grande Copy-To Operator
       # 
@@ -424,12 +427,13 @@
       def copy_to(destination) target.copy_to(destination); self end
 
 
       # Grande Pipe Operator
       # 
-      # The Rio pipe operator is actually an alternative syntax for calling the copy-to operator, designed to 
-      # allow several copy operation to be performed in one line of code, with behaviour that mimics
+      # The Rio pipe operator is actually an alternative syntax for calling the IF::Grande#> (copy-to) 
+      # operator, designed to 
+      # allow several copy operation to be performed in one line of code, with behavior that mimics
       # the pipe operator commonly available in shells.
       #
       # If +destination+ is a +cmdio+, a <tt>cmdpipe</tt> Rio is returned, and none of the commands are run.
       #
       # Otherwise the +cmdpipe+ Rio is run with the output of the pipe being copied to the destination.
@@ -526,11 +530,11 @@
       # not give the same results, This generalized description is convenient.
       #
       # For example the code:
       #
       #  destination < source
-      #  # is like
+      # is like
       #  source.each { |element| destination << element }
       #
       # for any of the following definitions of src and dst
       # * copying files
       #    src = rio('afile')
@@ -628,10 +632,13 @@
 
       # Grande Exclude method
       # 
       # +skip+ can be used in two ways.
       #
+      #
+      # ==== skip with no arguments
+      #
       # If called with no arguments it reverses the polarity of the
       # next non-skip grande selection method that is called. That is,
       # it turns +lines+, +records+, +rows+, +files+, +dirs+ and +entries+
       # into +skiplines+, +skiprecords+, +skiprows+, +skipfiles+, 
       # +skipdirs+, and +skipentries+, respectively.
@@ -641,10 +648,12 @@
       #
       # Note that it only affects the next selection method seen -- and may be
       # used more than once. If no grande selection method is seen, +skip+ is
       # ignored.
       #
+      # ==== skip with arguments
+      #
       # When called with arguments it acts like IF::GrandeEntry#skipentries for directory 
       # Rios and like IF::GrandeStream#skiprecords for stream Rios.
       #
       #  rio('afile').lines(/Rio/).skip[0..4] # lines containg 'Rio' excluding the
       #                                       # first five lines
@@ -672,11 +681,11 @@
       def empty?() target.empty? end
 
       # IF::Grande#split has two distinct behaviors depending on 
       # whether or not it is called with an argument.
       #
-      # ==== split-with-no-aruments:
+      # ==== split with no aruments:
       #
       # Returns an array of Rios, one for each path element. 
       # (Note that this behavior differs from File#split.)
       #
       #  rio('a/b/c').split   #=> [rio('a'),rio('b'),rio('c')]
@@ -691,10 +700,10 @@
       #  ary[1] = rio('d')
       #  ary.to_rio                 #=> rio('a/d/c')
       #
       # See also IF::Path#join, IF::Path#/, IF::Path#splitpath
       #
-      # ==== split-with-an-argument:
+      # ==== split with an argument:
       #
       # 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
       #