HOWTO.rb in rio-0.4.0

- old
+ new

@@ -36,14 +36,17 @@
 
 module RIO
 module Doc #:doc:
 =begin rdoc
 
-= Rio - Ruby I/O Comfort Class
+= Rio - Ruby I/O Facilitator
 
-Rio is a convenience class wrapping much of the functionality of 
-IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO, OpenURI, Zlib, and CSV.
+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.
 
 == HOWTO...
 
 === Read a single file
    ario = rio('afile')
@@ -94,18 +97,22 @@
    # method 3
    ario.chomp > array
 
 * Append the first 10 lines of a file into an array, with each line chomped
    # method 1
-   array += ario.chomp.lines[0...10]
+   array += ario.chomp[0...10]
    # method 2
+   array += ario.chomp.lines[0...10]
+   # method 3
    ario.chomp.lines(0...10) >> array
 
 * Read all lines starting with 'require' into an array, with each line chomped
    # method 1
-   array = ario.chomp.lines[/^\s*require/]
+   array = ario.chomp[/^\s*require/]
    # method 2
+   array = ario.chomp.lines[/^\s*require/]
+   # method 3
    ario.chomp.lines(/^\s*require/) > array
 
 * Read a gzipped file into a string
    # method 1
    rio('afile.gz').gzip > string
@@ -139,25 +146,29 @@
 
 * Iterate through the first line and all ruby comment lines in a gzipped file
    rio('afile.rb.gz').gzip.lines(0,/^\s*#/) { |line| ... }
 
 * Iterate through the lines of a ruby file that are neither empty nor comments, with all lines chomped
-   rio('afile.rb.gz').chomp.skiplines(/^\s*#/,:empty?) { |line| ... }
+   rio('afile.rb').chomp.skiplines(/^\s*#/,:empty?) { |line| ... }
 
 * Read all the comment lines from a ruby file into an array with all lines chomped
    # method 1
-   array = rio('afile.rb').chomp.lines[/^\s*#/]
+   array = rio('afile.rb').chomp[/^\s*#/]
    # method 2
+   array = rio('afile.rb').chomp.lines[/^\s*#/]
+   # method 3
    rio('afile.rb').chomp.lines(/^\s*#/) > array
   
 
 * Read lines of a file into an array, with each line chomped, skipping any lines longer than 1024 chars
    # method 1
-   ario.chomp.lines(proc{ |line| line.length <= 1024}) > array
+   array = ario.chomp[proc{ |line| line.length <= 1024}]
    # method 2
-   array = ario.chomp.skiplines[proc{ |line| line.length > 1024}]
+   ario.chomp.lines(proc{ |line| line.length <= 1024}) > array
    # method 3
+   array = ario.chomp.skiplines[proc{ |line| line.length > 1024}]
+   # method 4
    array = ario.chomp.lines(proc{ |line| line.length <= 1024}).to_a
 
 ---
 
 === Write to a single file
@@ -219,43 +230,45 @@
 
 * Put lines one thru ten and line 100 into an array
    # method 1
    array = ario[0..9,99]
    # method 2
-   array = ario[0...10,99..99]
+   array = ario.lines[0..9,99]
    # method 3
-   ario(0..9,99) > array
+   ario.lines(0..9,99) > array
   
-* Put lines one thru ten,line 100 and lines starting with 'zippy' into an array
+* Put lines one thru ten,line 100 and lines starting with 'rio4ruby' into an array
    # method 1
-   array = ario[0..9,99,/^zippy/]
+   array = ario[0..9,99,/^rio4ruby/]
    # method 2
-   array = ario[0...10,99..99,/^zippy/]
+   array = ario.lines[0..9,99,/^rio4ruby/]
    # method 3
-   ario(0..9,99,/^zippy/) > array
+   ario.lines(0..9,99,/^rio4ruby/) > array
   
 * Put lines that are longer than 128 bytes into an array
    # method 1
    array = ario[proc{ |l| l.length > 128}]
    # method 2
    array = ario.lines[proc{ |l| l.length > 128}]
    # method 3
    array = ario.skiplines[proc{ |l| l.length <= 128}]
+   # method 4
+   array = ario.skip.lines[proc{ |l| l.length <= 128}]
   
-* Copy all lines that do not start with 'zippy' into another file
+* Copy all lines that do not start with 'rio4ruby' into another file
    # method 1
-   ario.skiplines(/^zippy/) > rio('another_file')
+   ario.skiplines(/^rio4ruby/) > rio('another_file')
    # method 2
-   ario.lines.skiplines(/^zippy/) > rio('another_file')
+   ario.lines.skiplines(/^rio4ruby/) > rio('another_file')
    # method 3
-   rio('another_file') < ario.skiplines(/^zippy/)
+   rio('another_file') < ario.skiplines(/^rio4ruby/)
   
-* Copy the first 10 lines and lines starting with 'zippy', but exclude any lines longer than 128 bytes
+* Copy the first 10 lines and lines starting with 'rio4ruby', but exclude any lines longer than 128 bytes
    # method 1
-   ario.lines(0...10,/^zippy/).skiplines(proc{ |l| l.length > 128}] > rio('another_file')
+   ario.lines(0...10,/^rio4ruby/).skiplines(proc{ |l| l.length > 128}] > rio('another_file')
    # method 2
-   rio('another_file') < ario.lines(0...10,/^zippy/).skiplines(proc{ |l| l.length > 128})
+   rio('another_file') < ario.lines(0...10,/^rio4ruby/).skiplines(proc{ |l| l.length > 128})
   
 
 
 ---
 
@@ -456,13 +469,13 @@
    string = ""
    array = []
 
 * Count the lines of code in a directory tree of ruby source files
    # method 1
-   cnt = ario.all.files('*.rb').chomp.skiplines(/^\s*#/,/^\s*$/).inject(0) { |sum,l|  sum += 1 }
+   cnt = ario.all.files('*.rb').skiplines[/^\s*#/,/^\s*$/].size
    # method 2
-   cnt = ario.all.files('*.rb').chomp.skiplines[/^\s*#/,/^\s*$/].size
+   cnt = ario.all.files('*.rb').skiplines(/^\s*#/,/^\s*$/).inject(0) { |sum,l|  sum += 1 }
 
 * Concatanate the contents of all .txt files in a directory into an array
    # method 1
    array = ario.lines.files['*.txt']
    # method 2
@@ -548,23 +561,25 @@
    # method 3
    rio(?=) < "Hello Error\n"
 
 * Dump a file to stdout
    # method 1
-   rio(?-) << rio('afile')
+   rio('afile') > ?-
    # method 2
-   rio('afile') >> rio(?-)
-   # method 3
    rio('afile') > rio(?-)
+   # method 3
+   rio(?-) << rio('afile')
    # method 4
-   rio(?-) < rio('afile')
+   rio('afile') >> ?-
    # method 5
+   rio(?-) < rio('afile')
+   # method 6
    rio(?-).print(rio('afile').contents)
 
 * Emulate a simplified unix 'head' command which reads from stdin and writes the first 10 lines to stdout
    # method 1
-   rio(?-).lines(0..9) > rio(?-)
+   rio(?-).lines(0..9) > ?-
 
 ---
 
 === Reading and writing from processes as one might do with popen 
 
@@ -627,13 +642,13 @@
 
 * Change a file to have the extension '.html' leaving the rest of it as is
    # method 1
    ario.rename.extname = '.html'
 
-* Change a files basename to 'zippy' without changing its extension
+* Change a files basename to 'rio4ruby' without changing its extension
    # method 1
-   ario.rename.basename = 'zippy'
+   ario.rename.basename = 'rio4ruby'
 
 * Change a file ending with '.tar.gz' to end with '.tgz'
    # method 1
    ario.rename.ext('.tar.gz').extname = '.tgz'
 
@@ -676,10 +691,9 @@
    ap /= 'subdirectory'   
    # method 2
    ap = ap.join('subdirectory')
    # method 3
    ap = rio(ap,'subdirectory')
-   # method 4
 
 * Create a Rio from an array of subdirectories
    dirs = ['adir','subdir1','subdir2']
    # method 1
    ario = rio(dirs)