rio 0.4.2 → 0.5.1

data/lib/rio/context/skip.rb

@@ -1,6 +1,6 @@
 #--
-# =============================================================================== 
-# Copyright (c) 2005,2006,2007,2008 Christopher Kleckner
+# ===========================================================================
+# Copyright (c) 2005-2012 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -18,20 +18,9 @@
 # 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
-#
 
 
 require 'rio/context/cxx.rb'

data/lib/rio/context/stream.rb

@@ -1,6 +1,6 @@
 #--
-# =============================================================================== 
-# Copyright (c) 2005,2006,2007,2008 Christopher Kleckner
+# ===========================================================================
+# Copyright (c) 2005-2012 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -18,20 +18,9 @@
 # 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
-#
 
 
 require 'rio/context/cxx.rb'

data/lib/rio/cp.rb

@@ -1,6 +1,6 @@
 #--
-# =============================================================================== 
-# Copyright (c) 2005,2006,2007,2008 Christopher Kleckner
+# ===========================================================================
+# Copyright (c) 2005-2012 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -18,20 +18,9 @@
 # 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
-#
 
 
 require 'rio/exception/copy'
@@ -108,7 +97,6 @@ module RIO
           end
         end
         def cpfrom_array_(ary)
-          #p "CPFROM_ARRAY_"
           ary.inject(self) { |anio,el| anio << el }
         end
       end
@@ -163,14 +151,12 @@ module RIO
 
         def cpto_rio_(arg,sym)
           ario = ensure_rio(arg)
-          #p ario
           ario = ario.join(self.filename) if ario.dir?
+
           ario.cpclose {
             ario = ario.iostate(sym)
             self.copying(ario).each { |el|
-#              p el
               ario.putrec(el)
-#              ario << el
             }.copying_done(ario)
             ario
           }
@@ -198,10 +184,9 @@ module RIO
         end
         def cpfrom_rio_(arg)
           ario = ensure_rio(arg)
-          #p ario.cx
 
           ario.copying(self).each { |el|
-            self << el
+            self.putrec(el)
           }.copying_done(self)
         end
       end

data/lib/rio/cxuri.rb

@@ -0,0 +1,67 @@
+#--
+# ===========================================================================
+# Copyright (c) 2005-2012 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
+# =========================================================================== 
+#++
+#
+
+require 'forwardable'
+require 'rio/alturi'
+
+module RIO
+  class CxURI
+    def initialize(r)
+      case r
+      when ::RIO::Rio
+        u = r.uri
+        @parts = ::Alt::URI::Gen::URIParts.parse(u.to_s)
+        self.fragment = r.cx
+      else
+        @parts = ::Alt::URI::Gen::URIParts.parse(r.to_s)
+      end
+    end
+    def to_rio
+      nparts = @parts.clone
+      cx = self.fragment
+      nparts.fragment = nil
+      nrio = Rio.rio(nparts.to_s)
+      nrio.cx = cx
+      nrio
+    end
+    def fragment=(arg)
+      @parts.fragment = arg.nil? ? nil : YAML.dump(arg)
+    end
+    def fragment
+      YAML.load(@parts.fragment) unless @parts.fragment.nil?
+    end
+
+    extend Forwardable
+
+    def_delegators :@parts, :authority,:scheme,:path
+    def_delegators :@parts, :authority=,:scheme=,:path=,:query=,:query
+    def_delegators :@parts, :userinfo,:host
+    def_delegators :@parts, :userinfo=,:host=,:port=, :port
+    def to_s
+      @parts.uri
+    end
+
+
+  end
+end

data/lib/rio/dbg/trace_states.rb

@@ -0,0 +1,18 @@
+
+module RIO
+  module DBG
+    def trace_states(tf=true,&block)
+      old_trace_states = $trace_states
+      begin
+        $trace_states = tf
+        yield
+      ensure
+        $trace_states = old_trace_states
+      end
+    end
+    module_function :trace_states
+  end
+end
+
+
+

data/lib/rio/def.rb

@@ -1,6 +1,6 @@
 #--
-# =============================================================================== 
-# Copyright (c) 2005,2006,2007,2008 Christopher Kleckner
+# ===========================================================================
+# Copyright (c) 2005-2012 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -18,20 +18,9 @@
 # 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
-#
 
 require 'rio/base'
 

data/lib/rio/dir.rb

@@ -1,6 +1,6 @@
 #--
-# =============================================================================== 
-# Copyright (c) 2005,2006,2007,2008 Christopher Kleckner
+# ===========================================================================
+# Copyright (c) 2005-2012 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -18,29 +18,20 @@
 # 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
-#
 
 
-require 'rio/ops/path'
-require 'rio/ops/dir'
-require 'rio/filter/closeoneof'
-require 'rio/ioh'
+#require 'rio/ops/path'
+#require 'rio/ops/dir'
+#require 'rio/filter/closeoneof'
+#require 'rio/ioh'
+
 module RIO
   module Dir #:nodoc: all
     class Base < State::Base
+      fwd :data,:ioh
       include Ops::Path::Str
       def open?() !ioh.nil? end
     end

data/lib/rio/doc.rb

@@ -1,6 +1,6 @@
 #--
-# =============================================================================== 
-# Copyright (c) 2005,2006,2007,2008 Christopher Kleckner
+# ===========================================================================
+# Copyright (c) 2005-2012 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -18,20 +18,9 @@
 # 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
-#
 
 
 require 'rio'

data/lib/rio/doc/EXAMPLES.rb

@@ -1,6 +1,6 @@
 #--
-# =============================================================================== 
-# Copyright (c) 2005,2006,2007,2008 Christopher Kleckner
+# ===========================================================================
+# Copyright (c) 2005-2012 Christopher Kleckner
 # All rights reserved
 #
 # This file is part of the Rio library for ruby.
@@ -18,281 +18,268 @@
 # 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) { |line| ... }      # block will be called for the first 10 records
- rio('afile').lines[0...10]                     # 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
+##
+#
+# 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) { |line| ... }      # block will be called for the first 10 records
+#  rio('afile').lines[0...10]                     # 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