rio 0.3.1

data/lib/rio/doc/MISC.rb

@@ -0,0 +1,257 @@
+#--
+# =============================================================================== 
+# Copyright (c) 2005, 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
+#  rake rdoc
+# from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
+#
+# Suggested Reading
+# * RIO::Doc::SYNOPSIS
+# * RIO::Doc::INTRO
+# * RIO::Doc::HOWTO
+# * RIO::Rio
+#
+# <b>Rio is pre-alpha software. 
+# The documented interface and behavior is subject to change without notice.</b>
+
+
+module RIO
+module Doc
+=begin rdoc
+
+
+
+The following example 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 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 +bytes(n)+
+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 MISC
+end
+end
+end

data/lib/rio/doc/SYNOPSIS.rb

@@ -0,0 +1,170 @@
+#--
+# =============================================================================== 
+# Copyright (c) 2005, 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
+#  rake rdoc
+# from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
+#
+# Suggested Reading
+# * RIO::Doc::SYNOPSIS
+# * RIO::Doc::INTRO
+# * RIO::Doc::HOWTO
+# * RIO::Rio
+#
+# <b>Rio is pre-alpha software. 
+# The documented interface and behavior is subject to change without notice.</b>
+
+
+:title: Rio
+
+module RIO
+# Copyright (c) 2005, 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}[http://www.gnu.org/licenses/gpl.html] as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+module Doc #:doc:
+=begin rdoc
+
+= Rio - Ruby I/O Comfort Class
+
+Rio is a convenience class wrapping much of the functionality of 
+IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO, OpenURI, Zlib, and CSV.
+
+== SYNOPSIS
+For the following assume:
+ astring = ""
+ anarray = []
+
+Copy a file into a string
+ rio('afile') > astring 
+
+Copy the chomped lines of a file into an array
+ rio('afile').chomp > anarray
+ 
+Copy a file into another file
+ rio('afile') > rio('another_file')
+
+Copy a file into a directory
+ rio('afile') > rio('adir')
+
+Copy an entire directory structure into another directory
+ rio('adir') > rio('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
+ 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')
+
+Iterate over the entries in a directory
+ rio('adir').entries { |entrio| ... }
+
+Iterate over only the files in a directory
+ rio('adir').files { |entrio| ... }
+
+Iterate over only the .rb files in a directory
+ rio('adir').files('*.rb') { |entrio| ... }
+
+Create an array of the .rb entries in a directory
+ anarray = rio('adir')['*.rb']
+
+Iterate over the .rb files in a directory and its subdirectories
+ rio('adir').all.files('*.rb') { |entrio| ... }
+
+Create an array of the .rb entries in a directory and its subdirectories
+ anarray = rio('adir').all['*.rb']
+
+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
+ rio('adir').dirs.files('*.rb') > rio('another_directory')
+
+Iterate over the chomped lines of a file
+ rio('afile').chomp.lines { |line| ... }
+
+Put the chomped lines of a file into an array
+ anarray = rio('afile').chomp.lines[]
+
+Iterate over the first 10 chomped lines of a file
+ rio('afile').chomp.lines(0..9) { |line| ... }
+
+Put the first 10 chomped lines of a file into an array
+ anarray = rio('afile').chomp.lines[0..9]
+
+Copy the first 10 lines of a file into another file
+ rio('afile').lines(0..9) > rio('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] 
+
+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 
+
+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'
+ 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')
+
+=== SUGGESTED READING
+
+* RIO::Doc::INTRO
+* RIO::Doc::HOWTO
+* RIO::Rio
+
+=end
+module SYNOPSIS #:doc:
+end
+end
+end

data/lib/rio/entrysel.rb

@@ -0,0 +1,162 @@
+#--
+# =============================================================================== 
+# Copyright (c) 2005, 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
+#  rake rdoc
+# from the distribution directory. Then point your browser at the 'doc/rdoc' directory.
+#
+# Suggested Reading
+# * RIO::Doc::SYNOPSIS
+# * RIO::Doc::INTRO
+# * RIO::Doc::HOWTO
+# * RIO::Rio
+#
+# <b>Rio is pre-alpha software. 
+# The documented interface and behavior is subject to change without notice.</b>
+
+
+require 'rio/abstract_method'
+class ::Object #:nodoc: all
+  def true?() true end
+  def false?() false end
+end
+# 2314
+module RIO
+  module Match  #:nodoc: all
+    module Entry
+      class Base
+        attr_reader :match_to
+        def initialize(match_to)
+          @match_to = match_to
+        end
+        def inspect()
+          @match_to.to_s
+        end
+        def ===(el) self =~ el end 
+        abstract_method :=~
+                         
+      end
+      class Any < Base
+        def =~(entry) true end
+      end
+      class None < Base
+        def =~(entry) false end
+      end
+      class Glob < Base
+        def =~(entry) Impl::U.fnmatch?(entry.filename.to_s,@match_to) end
+      end
+      class Regexp < Base
+        def =~(entry) @match_to =~ entry.filename.to_s end
+      end
+      class Proc < Base
+        def =~(entry) @match_to[entry] end
+      end
+      class Symbol < Base
+        def =~(entry) entry.__send__(@match_to) end
+      end
+      def create(arg)
+        case arg
+        when ::String     then Glob.new(arg)
+        when ::Regexp     then Regexp.new(arg)
+        when ::Proc       then Proc.new(arg)
+        when ::Symbol     then Symbol.new(arg)
+        when ::TrueClass  then Any.new(arg)
+        when ::FalseClass then None.new(arg)
+        else raise ArgumentError,"a String,Regexp,Proc or Symbol is required (#{arg})"
+        end
+      end
+      module_function :create
+    end
+  end
+end
+module RIO
+  module Match
+    module Entry
+      class List
+        def callstr(func,*args)
+          self.class.to_s+'['+self.to_s+']'+'.'+func.to_s+'('+args.join(',')+')'
+        end
+        attr_reader :sym
+        attr_accessor :list
+        def initialize(sym,*args)
+          @sym = sym
+          @list = args.map { |arg| Match::Entry.create(arg) }
+        end
+        def inspect()
+          @sym.to_s+"("+@list.inspect+")"
+        end
+        def <<(el)
+          @list << el
+        end
+        def ===(me_list)
+          @sym == me_list.sym
+        end
+        def =~(el)
+          el.__send__(@sym) and (@list.empty? or @list.detect { |sel| sel =~ el })
+        end
+        extend Forwardable
+        def_instance_delegators(:@list,:each)
+      end
+      class Sels < Array
+        def <<(entry_list)
+          same_sym = self.grep(entry_list)
+          if same_sym.empty?
+            super
+          else
+            same_sym[0].list = entry_list.list
+          end
+        end
+      end
+      class Selector
+        def initialize(sel,nosel)
+          @sel = sel
+          @nosel = nosel
+        end
+        def inspect()
+          str = sprintf('#<Selector:0x%08x',self.object_id)
+          str += " @sel=#{@sel.inspect}"
+          str += " @nosel=#{@nosel.inspect}"
+          str += ">"
+          str
+        end
+
+        private
+
+        def yes?(el)
+          @sel.nil? or @sel.detect { |match_entry| match_entry =~ el }
+#          @sel.nil? or @sel.grep(el)
+        end
+        def no?(el)
+          @nosel.detect { |match_entry| match_entry =~ el } unless @nosel.nil?
+        end
+
+        public
+
+        def match?(el)
+          yes?(el) and not no?(el)
+        end
+      end
+    end
+    
+  end
+end