rio 0.3.8 → 0.3.9

data/README

@@ -1,4 +1,4 @@
-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.
@@ -18,30 +18,35 @@ along with Rio; if not, write to the Free Software
 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 
 
-<b>Rio is pre-alpha software. 
-The documented interface and behavior is subject to change without notice.</b>
-
 === 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.
+Rio wraps much of the functionality of IO, File, Dir, Pathname, FileUtils,
+Tempfile, StringIO, OpenURI, Zlib, and CSV.
+
+==== Building the documentation
 
 To create the documentation for Rio run the command
   ruby build_doc.rb
-from  the distribution directory.
+from the distribution directory.
 
 Then point your browser at the 'doc/rdoc' directory.
 
-Suggested Reading
+The RDoc template file included with the distribution contains some RDoc hacks
+that overcomes some of RDoc's weaknesses and makes the documentation *much* more
+usable. It is unadvisable to build the RDoc documentation without these.
+
+
+===== Suggested Reading
 * RIO::Doc::SYNOPSIS
 * RIO::Doc::INTRO
 * RIO::Doc::HOWTO
+* RIO::Doc::EXAMPLES
 * RIO::Rio
 
-To install Rio untar the distribution and type
-  ruby setup.rb config
-  ruby setup.rb setup
-  ruby setup.rb install
+==== Installation
+
+To install Rio from the distribution directory type
+  ruby setup.rb
 
 Rio is also available as a gem. If you have rubygems installed use:
   gem install rio
@@ -56,6 +61,7 @@ To read the documentation without running rdoc, read the files:
 * lib/rio/doc/HOWTO.rb
 * lib/rio/if/*.rb
 
+
 Project:: http://rubyforge.org/projects/rio/
 Documentation:: http://rio.rubyforge.org/
 Bugs:: http://rubyforge.org/tracker/?group_id=821

data/Rakefile

@@ -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.
@@ -41,32 +41,12 @@ require 'rake/testtask'
 $:.push 'lib'
 require 'rio/version'
 require 'rio/doc'
+require 'rio'
 
-SVN_REPOSITORY_URL = ''
+SVN_REPOSITORY_URL = 'svn+ssh://rio4ruby@rubyforge.org//var/svn/trunk/rio'
  
-SRC_FILES = FileList['lib/**/*.rb']
-DOC_FILES = FileList['README','lib/rio.rb','lib/rio/doc/*.rb',
-                     'lib/rio/if/*.rb','lib/rio/kernel.rb','lib/rio/constructor.rb']
-XMP_FILES = FileList['ex/*']
-
-module PKG
-  NAME = "rio"
-  TITLE = RIO::TITLE
-  VERSION = RIO::VERSION
-  FULLNAME = PKG::NAME + "-" + PKG::VERSION
-  SUMMARY = RIO::SUMMARY
-  DESCRIPTION = RIO::DESCRIPTION
-  FILES = FileList.new(['setup.rb', 'build_doc.rb', 'COPYING', 'Rakefile', 'ChangeLog', 'VERSION', 
-                        'test/**/*.rb','doc/**/*'] + SRC_FILES.to_a + DOC_FILES.to_a + XMP_FILES.to_a
-                       ) do |fl|
-    fl.exclude( /\bsvn\b/ )
-    fl.exclude( 'test/qp' )
-    fl.exclude( 'test/coverage' )
-    fl.exclude( 'doc/rdoc' )
-  end
-  OUT_DIR = 'pkg'
-  OUT_FILES = %w[.gem .tar.gz .zip].map { |ex| OUT_DIR + '/' + FULLNAME + ex }
-end
+require 'doc/pkg_def'
+
 ZIP_DIR = "/zip/ruby/rio"
 
 
@@ -84,47 +64,44 @@ task :prepare do
   ruby "setup.rb setup"
 end
 
-
 desc "Installs the package #{PKG::NAME}"
 task :install => [:prepare] do
   ruby "setup.rb install"
 end
 
-
 task :clean do
   ruby "setup.rb clean"
 end
 
-
 CLOBBER << "doc/rdoc"
 desc "Builds the documentation"
-task :doc => [:rdoc] do
+task :doc => [:rio_rdoc] do
     puts "\nGenerating online documentation..."
 #    ruby %{-I../lib ../bin/webgen -V 2 }
 end
 
-RDOC_OPTIONS = ['--line-numbers']
 rd = Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = 'doc/rdoc'
   rdoc.title    = PKG::TITLE
-  rdoc.options = RDOC_OPTIONS
+  rdoc.options = PKG::RDOC_OPTIONS
   rdoc.main = 'RIO::Doc::SYNOPSIS'
-  DOC_FILES.to_a.each do |glb|
-    next if glb =~ /yaml.rb$/
+  PKG::FILES::DOC.to_a.each do |glb|
+    #next if glb =~ /yaml.rb$/
     rdoc.rdoc_files.include( glb )
   end
   rdoc.template = 'doc/generators/template/html/rio.rb'
 end
 
-CLOBBER << "test/rio.log"
+desc "Build custom RDoc"
+task :rio_rdoc do 
+  require 'rio/doc/SYNOPSIS'
+  ruby "-Idoc/patched_rdoc -Ilib doc/bin/rdoc --show-hash --op doc/rdoc --title #{PKG::TITLE} --line-numbers  --template doc/generators/template/html/rio.rb #{PKG::FILES::DOC} --main #{RIO::Doc::SYNOPSIS}" 
+end
+CLOBBER << "test/log" << "test/qp"
 task :test do |t|
     sh "cd test;ruby -I../lib -I. runtests.rb"
 end
 
-#task :package => [:gen_files] do |var|
-#  require 'rio/kernel'
-#  rio(ZIP_DIR) << rio('pkg').files['*.tgz','*.tar.gz','*.zip','*.gem']
-#end
 task :ziparc do |var|
   require 'rio'
   #$trace_states = true
@@ -145,6 +122,7 @@ end
 #CLOBBER << "ChangeLog" << "VERSION" << "install.rb"
 
 task :gen_files => [:gen_changelog, :gen_version]
+#task :gen_files => [:gen_version]
 CLOBBER << "ChangeLog" << "VERSION" 
 task :no_old_pkg do
 #  unless Dir["pkg/#{PKG::FULLNAME}*"].empty?
@@ -162,7 +140,36 @@ task :package => [:no_old_pkg, :gen_files]
 Rake::PackageTask.new( PKG::NAME, PKG::VERSION ) do |p|
   p.need_tar_gz = true
   p.need_zip = true
-  p.package_files = PKG::FILES
+  p.package_files = PKG::FILES::DIST
+end
+
+Spec = Gem::Specification.new do |s|
+  s.name = PKG::NAME
+  s.version = PKG::VERSION
+  s.author = PKG::AUTHOR
+  s.email = PKG::EMAIL
+  s.homepage = "http://rio.rubyforge.org/"
+  s.rubyforge_project = "rio"
+
+  s.platform = Gem::Platform::RUBY
+  s.summary = PKG::SUMMARY
+  s.files = PKG::FILES::DIST.map { |rf| rf.to_s }
+
+  s.require_path = 'lib'
+  s.autorequire = 'rio'
+
+  s.has_rdoc = true
+
+  s.rdoc_options << PKG::RDOC_OPTIONS 
+end
+
+Rake::GemPackageTask.new(Spec) do |p| end
+
+desc "Build the Gem spec file for the rio package"
+task :gemspec => "pkg/rio.gemspec"
+file "pkg/rio.gemspec" => ["pkg", "Rakefile"] do |t|
+  puts PKG::FILES::DIST
+  open(t.name, "w") do |f| f.puts Spec.to_yaml end
 end
 
 desc "Make a new release (test,package,svn_version)"
@@ -194,55 +201,18 @@ task :svn_commit do
   sh cmd
 end
 
-if !defined? Gem
-  puts "Package Target requires RubyGEMs"
-else
-  spec = Gem::Specification.new do |s|
-
-    #### Basic information
-
-    s.name = PKG::NAME
-    s.version = PKG::VERSION
-    s.summary = PKG::SUMMARY
-    s.description = PKG::DESCRIPTION
-
-    #### Dependencies, requirements and files
-
-    s.files = PKG::FILES.to_a
-    # s.add_dependency( 'extensions', '>= 0.6.0' )
-
-    s.require_path = 'lib'
-    s.autorequire = 'rio'
-
-    #### Documentation
-
-    s.has_rdoc = true
-    #s.extra_rdoc_files = ['doc/generators/template/html/rio.rb']
-    s.rdoc_options << RDOC_OPTIONS 
-
-    #### Author and project details
-
-    s.author = "Christopher Kleckner"
-    s.email = "rio4ruby@rubyforge.org"
-    s.homepage = "http://rio.rubyforge.org/"
-    s.rubyforge_project = "rio"
-  end
-
-  Rake::GemPackageTask.new( spec ) do |pkg|
-    pkg.need_zip = true
-    pkg.need_tar_gz = true
-  end
-
-end
+#desc "Build the gem from the gemspec"
+#task :buildgem => ['rio.gemspec'] do
+#  cmd = "gem build 'rio.gemspec'"
+#  sh cmd
+#end
 
-=begin
-desc "Creates a tag in the repository"
-task :tag do
-  repositoryPath = File.dirname( $1 ) if `svn info` =~ /^URL: (.*)$/
-  fail "Tag already created in repository " if /#{PKG::NAME}/ =~ `svn ls #{repositoryPath}/versions`
-  sh "svn cp -m 'Created version #{PKG::NAME}' #{repositoryPath}/trunk #{repositoryPath}/versions/#{PKG::NAME}"
+GEM_FILENAME = "pkg/#{Spec.full_name}.gem"
+desc "Install development gem"
+task :installgem => [GEM_FILENAME] do
+  cmd = "gem install #{GEM_FILENAME}"
+  sh cmd
 end
-=end
 
 desc "Upload documentation to homepage"
 task :uploaddoc => [:rdoc] do
@@ -281,7 +251,7 @@ task :statistics do
   total_lines = 0
   total_code = 0
   show_line( "File Name", "Lines", "LOC" )
-  SRC_FILES.each do |fn|
+  PKG::FILES::SRC.each do |fn|
     lines, codelines = count_lines fn
     show_line( fn, lines, codelines )
     total_lines += lines

data/build_doc.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 #--
 # =============================================================================== 
-# 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.
@@ -28,32 +28,32 @@
 
 $:.unshift 'lib'
 require 'rio'
+require 'rio/prompt'
+require 'doc/pkg_def'
 
 module DFLT
   RDOC_DIR = rio('doc/rdoc')
 end
 
-puts "Rio interactive RDoc installer."
+#puts "Rio interactive RDoc installer."
 
-rdoc_dir = rio(?-).print!("Where shall I build the rdoc documentation[#{DFLT::RDOC_DIR}]: ").chomp.gets.strip
+rdoc_dir = RIO.promptd('Where shall I build the rdoc documentation',DFLT::RDOC_DIR)
 rdoc_dir = DFLT::RDOC_DIR if rdoc_dir.empty?
 rdoc_dir = rio(rdoc_dir)
 
-puts "Building the Rio RDoc documentation in '#{rdoc_dir}'"
+argv = []
+argv << '--op' << rdoc_dir.to_s
+argv += PKG::RDOC_OPTIONS
+argv += PKG::FILES::DOC
 
-RDOC_OPTIONS = ['--line-numbers', '-m RIO::Doc::SYNOPSIS',"--op #{rdoc_dir}", "-T doc/generators/template/html/rio"]
-
-rdoc_files = [
-  rio('README'), 
-  rio('lib/rio.rb'),
-  rio('lib/rio/')['kernel.rb','constructor.rb'],
-  rio('lib/rio/doc')['*.rb'],
-  rio('lib/rio/if').skipfiles('yaml.rb').files['*.rb'],
-]
-
-cmd = sprintf("rdoc %s %s",RDOC_OPTIONS.join(' '),rdoc_files.join(' '))
-
-rio(?-,cmd) > ?-
+require 'rdoc/rdoc'
+begin
+  r = RDoc::RDoc.new
+  r.document(argv)
+rescue RDoc::RDocError => e
+  $stderr.puts e.message
+  exit(1)
+end
 
 docindex = (rdoc_dir/'index.html').abs.to_url
 msg = "Please point your browser at '#{docindex}'" 
@@ -63,5 +63,7 @@ puts
 puts lin
 puts "> " + msg + " >"
 puts lin
+__END__
+
 
 

data/doc/ANNOUNCE

@@ -1,4 +1,4 @@
-Rio 0.3.8
+Rio 0.3.9
 
 == Overview
 
@@ -10,36 +10,7 @@ interfaces provided by IO, File, and Dir to an appropriate object, Rio
 provides a "grande" interface that allows many common application
 level I/O and file-system tasks to be expressed succinctly.
 
-== New
-
-Enhanced support for FTP file-systems. All of Rio's most powerful
-idioms are now supported seamlessly on FTP servers.
-
- # copy a file from or to an FTP server
- rio('ftp://ahost/adir/afile') > rio('localfile') # server -> local file
- rio('ftp://ahost/adir/afile') < rio('localfile') # local file -> server
-
- # copy an entire directory structure from or to an FTP server
- rio('ftp://ahost/adir') > rio('localdir') # server -> local directory
- rio('ftp://ahost/adir') < rio('localdir') # local directory -> server
-
-All of Rio's grande selection and filtering options are available for
-files and directories on FTP servers.
-
- # create a gzipped copy of a web page on an ftp server
- rio('ftp://ftphost/f.html.gz').gzip < rio('http://httphost/f.html')
-
- # dump the first 10 lines of a gzipped log file on an FTP server to stdout
- rio('ftp://ftphost/logfile.txt').lines(0...10) > ?-
-
- # iterate through the entries of a directory on an FTP server
- rio('ftp://ftphost/adir').entries { |entrio| ... }
-
- # get an array of all .rb files on an ftp server
- rb_files = rio('ftp://ftphost/').all.files['*.rb']
-
-
-== SYNOPSIS
+= SYNOPSIS
 
 For the following assume:
  astring = ""
@@ -156,7 +127,7 @@ Bugs:: http://rubyforge.org/tracker/?group_id=821
 Email:: rio4ruby@rubyforge.org
 
 == Copyright
-Copyright (c) 2005, 2006 Christopher Kleckner. All rights reserved
+Copyright (c) 2005,2006,2007 Christopher Kleckner. All rights reserved
 
 == License
 Rio is released under the GNU General Public License

data/doc/RELEASE_NOTES

@@ -1,8 +1,3 @@
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-Rio is pre-alpha software. 
-The documented interface and behaviour is subject to change without notice.
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
 === Rio - Ruby I/O Comfort Class
 
 Rio is a convenience class wrapping much of the functionality of 
@@ -20,6 +15,10 @@ Suggested Reading
 * RIO::Doc::HOWTO
 * RIO::Rio
 
+== New for version 0.3.9
+* Bug fixes, code cleanup, 
+
+
 == New for version 0.3.8
 * Enhanced support for FTP file-systems. All of Rio's most powerful
   idioms are now supported seamlessly on FTP servers.

data/doc/RIOIS

@@ -0,0 +1,215 @@
+Rio IS
+
+=== EASY
+
+Anything that does I/O is a Rio:
+
+File:	   
+ rio('aflile')
+Directory: 
+ rio('adir')
+Web Page:  
+ rio('http://ahost/adir/afile')
+Any IO:    
+ rio(any_io)
+
+... much more
+
+Makes common tasks easy
+
+ rio('afile') > rio('copy of afile')
+ rio('adir') > rio('copy of adir')
+ rio('gzipped_file.gz').gzip > rio('ungzipped_file')
+ chomped_lines = rio('afile').chomp[]
+
+... much more
+
+=== Powerful
+
+ rb_files= rio('adir').files['*.rb']
+ rb_files_including_those_in_subdirectories = rio('adir').all.files['*.rb']
+ first_ten_lines_chomped = rio('afile').chomp[0..9]
+ first_ten_lines_chomped_from_gzipped_file = rio('afile.gz').gzip.chomp[0..9]
+ first_ten_lines_chomped_from_gzipped_file_on_ftp_server = rio('ftp://ahost/afile.gz').gzip.chomp[0..9]
+
+... much more
+
+=== Consistent
+
+To iterate, add a block: 
+ rio('afile').lines(/regular_expression/) { |line| ... }
+ rio('adir').files('
+To return an array, use a subscript: 
+ rio('afile').lines[/regular_expression/]
+To copy use the copy-operator: 
+ rio('afile').lines(/regular_expression/) > rio('destination_file')
+
+
+
+
+
+
+
+== Overview
+
+Rio is a Ruby I/O convenience class wrapping much of the functionality
+of IO, File and Dir. Rio also uses FileUtils, Tempfile, StringIO,
+OpenURI, Net::FTP, Zlib, and CSV to provide similar functionality
+using a simple consistent interface. In addition to forwarding the
+interfaces provided by IO, File, and Dir to an appropriate object, Rio
+provides a "grande" interface that allows many common application
+level I/O and file-system tasks to be expressed succinctly.
+
+== New
+
+Enhanced support for FTP file-systems. All of Rio's most powerful
+idioms are now supported seamlessly on FTP servers.
+
+ # copy a file from or to an FTP server
+ rio('ftp://ahost/adir/afile') > rio('localfile') # server -> local file
+ rio('ftp://ahost/adir/afile') < rio('localfile') # local file -> server
+
+ # copy an entire directory structure from or to an FTP server
+ rio('ftp://ahost/adir') > rio('localdir') # server -> local directory
+ rio('ftp://ahost/adir') < rio('localdir') # local directory -> server
+
+All of Rio's grande selection and filtering options are available for
+files and directories on FTP servers.
+
+ # create a gzipped copy of a web page on an ftp server
+ rio('ftp://ftphost/f.html.gz').gzip < rio('http://httphost/f.html')
+
+ # dump the first 10 lines of a gzipped log file on an FTP server to stdout
+ rio('ftp://ftphost/logfile.txt').lines(0...10) > ?-
+
+ # iterate through the entries of a directory on an FTP server
+ rio('ftp://ftphost/adir').entries { |entrio| ... }
+
+ # get an array of all .rb files on an ftp server
+ rb_files = rio('ftp://ftphost/').all.files['*.rb']
+
+
+== SYNOPSIS
+
+For the following assume:
+ astring = ""
+ anarray = []
+
+Copy or append a file to a string
+ rio('afile') > astring      # copy
+ rio('afile') >> astring     # append
+
+Copy or append a string to a file
+ rio('afile') < astring      # copy
+ rio('afile') << astring     # append
+
+Copy or append the lines of a file to an array
+ rio('afile') > anarray     
+ rio('afile') >> anarray
+ 
+Copy or append a file to another file
+ rio('afile') > rio('another_file')  
+ rio('afile') >> rio('another_file') 
+
+Copy a file to a directory
+ rio('adir') << rio('afile')
+
+Copy a directory structure to another directory
+ rio('adir') >> rio('another_directory')
+
+Copy a web-page to a file
+ rio('http://rubydoc.org/') > rio('afile')
+
+Ways to get the chomped lines of a file into an array
+ anarray = rio('afile').chomp[]         # subscript operator
+ rio('afile').chomp > anarray           # copy-to operator
+ anarray = rio('afile').chomp.to_a      # to_a
+ anarray = rio('afile').chomp.readlines # IO#readlines
+ 
+Copy a gzipped file un-gzipping it
+ rio('afile.gz').gzip > rio('afile')
+
+Copy a plain file, gzipping it
+ rio('afile.gz').gzip < rio('afile')
+
+Copy a file from a ftp server into a local file un-gzipping it
+ rio('ftp://host/afile.gz').gzip > rio('afile')
+
+Iterate over the entries in a directory
+ rio('adir').entries { |entrio| ... }
+
+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| ... }
+
+Iterate over .rb files but not symlinks to .rb files
+ rio('adir').files('*.rb').skip(:symlink?) { |entrio| ... }
+
+Iterate over only the _dot_ files in a directory
+ rio('adir').files(/^\./) { |entrio| ... }
+
+Iterate over the files in a directory and its subdirectories, skipping
+'.svn' and 'CVS' directories
+
+ rio('adir').norecurse(/^\.svn$/,'CVS').files { |entrio| ... }
+
+Create an array of the .rb entries in a directory
+ anarray = rio('adir')['*.rb']
+
+Create an array of the .rb entries in a directory and its
+subdirectories.
+ anarray = rio('adir').all['*.rb']
+
+Iterate over the .rb files in a directory and its subdirectories
+ rio('adir').all.files('*.rb') { |entrio| ... }
+
+Iterate over the non-empty, non-comment chomped lines of a file
+ rio('afile').chomp.skip.lines(:empty?,/^\s*#/) { |line| ... }
+
+Copy the output of th ps command into an array, skipping the header
+line and the ps command entry
+ rio(?-,'ps -a').skip.lines(0,/ps$/) > anarray 
+
+Prompt for input and return what was typed
+ ans = rio(?-).print("Type Something: ").chomp.gets 
+
+Change the extension of all .htm files in a directory and its
+subdirectories to .html
+ rio('adir').rename.all.files('*.htm') do |htmfile|
+   htmfile.extname = '.html'
+ end
+
+Create a symbolic link 'asymlink' in 'adir' which refers to
+'adir/afile'
+ rio('adir/afile').symlink('adir/asymlink')
+
+Copy a CSV file, changing the separator to a semicolon
+ rio('comma.csv').csv > rio('semicolon.csv').csv(';')
+
+Iterate through a CSVfile with each line parsed into an array
+ rio('afile.csv').csv { |array_of_fields| ...}
+
+Create a tab separated file of accounts in a UNIX passwd file,
+listing only the username, uid, and realname fields
+ rio('/etc/passwd').csv(':').columns(0,2,4) > rio('rpt').csv("\t")
+
+Pipe multiple commands
+ rio('afile') | rio(?-,'acmd') | 'another_cmd' | ?-
+
+== Contact
+
+Project:: http://rubyforge.org/projects/rio/
+Documentation:: http://rio.rubyforge.org/
+Bugs:: http://rubyforge.org/tracker/?group_id=821
+Email:: rio4ruby@rubyforge.org
+
+== Copyright
+Copyright (c) 2005,2006,2007 Christopher Kleckner. All rights reserved
+
+== License
+Rio is released under the GNU General Public License
+(http://www.gnu.org/licenses/gpl.html)
+
+-Christopher Kleckner