#--
# ===============================================================================
# Copyright (c) 2005,2006,2007 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
# ruby build_doc.rb
# from the distribution directory.
#
# Suggested Reading
# * RIO::Doc::SYNOPSIS
# * RIO::Doc::INTRO
# * RIO::Doc::HOWTO
# * RIO::Doc::EXAMPLES
# * RIO::Rio
#
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.
== HOWTO...
=== Read a single file
ario = rio('afile')
string = ""
array = []
* Read a file into a string.
# method 1
string = ario.contents
# method 2
ario > string
* Append a file onto a string.
# method 1
ario >> string
# method 2
string += ario.contents
* Read lines of a file into an array
# method 1
array = ario[]
# method 2
ario > array
# method 3
array = ario.to_a
# method 4
array = ario.readlines
* Append lines of a file into an array
# method 1
ario >> array
# method 2
array += ario.lines[]
* Read the first 10 lines of a file into an array
# method 1
array = ario[0...10]
# method 2
array = ario.lines[0...10]
# method 3
ario.lines(0...10) > array
* Read lines of a file into an array, with each line chomped
# method 1
array = ario.chomp[]
# method 2
array = ario.chomp.lines[]
# 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[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[/^\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
# method 2
string = rio('afile.gz').gzip.contents
* Append a gzipped file into a string
# method 1
rio('afile.gz').gzip >> string
# method 2
string += rio('afile.gz').gzip.contents
* Iterate through all the lines of a file
# method 1
rio('afile').lines { |line| ... }
# method 2
rio('afile').each { |line| ... }
# method 3
rio('afile').each_line { |line| ... }
* Iterate through the lines of a gzipped file
rio('afile.gz').gzip { |line| ... }
* Iterate through all non-empty lines of a gzipped file, with each line chomped
rio('afile.gz').gzip.chomp.skiplines(:empty?) { |line| ... }
* Iterate through the first 100 lines of a file
# method 1
rio('afile').lines(0...100) { |line| ... }
* 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').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[/^\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
array = ario.chomp[proc{ |line| line.length <= 1024}]
# method 2
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
ario = rio('afile')
string = "A String\n"
array = ["Line 0\n","Line 1\n"]
* Write a string to a file, leaving the Rio open
# method 1
ario.puts(string)
# method 2
ario.print(string)
# method 3
ario.noautoclose < string
* Write a string to a file and close the file
# method 1
rio('afile') < string
# method 2
ario.print!(string)
# method 3
ario.print(string).close
* Append a string to a file, leaving the Rio open
# method 1
ario.a.puts(string)
# method 2
ario.a.print(string)
# method 3
ario.noautoclose << string
* Append a string to a file and close the file
# method 1
rio('afile') << string
# method 2
rio('afile').a.print!(string)
# method 3
rio('afile').a.print(string).close
* Write an array to a file, leaving the Rio open
# method 1
ario = rio('afile').nocloseoncopy
ario << array
# method 2
ario.noautoclose < array
* Write an array to a file and close the file
# method 1
rio('afile') < array
---
=== Select records
ario = rio('afile')
string = ""
array = []
* Put lines one thru ten and line 100 into an array
# method 1
array = ario[0..9,99]
# method 2
array = ario.lines[0..9,99]
# method 3
ario.lines(0..9,99) > array
* Put lines one thru ten,line 100 and lines starting with 'rio4ruby' into an array
# method 1
array = ario[0..9,99,/^rio4ruby/]
# method 2
array = ario.lines[0..9,99,/^rio4ruby/]
# method 3
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 'rio4ruby' into another file
# method 1
ario.skiplines(/^rio4ruby/) > rio('another_file')
# method 2
ario.lines.skiplines(/^rio4ruby/) > rio('another_file')
# method 3
rio('another_file') < ario.skiplines(/^rio4ruby/)
* Copy the first 10 lines and lines starting with 'rio4ruby', but exclude any lines longer than 128 bytes
# method 1
ario.lines(0...10,/^rio4ruby/).skiplines(proc{ |l| l.length > 128}] > rio('another_file')
# method 2
rio('another_file') < ario.lines(0...10,/^rio4ruby/).skiplines(proc{ |l| l.length > 128})
---
=== Select directory entries
ario = rio('adir')
string = ""
array = []
* Put all entries with the extension '.txt' into an array
# method 1
array = ario['*.txt']
# method 2
array = ario[/\.txt$/]
# method 3
array = ario.entries['*.txt']
* Put all files with the extension '.txt' into an array
# method 1
array = ario.files['*.txt']
# method 2
array = ario.files[/\.txt$/]
# method 3
array = ario.files['*.txt']
* Put all entries with the extension '.txt' into an array, including those in subdirectories
# method 1
array = ario.all['*.txt']
# method 2
array = ario.all[/\.txt$/]
# method 3
array = ario.all.entries['*.txt']
* Put all entries with the extension '.txt' into an array, including those in subdirectories, except those
in subdirectories name '.svn'
# method 1
array = ario.norecurse('.svn').all['*.txt']
# method 2
array = ario.norecurse(/^\.svn$/).all[/\.txt$/]
# method 3
array = ario.norecurse('.svn').entries['*.txt']
# method 4
array = ario.entries('*.txt').norecurse('.svn').to_a
# method 5
array = ario.norecurse('.svn')['*.txt']
* Put all directories into an array
# method 1
array = ario.dirs[]
# method 2
array = ario.dirs.to_a
* Put all directories (recursively) into an array
# method 1
array = ario.all.dirs[]
# method 2
array = ario.all.dirs.to_a
* Put all entries (recursively) into an array, but limit the depth of recursion to 2
# method 1
array = ario.norecurse(3).to_a
* Iterate through ruby files in a directory and subdirectories skipping
those in the '.svn', and 'pkg' directories
# method 1
is_ruby_exe = proc{ |f| f.executable? and f[0][0] =~ /^#!.+ruby/ }
ario.norecurse('.svn','pkg').files('*.rb',is_ruby_exe) { |f| ... }
# method 2
is_ruby_exe = proc{ |f| f.executable? and f.gets =~ /^#!.+ruby/ }
ario.norecurse('.svn','pkg').files('*.rb',is_ruby_exe) { |f| ... }
* Put all files excluding those that are symlinks to files in an array
# method 1
array = ario.skipfiles[:symlink?]
# method 2
array = ario.skipfiles(:symlink?).files[]
# method 3
array = ario.skipfiles(:symlink?).to_a
# method 4
array = ario.files.skipfiles[:symlink?]
* Put all entries that are not files (or symlinks to files) into an array
# method 1
array = ario.skipfiles[]
# method 2
array = ario.skipfiles.to_a
* Put all entries that are symlinks to files into an array
# method 1
array = ario.files[proc{|f| f.file? and f.symlink?}]
# method 2
array = ario.files(proc{|f| f.file? and f.symlink?}).to_a
* Put all directories except those named '.svn' into an array
# method 1
array = ario.skipdirs['.svn']
# method 2
array = ario.skipdirs[/^\.svn$/]
# method 3
array = ario.skipdirs('.svn').to_a
# method 4
array = ario.skipdirs('.svn').dirs[]
# method 5
array = ario.skipdirs('.svn')[]
---
=== Read and writing files
ario = rio('afile')
string = ""
array = []
* Copy the contents of one file into another file
# method 1
rio('srcfile') > rio('dstfile')
# method 2
rio('dstfile') < rio('srcfile')
# method 3
rip('dstfile').print!(rio('srcfile').contents)
* Append the contents of one file to another file
# method 1
rio('srcfile') >> rio('dstfile')
# method 2
rio('dstfile') << rio('srcfile')
# method 3
rip('dstfile').a.print!(rio('srcfile').contents)
* Copy the first 10 lines of one file to another file
# method 1
rio('srcfile').lines(0...10) > rio('dstfile')
# method 2
rio('dstfile') < rio('srcfile').lines(0...10)
# method 3
rio('dstfile') < rio('srcfile').lines[0...10]
* Concatenate several files into one
# method 1
rio('dstfile') < [ rio('src1'), rio('src2'), rio('src3') ]
# method 2
rio('dstfile') < rio('src1') << rio('src2') << rio('src3')
* Copy a web page into a file
# method 1
rio('http://ruby-doc.org/') > rio('afile')
# method 2
rio('afile') < rio('http://ruby-doc.org/')
# method 3
rio('afile').print!(rio('http://ruby-doc.org/').contents)
* Append the output of the daytime server running on the localhost to a file
# method 1
rio("tcp://localhost:daytime") >> rio('afile')
# method 2
rio("tcp:",'localhost','daytime') >> rio('afile')
# method 3
rio('afile') << rio("tcp://:daytime")
# method 4
rio('afile') << rio("tcp://:13")
* Copy the first line and all lines containing 'http:' to a file
# method 1
rio('srcfile').lines(0,/http:/) > rio('dstfile')
# method 2
rio('dstfile') < rio('srcfile').lines(0,/http:/)
# method 3
rio('dstfile') < rio('srcfile').lines[0,/http:/]
# method 4
* Create a gzipped copy of a file
# method 1
rio('afile') > rio('afile.gz').gzip
# method 2
rio('afile.gz').gzip < rio('afile')
# method 3
rio('afile.gz').gzip.print!( rio('afile').contents )
* Create an ungzipped copy of a gzipped file
# method 1
rio('afile') < rio('afile.gz').gzip
# method 2
rio('afile.gz').gzip > rio('afile')
# method 3
rio('afile').print!( rio('afile.gz').gzip.contents )
* Copy the first 100 lines of gzipped file on a webserver into a local file
# method 1
rio('http://aserver/afile.gz').gzip.lines(0...100) > rio('afile')
* Create a file composed of a header from another file, the output of the 'ps' command, some text and
its creation time pulled from the daytime server running on your localhost
# method 1
rio('out') < [ rio('header'), rio(?-,'ps'), "Created on ", rio('tcp://:daytime') ]
# method 2
rio('out') < rio('header') << rio(?-,'ps') << "Created on: " << rio("tcp://:daytime")
---
=== Reading multiple files
ario = rio('adir')
string = ""
array = []
* Count the lines of code in a directory tree of ruby source files
# method 1
cnt = ario.all.files('*.rb').skiplines[/^\s*#/,/^\s*$/].size
# method 2
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
array = ario.files('*.txt').lines[]
# method 3
ario.files('*.txt').lines > array
* Concatanate the first line of all .txt files in a directory into an array
# method 1
array = ario.lines(0).files['*.txt']
# method 2
array = ario.files('*.txt').lines[0]
# method 3
ario.files('*.txt').lines(0) > array
* Copy all .txt files (but only their first ten lines) in a directory into another directiory
# method 1
ario.files('*.txt').lines(0...10) > rio('another_dir')
---
=== Read and write using Standard IO
string = ""
array = []
* Prompt for input and return what was typed
# method 1
ans = rio(?-).chomp.print("Type Something: ").gets
# method 2
stdio = rio(?-).chomp
ans = stdio.print("Type Something: ").gets
* Create a Rio tied to stdin or stdout, depending on how it is used
stdio = rio(?-)
* Create a Rio tied to stderr
stderr = rio(?=)
* Write a string to stdout
# method 1
rio(?-).puts("Hello World")
# method 2
rio(?-) << "Hello World\n"
# method 3
rio(?-) < "Hello World\n"
* Read a string from stdin with the input chomped
# method 1
ans = rio(?-).chomp.gets
# method 2
stdio = rio(?-).chomp
ans = stdio.gets
* Read from stdin until end of file with the result going into a string
# method 1
rio(?-) >> string
# method 2
rio(?-) > string
* Read from stdin until end of file with the chomped lines going into an array
# method 1
rio(?-).chomp >> array
# method 2
rio(?-).chomp > array
* Read from stdin until end of file with the result going into a file
# method 1
rio(?-) > rio('afile')
# method 2
rio('afile') < rio(?-)
* Read from stdin until end of file with the result appended to a file
# method 1
rio(?-) >> rio('afile')
# method 2
rio('afile') << rio(?-)
* Write a message to stderr
# method 1
rio(?=).puts("Hello Error")
# method 2
rio(?=) << "Hello Error\n"
# method 3
rio(?=) < "Hello Error\n"
* Dump a file to stdout
# method 1
rio('afile') > ?-
# method 2
rio('afile') > rio(?-)
# method 3
rio(?-) << rio('afile')
# method 4
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) > ?-
---
=== Reading and writing from processes as one might do with popen
* Read the output of the 'ps' command into an array without the header line or the line representing
the 'ps' command itself
ps = rio(?-,'ps -a').skiplines[0,/ps$/]
* Run an external program, copying its input from one location and its output to another,
and make it look very much like a shell command.
infile = rio(?","Hello Kitty\n")
outfile = rio('out.txt')
# method 1
cat = rio(?-,'cat').w!
cat <infile >outfile
# method 2
infile | 'cat' | outfile
---
=== Renaming and moving files
string = ""
array = []
* Rename the file 'a' to 'b'
# method 1
rio('a').rename('b')
# method 2
rio('a').rename.filename = 'b'
* Rename a file and leave the Rio referencing the files old name
ario = rio('a')
# method 1
ario.rename('b')
* Rename a file and change the Rio to reference the new file name
ario = rio('a')
# method 1
ario.rename!('b')
* Rename the file 'index.htm' to 'index.html'
# method 1
rio('index.htm').rename('index.html')
# method 2
rio('index.htm').rename.extname = '.html'
* Rename the file 'index.html' to 'welcome.html'
# method 1
rio('index.html').rename('welecome.html')
# method 2
rio('index.htm').rename.basename = 'welcome'
* Move a file from directory 'src' to directory 'dst'
# method 1
rio('src/afile').rename('dst/afile')
# method 2
rio('src/afile').rename.dirname = 'dst'
* 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 'rio4ruby' without changing its extension
# method 1
ario.rename.basename = 'rio4ruby'
* Change a file ending with '.tar.gz' to end with '.tgz'
# method 1
ario.rename.ext('.tar.gz').extname = '.tgz'
* Change the extension of all files with the extension '.htm' in a directory to have the
extension '.html'
# method 1
rio('adir').rename.files('*.htm') do |htmfile|
htmlfile.extname = '.html'
end
# method 2
rio('adir').files('*.htm') do |htmfile|
htmlfile.rename.extname = '.html'
end
* Change the extension of all files with the extension '.htm' in a directory and its
subdirectories to have the extension '.html'
# method 1
rio('adir').rename.all.files('*.htm') do |htmfile|
htmfile.extname = '.html'
end
# method 2
rio('adir').all.files('*.htm') do |htmfile|
htmfile.rename.extname = '.html'
end
* Move a file in an arbitrary directory into the current working directory.
# method 1
rio('arb/i/trary/di/rec/tory/afile').rename.dirname = '.'
---
=== Manipulate a Rio's path
string = ""
array = []
* Create a Rio with an additional subdirectory appended
ap = rio('adir')
# method 1
ap /= 'subdirectory'
# method 2
ap = ap.join('subdirectory')
# method 3
ap = rio(ap,'subdirectory')
* Create a Rio from an array of subdirectories
dirs = ['adir','subdir1','subdir2']
# method 1
ario = rio(dirs)
* Create an array of subdirectories from a Rio
# method 1
anarray = rio('adir/subdir1/subdir2').split
* Append a string to a path
# method 1
ario = rio('apath') + astring
# method 2
ario = rio('apath')
ario += astring
* create a directory 'links' with a symlink pointing to each .rb file in directory 'lib' (including subdirectories)
lib = rio('lib')
links = rio('links').delete!.mkdir
lib.all.files("*.rb") do |f|
f.symlink( f.dirname.sub(/^#{lib}/,links).mkdir )
end
----
Suggested Reading
* RIO::Doc::SYNOPSIS
* RIO::Doc::INTRO
* RIO::Rio
=end
module HOWTO
end
end
end