Piping Hot -- Rio 0.3.7

== 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, 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

Support for Pipe operator
 # Pipe multiple commands
 rio('afile') | rio(?-,'acmd') | 'another_cmd' | ?-

 # run the same series of commands, with different input and/or output
 cmdpipe = rio(?-,'acmd') | rio(?-,'another_cmd')
 rio('infile1') | cmdpipe | rio('outfile1')
 rio('infile2') | cmdpipe | rio('outfile2')

 cmdpipe2 = rio(?|,'cmd1','cmd2','outfile')   # create a cmdpipe Rio
 rio('infile1') | cmdpipe2       # run with input coming from a file
 rio(?-) | cmdpipe2              # same commands with input from stdin

Improved support for MS Windows path specifications
 rio('D:/adir/afile')
 rio('//ahost/adir/afile')

== 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")

== New for version 0.3.4

* New Grande Selection parameter.

  A major weakness of Rio's selection methods (lines, files, etc.)
  has always been that it only implemented a logical OR.

   rio('afile').lines(0..10,/Rio/) {...}
  iterates through lines that are in the range 0..10 OR 
  contain 'Rio'.

   rio('adir').files(:executable?,'*.rb') {...}
  iterates through files that are executable OR match '*.rb'

  Selecting files that matched both required using a proc.
   rio('adir').files(proc{ |f| f.executable? and f.fnmatch?('*.rb')}) {...}

  Rio's grande selection methods will now accept an array of conditions
  which must all be matched, in order to be selected. A logical AND.

   rio('adir').files([:executable?,'*.rb']) {...}
  
  The array, of course, need not be the only paramter. 

   rio('adir').files('*.exe',[:executable?,'*.rb']) {...}

  selects .exe files and .rb files that are executable.

* Renamed some of grande rejection methods. 
  (based on a suggestion by Gavin Sinclair)
   nolines => skiplines
   nofiles => skipfiles
  etc.

* New skip() grande method
   rio('afile').skip.lines(/Rio/)       # same as skiplines(/Rio/)
   rio('afile').lines(/Rio/).skip(0..9) # lines with 'Rio', exclude 
                                        # the first ten lines

* Alternative syntaxes for creating Rios that have no path.
   rio(?-)          # create a Rio refering to stdio
   rio(:stdio)      # same thing.
   rio.stdio        # same thing
   RIO.stdio        # ditto
   RIO::Rio.stdio   # once again

* From Pathname added
  * root?
  * mountpoint?
  * realpath
  * cleanpath

* Removed Rio#slurp in favor of Rio#contents.

* Added aliases for the copy operators. (suggested by Dave Burt)
   * copy_to >
   * append_to >>
   * copy_from <
   * append_from <<

* Bug fixes and corrections    
  
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, Christopher Kleckner. All rights reserved

== License
Rio is released under the GNU General Public License
(http://www.gnu.org/licenses/gpl.html)

-Christopher Kleckner