rio 0.4.2 → 0.5.1

data/lib/rio/doc/OPTIONAL.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,113 +18,87 @@
 # 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
+# Please read the following first:
 # * RIO::Doc::INTRO
+# * RIO::Doc::SYNOPSIS
 # * RIO::Doc::HOWTO
-# * RIO::Doc::EXAMPLES
 # * RIO::Rio
 #
+# = Rio Optional Components
+#
+# This document describes various optional Rio components, that must be
+# explicitly 'required' to be available. These are not included in
+# rio.rb either because they change classes that should not be changed
+# without the developers explicit permission, or because they are not of
+# general enough interest.
+#
+# == to_rio
+#
+# This option comprises 4 options
+# * Object#to_rio
+#
+#     require 'rio/to_rio/object' 
+#     ario = any_object.to_rio
+#
+#   This option adds a to_rio method to the Object class which calls the
+#   object's #to_s method and passes it to the Rio constructor. Like:
+#
+#     ario = rio(any_object.to_s)
+#
+# * String#to_rio and String#/
+#
+#     require 'rio/to_rio/string'
+#     ario = "a/file/represented/as/a/string".to_rio
+#     ario = 'strings'/'used'/'with'/'subdirectory'/'operator'
+#
+#   This option adds a to_rio method and the subdirectory operator '/'
+#   to the String class. Note that due to operator precedance one must
+#   use parenthesis when calling a method directly on a Rio created
+#   using the subdirectory operator with Strings
+#
+#     array_of_first_ten_lines = ('adir'/'asubdir'/'afile').lines[0...10]  
+#
+# * Array#to_rio
+#
+#     require 'rio/to_rio/array'
+#     ario = %w[an array of path components].to_rio #=> rio('an/array/of/path/components')
+#
+#   This option adds a to_rio method to the Array class. This behaves as
+#   if 
+#    rio(%w[an array of path components]) had been called.
+#
+# * require 'rio/to_rio/all' will make all of the above available.
+#
+# == RIO.ARGV
+#
+#  require 'rio/argv'
+#  arguments_as_rios = RIO.ARGV
+#
+# This option provides a function which converts each element of ruby's
+# ARGV into a Rio.  Useful when writing a program which takes a list of
+# files as its arguments
+#
+# == RIO.popen3
+#
+#  require 'rio/open3'
+#  input,output,errput = RIO.popen3
+#  RIO.popen3 { |input,output,errput| ... }
+#
+# This options provides a wrapper around the Open3#popen3 call with the
+# IO objects converted to Rios
+#
+# == RIO.prompt
+#
+#  require 'rio/prompt'
+#  the_anwser = RIO.prompt('What is the answer? ')
+#
+# This option provides a module function to prompt for input.
 
-
-module RIO
-module Doc #:doc:
-=begin rdoc
-
-= Rio - Ruby I/O Facilitator
-
-Rio is a facade for most of the standard ruby classes that deal with I/O;
-providing a simple, intuitive, succinct interface to the functionality
-provided by IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO, OpenURI
-and others. Rio also provides an application level interface which allows many
-common I/O idioms to be expressed succinctly.
-
-Please read the following first:
-* RIO::Doc::INTRO
-* RIO::Doc::SYNOPSIS
-* RIO::Doc::HOWTO
-* RIO::Rio
-
-= Rio Optional Components
-
-This document describes various optional Rio components, that must be
-explicitly 'required' to be available. These are not included in
-rio.rb either because they change classes that should not be changed
-without the developers explicit permission, or because they are not of
-general enough interest.
-
-== to_rio
-
-This option comprises 4 options
-* Object#to_rio
-
-    require 'rio/to_rio/object' 
-    ario = any_object.to_rio
-
-  This option adds a to_rio method to the Object class which calls the
-  object's #to_s method and passes it to the Rio constructor. Like:
-
-    ario = rio(any_object.to_s)
-
-* String#to_rio and String#/
-
-    require 'rio/to_rio/string'
-    ario = "a/file/represented/as/a/string".to_rio
-    ario = 'strings'/'used'/'with'/'subdirectory'/'operator'
-
-  This option adds a to_rio method and the subdirectory operator '/'
-  to the String class. Note that due to operator precedance one must
-  use parenthesis when calling a method directly on a Rio created
-  using the subdirectory operator with Strings
-
-    array_of_first_ten_lines = ('adir'/'asubdir'/'afile').lines[0...10]  
-
-* Array#to_rio
-
-    require 'rio/to_rio/array'
-    ario = %w[an array of path components].to_rio #=> rio('an/array/of/path/components')
-
-  This option adds a to_rio method to the Array class. This behaves as
-  if 
-   rio(%w[an array of path components]) had been called.
-
-* require 'rio/to_rio/all' will make all of the above available.
-
-== RIO.ARGV
-
- require 'rio/argv'
- arguments_as_rios = RIO.ARGV
-
-This option provides a function which converts each element of ruby's
-ARGV into a Rio.  Useful when writing a program which takes a list of
-files as its arguments
-
-== RIO.popen3
-
- require 'rio/open3'
- input,output,errput = RIO.popen3
- RIO.popen3 { |input,output,errput| ... }
-
-This options provides a wrapper around the Open3#popen3 call with the
-IO objects converted to Rios
-
-== RIO.prompt
-
- require 'rio/prompt'
- the_anwser = RIO.prompt('What is the answer? ')
-
-This option provides a module function to prompt for input.
-
-
-=end
-module OPTIONAL
-end
-end
+module RIO::Doc::OPTIONAL
 end

data/lib/rio/doc/SYNOPSIS.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,26 +18,15 @@
 # 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
-#
 
 
 # :title: Rio
 
 module RIO
-# 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.
@@ -46,137 +35,127 @@ module RIO
 # 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 Facilitator
-
-fa-cil-i-tate:  To make easy or easier.
-
-Rio is a facade for most of the standard ruby classes that deal with I/O;
-providing a simple, intuitive, succinct interface to the functionality
-provided by IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO, OpenURI
-and others. Rio also provides an application level interface which allows many
-common I/O idioms to be expressed succinctly.
-
-
-== SYNOPSIS
-
-For the following assume:
- astring = ""
- anarray = []
-
-Iterate over the .rb files in a directory.
- rio('adir').files('*.rb') { |entrio| ... }
-
-Return an array of the .rb files in a directory.
- rio('adir').files['*.rb']
-
-Copy the .rb files in a directory.to another directory.
- rio('adir').files('*.rb') > rio('another_directory')
-
-Iterate over the .rb files in a directory and its subdirectories.
- rio('adir').all.files('*.rb') { |entrio| ... }
-
-Return an array of the .rb files in a directory and its subdirectories.
- rio('adir').all.files['*.rb']
-
-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 to another directory
- rio('adir') >> rio('another_directory')
-
-Copy a web-page to a file
- rio('http://rubydoc.org/') > rio('afile')
-
-Read a web-page into a string
- astring = rio('http://rubydoc.org/').read
-
-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
- 
-Iterate over selected lines of a file
- rio('adir').lines(0..3) { |aline| ... }       # a range of lines
- rio('adir').lines(/re/) { |aline| ... }       # by regular expression
- rio('adir').lines(0..3,/re/) { |aline| ... }  # or both
- 
-Return selected lines of a file as an array
- rio('adir').lines[0..3]       # a range of lines
- rio('adir').lines[/re/]       # by regular expression
- rio('adir').lines[0..3,/re/]  # or both
- 
-Iterate over selected chomped lines of a file
- rio('adir').chomp.lines(0..3) { |aline| ... }       # a range of lines
- rio('adir').chomp.lines(/re/) { |aline| ... }       # by regular expression
-
-Return selected chomped lines of a file as an array
- rio('adir').chomp[0..3]  # a range of lines
- rio('adir').chomp[/re/]  # by regular expression
- 
-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')
-
-Return an array of .rb files excluding symlinks to .rb files
- rio('adir').files('*.rb').skip[:symlink?]
-
-Put the first 10 chomped lines of a gzipped file into an array
- anarray =  rio('afile.gz').chomp.gzip[0...10] 
-
-Copy lines 0 and 3 thru 5 of a gzipped file on an ftp server to stdout
- rio('ftp://host/afile.gz').gzip.lines(0,3..5) > ?-
-
-Return an array of files in a directory and its subdirectories, without descending into .svn directories. 
- rio('adir').norecurse(/^\.svn$/).files[]
-
-Iterate over the non-empty, non-comment chomped lines of a file
- rio('afile').chomp.skip(: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').skiplines(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
-
-=== SUGGESTED READING
+module Doc #:doc:
 
-* RIO::Doc::INTRO
-* RIO::Doc::HOWTO
-* RIO::Rio
-* RIO::Doc::EXAMPLES
-* RIO::Doc::OPTIONAL
+##
+#
+# == SYNOPSIS
+#
+# For the following assume:
+#  astring = ""
+#  anarray = []
+#
+# Iterate over the .rb files in a directory.
+#  rio('adir').files('*.rb') { |entrio| ... }
+#
+# Return an array of the .rb files in a directory.
+#  rio('adir').files['*.rb']
+#
+# Copy the .rb files in a directory.to another directory.
+#  rio('adir').files('*.rb') > rio('another_directory')
+#
+# Iterate over the .rb files in a directory and its subdirectories.
+#  rio('adir').all.files('*.rb') { |entrio| ... }
+#
+# Return an array of the .rb files in a directory and its subdirectories.
+#  rio('adir').all.files['*.rb']
+#
+# 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 to another directory
+#  rio('adir') >> rio('another_directory')
+#
+# Copy a web-page to a file
+#  rio('http://rubydoc.org/') > rio('afile')
+#
+# Read a web-page into a string
+#  astring = rio('http://rubydoc.org/').read
+#
+# 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
+# 
+# Iterate over selected lines of a file
+#  rio('adir').lines(0..3) { |aline| ... }       # a range of lines
+#  rio('adir').lines(/re/) { |aline| ... }       # by regular expression
+#  rio('adir').lines(0..3,/re/) { |aline| ... }  # or both
+# 
+# Return selected lines of a file as an array
+#  rio('adir').lines[0..3]       # a range of lines
+#  rio('adir').lines[/re/]       # by regular expression
+#  rio('adir').lines[0..3,/re/]  # or both
+# 
+# Iterate over selected chomped lines of a file
+#  rio('adir').chomp.lines(0..3) { |aline| ... }       # a range of lines
+#  rio('adir').chomp.lines(/re/) { |aline| ... }       # by regular expression
+#
+# Return selected chomped lines of a file as an array
+#  rio('adir').chomp[0..3]  # a range of lines
+#  rio('adir').chomp[/re/]  # by regular expression
+# 
+# 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')
+#
+# Return an array of .rb files excluding symlinks to .rb files
+#  rio('adir').files('*.rb').skip[:symlink?]
+#
+# Put the first 10 chomped lines of a gzipped file into an array
+#  anarray =  rio('afile.gz').chomp.gzip[0...10] 
+#
+# Copy lines 0 and 3 thru 5 of a gzipped file on an ftp server to stdout
+#  rio('ftp://host/afile.gz').gzip.lines(0,3..5) > ?-
+#
+# Return an array of files in a directory and its subdirectories, without descending into .svn directories. 
+#  rio('adir').norecurse(/^\.svn$/).files[]
+#
+# Iterate over the non-empty, non-comment chomped lines of a file
+#  rio('afile').chomp.skip(: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').skiplines(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
+#
+# === SUGGESTED READING
+#
+# * RIO::Doc::INTRO
+# * RIO::Doc::HOWTO
+# * RIO::Rio
+# * RIO::Doc::EXAMPLES
+# * RIO::Doc::OPTIONAL
 
-=end
 module SYNOPSIS #:doc:
 end
 end