rio 0.3.8 → 0.3.9

data/lib/rio/doc/EXAMPLES.rb

@@ -0,0 +1,299 @@
+#--
+# =============================================================================== 
+# 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 Doc
+=begin rdoc
+
+
+
+The following examples are provided without comment
+
+ array = rio('afile').readlines
+
+ rio('afile') > rio('acopy')
+ 
+ ary = rio('afile').chomp.lines[0...10]
+
+ rio('adir').rename.all.files('*.htm') do |file| 
+   file.ext = '.html'
+ end
+
+A basic familiarity with ruby and shell operations should allow a
+casual reader to guess what these examples will do. How they are being
+performed may not be what a casual reader might expect.  I will
+explain these example to illustrate the Rio basics.
+
+For many more examples please read the HOWTO document and the rdoc
+documentation.
+
+== Example 1.
+
+ array = rio('afile').readlines
+
+This uses IO#readlines to read the lines of 'afile' into an array.
+
+=== Creating a Rio
+
+Rio extends the module Kernel by adding one function +rio+, which acts
+as a constructor returning a Rio. This constructor builds a
+description of the resource the Rio will access (usually a path). It
+does not open the resource, check for its existance, or do anything
+except remember its specifcation. _rio_ returns the Rio which can be
+chained to a Rio method as in this example or stored in a
+variable. This coud have been written
+
+ ario = rio('afile')
+ array = ario.readlines
+
+ ario = rio('afile')
+
+In this case the resource specified is a relative path. After the
+first line the Rio does know or care whether it is a path to a file
+nor whether it exists. Rio provides many methods that only deal with a
+resource at this level, much as the standard library classes Pathname
+and URI. It should be noted at this point that Rio paths stored
+internally as a URL as specified in RFC 1738 and therefore use slashes
+as separators. A resource can also be specified without separators,
+because _rio_ interprets multiple arguments as parts of a path to be
+joined, and an array as an array of parts to be joined. So the
+following all specify the same resource.
+
+ rio('adir/afile')
+ rio('adir','afile')
+ rio(%w/adir afile/)
+
+The rio constructor can be used to specify non-file-system resources,
+but for this example we will restrict our discussion to paths to
+entities on file-systems.
+
+ array = ario.readlines
+
+Now that we have a Rio, we can call one of its methods; in this case
+_readlines_. This is an example of using a Rio as a proxy for the
+builtin IO#readlines. Given the method _readlines_, the Rio opens
+'afile' for reading, calls readlines on the resulting IO object,
+closes the IO object, and returns the lines read.
+
+== Example 2
+
+ rio('afile') > rio('acopy')
+ 
+This copies the file 'afile' into the file 'acopy'.
+
+The first things that happen here are the creation of the Rios. As
+described in Example 1, when created a Rio simply remembers the
+specifcation of its resource. In this case, a relative path 'afile' on
+the left and a relative path 'acopy' on the right.
+
+Next the Rio#> (copy-to) method is called on the 'afile' Rio with the
+'acopy' Rio as its argument. If that looks like a greater-than
+operator to you, think Unix shell, with Rios '>' is the copy-to
+operator.
+
+Upon seeing the copy-to operator, the Rio has all the information it
+needs to proceed. It determines that it must be opened for reading,
+that its argument must be opened for writing, and that it's contents
+must be copied to the resource referenced by it' argument -- and that
+is what it does. Then it closes itself and its argument.
+
+Consider if we had written this example this way.
+
+ afile = rio('afile')
+ acopy = rio('acopy')
+ afile > acopy
+
+In this case we would still have variables referencing the Rios, and
+perhaps we would like do things a little differently than described
+above. Be assured that the selection of mode and automatic closing of
+files are the default behaviour and can be changed. Say we wanted
+'afile' to remain open so that we could rewind it and make a second
+copy, we might do something like this:
+
+ afile = rio('afile').nocloseoneof
+ afile > rio('acopy1')
+ afile.rewind > rio('acopy2')
+ afile.close
+
+Actually the 'thinking process' of the Rio when it sees a copy-to
+operator is much more complex than that described above.  If its
+argument had been a rio referencing a directory, it would not have
+opened itself for reading, but instead used FileUtils#cp to copy
+itself; if its argument had been a string, its contents would have
+ended up in the string; If its argument had been an array, its lines
+would been elements of that array; if its argument had been a socket,
+the its contents would have been copied to the socket. See the
+documentation for details.
+
+== Example 3.
+
+ array = rio('afile').chomp.lines[0...10]
+
+This fills +array+ with the first ten lines of 'afile', with each line chomped
+
+The casual observer mentioned above might think that +lines+ returns an array of lines and that this
+is a simple rewording of <tt>array = rio('afile').readlines[0...10]</tt> or even of 
+<tt>array = File.new('afile').readlines[0...10]</tt>. They would be wrong.
+
++chomp+ is a configuration method which turns on chomp-mode and returns the Rio. Chomp-mode causes all
+line oriented read operations to perform a String#chomp on each line
+
+=== Reading files
+
+Rio provides four methods to select which part of the file is read and
+how the file is divided. They are +lines+, +records+, +rows+ and
++bytes+. Briefly, +lines+ specifies that the file should be read line
+by line and <tt>bytes(n)</tt> specifies that the file should be read
+in _n_ byte chunks. All four take arguments which can be used to
+filter lines or chunks in or out. For simple Rios +records+ and +rows+
+only specify the filter arguments and are provided for use be
+extensions. For example, the CSV extension returns an array of the
+columns in a line when +records+ is used. In the absence of an
+extension +records+ and +rows+ behave like +lines+.
+
+First lets rewrite our example as:
+
+ array = rio('afile').chomp.lines(0...10).to_a
+
+The arguments to lines specify which records are to be read. 
+Arguments are interpreted based on their class as follows:
+* Range - interpreted as a range of record numbers to be read
+* Integer - interpreted as a one-element range
+* RegExp - only matching records are processed
+* Symbol - sent to each record, which is processed unless the result is false or nil
+* Proc - called for each record, the record is processed unless the return value is false or nil
+See the documentation for details and examples.
+
+In our example we have specified the Range (0...10). The +lines+
+method is just configuring the Rio, it does not trigger any IO
+operation. The fact that it was called and the arguments it was called
+with are stored away and the Rio is returned for further configuration
+or an actual IO operation. When an IO operation is called the Range
+will be used to limit processing to the first ten records. For
+example:
+
+ rio('afile').lines(0...10).each { |line| ... } # block will be called for the first 10 records
+ rio('afile').lines(0...10).to_a                # the first 10 records will be returned in an array
+ rio('afile').lines(0...10) > rio('acopy')      # the first 10 records will be copied to 'acopy'
+
+"But wait", you say, "In our original example the range was an
+argument to the subscript operator, not to +lines+".  This works
+because the subscript operator processes its arguments as if they had
+been arguments to the most-recently-called selection method and then
+calls +to_a+ on the rio. So our rewrite of the example does precisely
+the same thing as the original
+
+The big difference between the original example and the
+casual-observer's solution is that hers creates an array of the entire
+contents and only returns the first 10 while the original only puts 10
+records into the array.
+
+As a sidenote, Rios also have an optimization that can really help in
+certain situations. If records are only selected using Ranges, it
+stops iterating when it is beyond the point where it could possibly
+ever match. This can make a dramatic difference when one is only
+interested in the first few lines of very large files.
+
+== Example 4.
+
+ rio('adir').rename.all.files('*.htm') do |file| 
+   file.ext = '.html'
+ end
+
+This changes the extension of all .htm files below 'adir' to '.html'
+
+First we create the rio as always.
+
+Next we process the +rename+ method. When used as it is here --
+without arguments -- it just turns on rename-mode and returns the Rio.
+
++all+ is another configuration method, which causes directories to be
+processed recursively
+
++files+ is another configuration method. In example 3 we used +lines+
+to select what to process when iterating through a file. +files+ is
+used to select what to process when iterating through directories. The
+arguments to +files+ can be the same as those for +lines+ except that
+Ranges can not be used and globs can.
+
+In our example, the argument to +files+ is a string which is treated
+as a glob. As with +lines+, +files+ does not trigger any IO, it just
+configures the Rio.
+
+=== There's no action
+
+The previous examples had something that triggered IO: +readlines+,
++to_a+, +each+, <tt>> (copy-to)</tt>. This example does not. This
+example illustrates Rio's 'implied each'. All the configuration
+methods will call each for you if a block is given. So, because a
+block follows the +files+ method, it calls +each+ and passes it the
+block.
+
+Let's recap. At this point we have a Rio with a resource specified. We
+have configured with a couple of modes, 'rename', and 'all', and we
+have limited the elements we want to process to entries that are files
+and match the glob '*.htm'. +each+ causes the Rio to open the
+directory and call the block for each entry that is both a file and
+matches the glob. It was also configured with +all+,so it descends
+into subdirectories to find further matches and calles the block for
+each of them. The argument passed to the block is a Rio referencing
+the entry on the file-system.
+
+The _rename_mode_ we set has had no effect on our iteration at all, so why is it there? In general, 
+configuration options that are not applicable to a Rio are silently ignored, however, for directories
+some of them are passed on to the Rios for each entry when iterating. Since +rename+ is one such option,
+The example could have been written:
+
+ rio('adir').all.files('*.htm') do |file| 
+   file.rename.ext = '.html'
+ end
+
+The rename-with-no-args method affects the behaviour of the <tt>ext=</tt> option. In this case,
+setting it for the directory, rather than for each file in the block seems to make the intent
+of the code more clear, but that is a matter of personal taste. See the documentation for more 
+information on the rename-with-no-args method
+
+== Suggested Reading
+* RIO::Doc::SYNOPSIS
+* RIO::Doc::INTRO
+* RIO::Doc::HOWTO
+* RIO::Rio
+
+=end
+module EXAMPLES
+end
+end
+end

data/lib/rio/doc/HOWTO.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================== 
-# Copyright (c) 2005, 2006 Christopher Kleckner
+# Copyright (c) 2005,2006,2007 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -23,16 +23,15 @@
 #
 # 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.
+# from the distribution directory.
 #
 # Suggested Reading
 # * RIO::Doc::SYNOPSIS
 # * RIO::Doc::INTRO
 # * RIO::Doc::HOWTO
+# * RIO::Doc::EXAMPLES
 # * RIO::Rio
 #
-# <b>Rio is pre-alpha software. 
-# The documented interface and behavior is subject to change without notice.</b>
 
 
 module RIO

data/lib/rio/doc/INTRO.rb

@@ -1,6 +1,6 @@
 #--
 # =============================================================================== 
-# Copyright (c) 2005, 2006 Christopher Kleckner
+# Copyright (c) 2005,2006,2007 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -23,16 +23,15 @@
 #
 # 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.
+# from the distribution directory.
 #
 # Suggested Reading
 # * RIO::Doc::SYNOPSIS
 # * RIO::Doc::INTRO
 # * RIO::Doc::HOWTO
+# * RIO::Doc::EXAMPLES
 # * RIO::Rio
 #
-# <b>Rio is pre-alpha software. 
-# The documented interface and behavior is subject to change without notice.</b>
 
 
 module RIO
@@ -248,15 +247,15 @@ to the File or URI classes with 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+
+IF::Path#dirname, IF::Path#filename, IF::Path#basename, and IF::Path#extname.  The
+behavior of IF::Path#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.
+be changed using IF::Path#ext and IF::Path#noext and can be queried using
+IF::Path#ext?. This value is used by calls to IF::Path#basename.
 
-Rio#filename returns the last component of a path, and is basically
+IF::Path#filename returns the last component of a path, and is basically
 the same as +basename+ without consideration of an extension.
 
    rio('afile.txt').basename       #=> rio('afile')
@@ -271,8 +270,8 @@ the same as +basename+ without consideration of an extension.
 ==== Changing a path's component parts.
 
 Rio also provides methods for changing the component parts of its
-path.  They are Rio#dirname=, Rio#filename=, Rio#basename=, and
-Rio#extname=. These methods replace the part extracted as described
+path.  They are IF::Path#dirname=, IF::Path#filename=, IF::Path#basename=, and
+IF::Path#extname=. These methods replace the part extracted as described
 above with their argument.
 
    ario = rio('dirA/dirB/afile.rb')
@@ -287,8 +286,8 @@ discussed in the section on Renaming and Moving.
 
 ==== Splitting a Rio
 
-Rio#split returns an array of Rios, one for each path element. (Note
-that this behavior differs from File#split.)
+IF::Grande#split (or IF::Path#splitpath) 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')]
 
@@ -307,7 +306,7 @@ constructor will take, the constructor can be used.
    ario = rio('adir')
    rio(ario,'b')    #=> rio('adir/b')
 
-Rio#join and Rio#/ do the same thing, but the operator version
+IF::Path#join and IF::Path#/ do the same thing, but the operator version
 <tt>/</tt> can take only one argument.
 
    a = rio('a')
@@ -315,7 +314,7 @@ Rio#join and Rio#/ do the same thing, but the operator version
    c = a.join(b)    #=> rio('a/b')
    c = a/b          #=> rio('a/b')
 
-The arguments to +join+ and <tt>/</tt> do not need to be Rios, of course
+The arguments to IF::Path#join and IF::Path#/ do not need to be Rios, of course
    ario = rio('adir')
    ario/'afile.rb'           #=> rio('adir/afile.rb')
    ario.join('b','c','d')    #=> rio('adir/b/c/d')
@@ -324,8 +323,8 @@ The arguments to +join+ and <tt>/</tt> do not need to be Rios, of course
 
 ==== Manipulating a Rio path by treating it as a string.
 
-The Rio methods which treat a Rio as a string are Rio#sub, Rio#gsub
-and Rio#+.  These methods create a new Rio using the string created by
+The Rio methods which treat a Rio as a string are IF::String#sub, IF::String#gsub
+and IF::String#+.  These methods create a new Rio using the string created by
 forwarding the method to the String returned by Rio#to_s.
 
    ario = rio('dirA/dirB/afile') + '-1.1.1'   # rio('dirA/dirB/afile-1.1.1')
@@ -334,8 +333,8 @@ forwarding the method to the String returned by Rio#to_s.
 
 ==== Creating a Rio based on its relationship to another
 
-Rio#abs creates a new rio whose path is the absolute path of a Rio.
-If provided with an argument, it uses that as the base path, otherwise
+IF::Path#abs creates a new rio whose path is the absolute path of a Rio.
+If called with an argument, it uses it as the base path, otherwise
 it uses an internal base path (usually the current working directory
 when it was created).
 
@@ -344,16 +343,16 @@ when it was created).
      rio('a').abs('/usr')    #=> rio('/usr/a')
    end
 
-Rio#rel creates a new rio with a path relative to a Rio.
+IF::Path#rel creates a new rio with a path relative to a Rio.
 
    rio('/tmp').chdir do
      rio('/tmp/a').rel       #=> rio('a')
    end
    rio('/tmp/b').rel('/tmp') #=> rio('b')
 
-Rio#route_to and Rio#route_from creates a new rio with a path
+IF::Path#route_to and IF::Path#route_from creates a new rio with a path
 representing the route to get to/from a Rio. They are based on the
-methods of the same names in the URI class
+methods of the same names in the ::URI class
 
 === Configuring a Rio
 
@@ -381,7 +380,7 @@ Rio's configuration mehods fall into three categories.
   grande I/O methods
 
 All of Rio's configuration and selection methods can be passed a
-block, which will cause the Rio to behave as if +each+ had been called
+block, which will cause the Rio to behave as if IF::Grande#each had been called
 with the block after the method.
 
 ==== IO manipulators
@@ -497,13 +496,13 @@ object. The result produced by the method is returned, and the object
 is closed.
 
 In some cases the result is modified before being returned, as when a
-Rio is configured with +chomp+.
+Rio is configured with IF::GrandeStream#chomp.
 
 In all cases, if the result returned by the underlying object, could
 itself be used for further I/O operations it is returned as a Rio. For
-example: where File#dirname returns a string, Rio#dirname returns a
+example: where File#dirname returns a string, IF::Path#dirname returns a
 Rio; where Dir#read returns a string representing a directory entry,
-Rio#read returns a Rio.
+IF::FileOrDir#read returns a Rio.
 
 With some noteable exceptions, most of the operations available if one
 were using the underlying Ruby I/O class are available to the Rio and
@@ -531,7 +530,7 @@ For things that exist on a file system:
 
   * +dirname+, and +readlink+ return Rios instead of strings
 
-  * Rio has its own Rio#basename, Rio#join and Rio#symlink, which
+  * Rio has its own IF::Path#basename, IF::Path#join and IF::FileOrDir#symlink, which
     provide similar functionality.
 
   * The class methods which take multiple filenames
@@ -578,7 +577,7 @@ For directories:
 * the class methods +mkdir+, +delete+, +rmdir+ are provided as
   instance methods.
 
-* +chdir+ is provided as an instance method. Rio#chdir returns a Rio
+* +chdir+ is provided as an instance method. IF::Dir#chdir returns a Rio
   and passes a Rio to a block if one is provided.
 
 * +glob+ is provided as an instance method, but returns an array of
@@ -600,7 +599,7 @@ appropriate. For example
   
 ==== Grande operators
 
-The primary grande operator is Rio#each. +each+ is used to iterate
+The primary grande operator is IF::Grande#each. +each+ is used to iterate
 through Rios. When applied to a file it iterates through records in
 the file. When applied to a directory it iterates through the entries
 in the directory. Its behavior is modified by configuring the Rio
@@ -617,7 +616,7 @@ explicitly. For example:
  rio('adir').all.files('*.rb') { |f| ... } 
 
 Because a Rio is an Enumerable, it supports +to_a+, which is the basis
-for the grande subscript operator.  Rio#[] with no arguments simply
+for the grande subscript operator.  IF::Grande#[] with no arguments simply
 calls to_a. With arguments it behaves as if those arguments had been
 passed to the most recently called of the grande selection methods
 listed above, and then calls to_a. For example to get the first ten
@@ -678,20 +677,22 @@ For example:
 === Renaming and Moving
 
 Rio provides two methods for directly renaming objects on the
-filesystem: Rio#rename and Rio#rename!. Both of these use
-File#rename. The difference between them is the returned
-Rio. Rio#rename leaves the path of the Rio unchanged, while
-Rio#rename! changes the path of the Rio to refer to the renamed path.
+filesystem: IF::FileOrDir#rename and IF::FileOrDir#rename!. 
+Both of these use File#rename. 
+The difference between them is the returned Rio. 
+IF::FileOrDir#rename leaves the path of the Rio unchanged, 
+while IF::FileOrDir#rename! changes the path of the Rio to refer 
+to the renamed path.
 
    ario = rio('a')
    ario.rename('b')  # file 'a' has been renamed to 'b' but 'ario' => rio('a')
    ario.rename!('b')  # file 'a' has been renamed to 'b' and 'ario' => rio('b')
 
 Rio also has a +rename+ mode, which causes the path manipulation
-methods Rio#dirname=, Rio#filename=, Rio#basename= and Rio#extname= to
-rename an object on the filesystem when they are used to change a
-Rio's path. A Rio is put in +rename+ mode by calling Rio#rename with
-no arguments.
+methods IF::Path#dirname=, IF::Path#filename=, IF::Path#basename= and
+IF::Path#extname= to rename an object on the filesystem when they are
+used to change a Rio's path. A Rio is put in +rename+ mode by calling
+IF::FileOrDir#rename with no arguments.
 
    rio('adir/afile.txt').rename.filename = 'bfile.rb' # adir/afile.txt => adir/bfile.rb
    rio('adir/afile.txt').rename.basename = 'bfile'    # adir/afile.txt => adir/bfile.txt
@@ -707,20 +708,20 @@ in the Rios created when iterating through that directory.
 
 === Deleting 
 
-The Rio methods for deleting filesystem objects are Rio#rm, Rio#rmdir,
-Rio#rmtree, Rio#delete, and Rio#delete!. +rm+, +rmdir+ and +rmtree+
-are passed the like named methods in the FileUtils module. Rio#delete
+The Rio methods for deleting filesystem objects are IF::File#rm, IF::Dir#rmdir,
+IF::Dir#rmtree, IF::Grande#delete, and IF::Grande#delete!. +rm+, +rmdir+ and +rmtree+
+are passed the like named methods in the FileUtils module. IF::Grande#delete
 calls +rmdir+ for directories and +rm+ for anything else, while
-Rio#delete!  calls Rio#rmtree for directories.
+IF::Grande#delete!  calls IF::Dir#rmtree for directories.
 
-* To delete something only if it is not a directory use Rio#rm
-* To delete an empty directory use Rio#rmdir
-* To delete an entire directory tree use Rio#rmtree
-* To delete anything except a populated directory use Rio#delete
-* To delete anything use Rio#delete!
+* To delete something only if it is not a directory use IF::File#rm
+* 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!
 
 It is not an error to call any of the deleting methods on something
-that does not exist. Rio provides Rio#exist? and Rio#symlink? to check
+that does not exist. Rio provides IF::Test#exist? and IF::Test#symlink? to check
 if something exists (<tt>exist?</tt> returns false for symlinks to
 non-existant object even though the symlink itself exists).  The
 deleting methods' purpose is to make things not exist, so calling one
@@ -742,7 +743,7 @@ that name exists one might do this
 ==== 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
+to by a Rio, use IF::FileOrDir#symlink.  IF::FileOrDir#symlink differs from File#symlink
 in that it calculates the path from the symlink location to the Rio's
 position.
 
@@ -762,12 +763,12 @@ 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.
+IF::Test#symlink? can be used to test if a file-system object is a
+symlink. A Rio is extended with IF::FileOrDir#readlink, and
+IF::Test#lstat only if IF::Test#symlink? returns true. So for
+non-symlinks, these will raise a NoMethodError. These are both passed
+to their counterparts in File. IF::FileOrDir#readlink returns a Rio
+refering to the result of File#readlink.
 
 
 ==== Using A Rio as an IO (or File or Dir)
@@ -781,7 +782,7 @@ 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.
+IF::GrandeStream#noautoclose.
 
 For example:
  require 'yaml'
@@ -797,8 +798,8 @@ 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)
+of file use IF::GrandeStream#nocloseoneof (it can be turned back on via
+IF::GrandeStream#closeoneof)
 
  ario = rio('afile').nocloseoneof
  lines = ario[]
@@ -814,15 +815,16 @@ 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.
+can be turned off with IF::GrandeStream#nocloseoncopy.
 
 To turn off both of thes types of automatic closing use
-Rio#noautoclose.
+IF::GrandeStream#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+
+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.
 
@@ -837,10 +839,12 @@ 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
+file. IF::RubyIO#close will close any open Rio. 
+The output methods 
+IF::RubyIO#puts!, IF::RubyIO#putc!, IF::RubyIO#printf!, IF::RubyIO#print!, and IF::RubyIO#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
+call IF::RubyIO#close or IF::RubyIO#close_write if the underlying IO object is
 opened for duplex access.
 
 
@@ -850,7 +854,7 @@ 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
+methods IF::GrandeStream#a, IF::GrandeStream#a!, IF::GrandeStream#r, IF::GrandeStream#r!, IF::GrandeStream#w, and IF::GrandeStream#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
@@ -862,13 +866,13 @@ 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::RubyIO#mode and IF::FileOrDir#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
+A Rio can also be opened explicitly using IF::RubyIO#open. +open+ takes one
 parameter, a mode.  This also will override all of Rio's automatic
 mode selection.
 
@@ -888,7 +892,7 @@ effectively means
  rio('afile').lines.records(1..2)
 
 The CSV extension distingishes between items selected using
-Rio#records and those selected using Rio#lines. Rio returns records
+IF::GrandeStream#records and those selected using IF::GrandeStream#lines. Rio returns records
 parsed into Arrays by the CSV library when +records+ is used, and
 returns Strings as normal when +lines+ is used.  +records+ is the
 default.
@@ -931,7 +935,7 @@ array CSV fields, rather than just an array of strings.
  array_of_lines[0].to_a                          #==>["f0", "f1"]
  array_of_records[0].to_s                        #==>"f0,f1"
 
-Rio#csv takes two optional parameters, which are passed on to the CSV
+IF::CSV#csv takes two optional parameters, which are passed on to the CSV
 library. They are the +field_separator+ and the +record_separator+.
 
  rio('semisep').puts!(["h0;h1","f0;f1"])                 
@@ -945,8 +949,8 @@ using the copy operators.
  rio('colonsep').contents  #==>"h0:h1\nf0:f1\n"
 
 Rio provides two methods for selecting fields from CSV records in a
-manner similar to that provided for selecting lines -- Rio#columns and
-Rio#skipcolumns.
+manner similar to that provided for selecting lines -- IF::CSV#columns and
+IF::CSV#skipcolumns.
 
  rio('f.csv').puts!(["h0,h1,h2,h3","f0,f1,f2,f3"])
 
@@ -955,7 +959,7 @@ Rio#skipcolumns.
  rio('f.csv').csv.columns(1..2).to_a    #==>[["h1", "h2"], ["f1", "f2"]]
  rio('f.csv').csv.skipcolumns(1..2).to_a  #==>[["h0", "h3"], ["f0", "f3"]]
 
-Rio#columns can, of course be used with the +each+ and the copy
+IF::CSV#columns can, of course be used with the +each+ and the copy
 operators:
 
  rio('f.csv').csv.columns(0..1) > rio('out').csv
@@ -964,8 +968,6 @@ operators:
 
 ==== YAML mode
 
-<b>YAML Mode is currently in work. Please disregard this section</b>
-
 Rio uses the YAML class from the Ruby standard library to provide
 support for reading and writing YAML files. Normally
 using <tt>(skip)records</tt> is identical to <tt>(skip)lines</tt> because
@@ -973,7 +975,7 @@ while +records+ only selects and does not specify the record-type,
 +lines+ is the default. 
 
 The YAML extension distingishes between items selected using
-Rio#records, Rio#rows and Rio#lines. Rio returns objects
+IF::GrandeStream#records, IF::GrandeStream#rows and IF::GrandeStream#lines. Rio returns objects
 loaded via YAML#load when +records+ is used; returns the YAML text
 as a String when +rows+ is used; and
 returns lines as Strings as normal when +lines+ is used.  
@@ -1016,43 +1018,25 @@ which is aliased to #dump
  }
  rio('afile.yaml').yaml.dump(anobject)
 
-The YAML extension changes the way the grande copy operators
-interpret their argument. Rio#< (copy-from) and Rio#<< (append-from)
-treat an array as an array of objects which are converted using their 
-#to_yaml method before writing.
-
- rio('afile.yaml').yaml < [obj1, obj2, obj3]
-
-Because of this, copying an ::Array must be done like this:
-
- rio('afile.yaml').yaml < [anarray]
 
-If their argument is a Rio or ::IO it is iterate through as normal, 
-with each record converted using its to_yaml method.
-
-For all other objects, the result of their +to_yaml+ operator is simply written.
-
- rio('afile.yaml').yaml < anobject
-
-Rio#> (copy-to) and Rio#>> (append-to) will fill an array with with all selected
+IF::Grande#> (copy-to) and IF::Grande#>> (append-to) will fill an array with with all selected
 YAML documents in the Rio. For non-arrays, the yaml text is copied. (This may change
 if a useful reasonable alternative can be found)
  
  rio('afile.yaml').yaml > anarray # load all YAML documents from 'afile.yaml'
 
-Single objects can be written using Rio#putrec (aliased to Rio#putobj and Rio#dump)
+Single objects can be written using IF::GrandeStream#putrec (aliased to IF::YAML#putobj and IF::YAML#dump)
 
  rio('afile.yaml').yaml.putobj(anobject)
 
-Single objects can be loaded using Rio#getrec (aliase to Rio#getobj and Rio#load)
+Single objects can be loaded using IF::GrandeStream#getrec (aliase to IF::YAML#getobj and IF::YAML#load)
 
  anobject = rio('afile.yaml').yaml.getobj
 
-Note that other than this redefinition of what a record is and how the copy
-operators interpret their argument, a Rio in yaml-mode is just like any other
-Rio. And all the things you can do with any Rio come for free.
-They can be iterated over using #each and read into an array using #[]
-just like any other Rio. All the selection criteria are identical also.
+A Rio in yaml-mode is just like any other Rio. And all the things you
+can do with any Rio come for free.  They can be iterated over using
+IF::Grande#each and read into an array using IF::Grande#[] just like
+any other Rio. All the selection criteria are identical also.
 
 Get the first three objects into an array:
 
@@ -1068,10 +1052,6 @@ Selecting records using a Proc can be used as normal:
 
  anarray = rio('afile.yaml').yaml(proc{|anobject| ...}).to_a
 
-One could even use the copy operator to convert a CSV file to a YAML representation of
-the same data:
-
- rio('afile.yaml').yaml < rio('afile.csv').csv 
 
 
 ---
@@ -1080,6 +1060,7 @@ the same data:
 See also:
 * RIO::Doc::SYNOPSIS
 * RIO::Doc::HOWTO
+* RIO::Doc::EXAMPLES
 * RIO::Rio
 
 =end