<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Module: RIO::Doc::INTRO</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<link rel="stylesheet" href="../../.././rdoc-style.css" type="text/css" media="screen" />
<script type="text/javascript">
// <![CDATA[
function popupCode( url ) {
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
}
function toggleCode( id ) {
if ( document.getElementById )
elem = document.getElementById( id );
else if ( document.all )
elem = eval( "document.all." + id );
else
return false;
elemStyle = elem.style;
if ( elemStyle.display != "block" ) {
elemStyle.display = "block"
} else {
elemStyle.display = "none"
}
return true;
}
// Make codeblocks hidden by default
document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
// ]]>
</script>
</head>
<body>
<div id="classHeader">
<table class="header-table">
<tr class="top-aligned-row">
<td class="class-mod"><strong>Module</strong></td>
<td class="class-name-in-header">RIO::Doc::INTRO</td>
<td rowspan="2" class="class-header-space-col"></td>
<td rowspan="2">
<a class="in-url" href="../../../files/lib/rio/doc/INTRO_rb.html">
lib/rio/doc/INTRO.rb
</a>
</td>
</tr>
</table>
</div>
<!-- banner header -->
<div id="bodyContent">
<div id="contextContent">
<div id="description">
<h1><a href="../Rio.html">Rio</a> - Ruby I/O Comfort Class</h1>
<p>
<a href="../Rio.html">Rio</a> is a convenience class wrapping much of the
functionality of IO, File, Dir, Pathname, FileUtils, Tempfile, StringIO,
and OpenURI and uses Zlib, and CSV to extend that functionality using a
simple consistent interface. Most of the instance methods of IO, File and
Dir are simply forwarded to the appropriate handle to provide identical
functionality. <a href="../Rio.html">Rio</a> also provides a
"grande" interface that allows many application level IO tasks to
be accomplished in line or two of code.
</p>
<p>
<a href="../Rio.html">Rio</a> functionality can be broadly broken into
three categories
</p>
<ul>
<li>path manipulation
</li>
<li>file system access
</li>
<li>stream manipulation
</li>
</ul>
<p>
Which methods are available to a given <a href="../Rio.html">Rio</a>,
depends on the underlying object.
</p>
<p>
A <a href="../Rio.html">Rio</a> generally does not need to be opened or
have its mode specified. Most of <a href="../Rio.html">Rio</a>’s
methods simply configure it. When an actual IO operation is specified, <a
href="../Rio.html">Rio</a> determines how to open it based on the object it
is opening, the operation it is performing, and the options specified.
</p>
<p>
<a href="../Rio.html">Rio</a> configuration methods return the <a
href="../Rio.html">Rio</a> for easy chaining and regard the presence of a
block as an implied <tt>each</tt>.
</p>
<h2>Using a <a href="../Rio.html">Rio</a></h2>
<p>
Using a <a href="../Rio.html">Rio</a> can be described as having 3 steps:
</p>
<ul>
<li>Creating a <a href="../Rio.html">Rio</a> (using the constructor or as the
result of one of path manipulation methods)
</li>
<li>Configuring a <a href="../Rio.html">Rio</a>
</li>
<li><a href="../Rio.html">Rio</a> I/O
</li>
</ul>
<h3>Creating a <a href="../Rio.html">Rio</a></h3>
<p>
<a href="../Rio.html">Rio</a> extends <a
href="../../Kernel.html">Kernel</a> with one function <tt>rio</tt>, its
constructor. This function is overloaded to create any type of <a
href="../Rio.html">Rio</a>. <tt>rio</tt> looks at the class and sometimes
the value of its first argument to create an internal representation of the
resource specified, additional arguments are used as needed by the resource
type. The rio constructor does not initiate any io, it does not check for a
resources existance or type. It neither knows nor cares what can be done
with this <a href="../Rio.html">Rio</a>. Using methods like +respond_to?+
are meaningless at best and usually misleading.
</p>
<p>
For purposes of discussion, we divide Rios into two catagories, those that
have a path and those that don’t.
</p>
<h4>Creating a <a href="../Rio.html">Rio</a> that has a path</h4>
<p>
To create a <a href="../Rio.html">Rio</a> that has a path the arguments to
<tt>rio</tt> may be:
</p>
<ul>
<li>a string representing the entire path. The separator used for Rios is as
specified in RFC1738 (’/’).
<pre>
rio('adir/afile')
</pre>
</li>
<li>a string representing a fully qualified <tt>file</tt> URI as per RFC1738
<pre>
rio('file:///atopleveldir/adir/afile')
</pre>
</li>
<li>a <tt>URI</tt> object representing a <tt>file</tt> or generic <tt>URI</tt>
<pre>
rio(URI('adir/afile'))
</pre>
</li>
<li>the components of a path as separate arguments
<pre>
rio('adir','afile')
</pre>
</li>
<li>the components of a path as an array
<pre>
rio(%w/adir afile/)
</pre>
</li>
<li>another <a href="../Rio.html">Rio</a>
<pre>
another_rio = rio('adir/afile')
rio(another_rio)
</pre>
</li>
<li>any object whose <tt>to_s</tt> method returns one of the above
<pre>
rio(Pathname.new('apath'))
</pre>
</li>
<li>any combination of the above either as separate arguments or as elements of
an array,
<pre>
another_rio = rio('dir1/dir2')
auri = URI('dir4/dir5)
rio(another_rio,'dir3',auri,'dir6/dir7')
</pre>
</li>
</ul>
<h5>Creating a <a href="../Rio.html">Rio</a> that refers to a web page</h5>
<p>
To create a <a href="../Rio.html">Rio</a> that refers to a web page the
arguments to <tt>rio</tt> may be:
</p>
<ul>
<li>a string representing a fully qualified <tt>http</tt> URI
<pre>
rio('http://ruby-doc.org/index.html')
</pre>
</li>
<li>a <tt>URI</tt> object representing a <tt>http</tt> <tt>URI</tt>
<pre>
rio(URI('http://ruby-doc.org/index.html'))
</pre>
</li>
<li>either of the above with additional path elements
<pre>
rio('http://www.ruby-doc.org/','core','classes/Object.html')
</pre>
</li>
</ul>
<h5>Creating a <a href="../Rio.html">Rio</a> that refers to a file or directory on a FTP server</h5>
<p>
To create a <a href="../Rio.html">Rio</a> that refers to a file on a FTP
server the arguments to <tt>rio</tt> may be:
</p>
<ul>
<li>a string representing a fully qualified <tt>ftp</tt> URI
<pre>
rio('ftp://user:password@ftp.example.com/afile.tar.gz')
</pre>
</li>
<li>a <tt>URI</tt> object representing a <tt>ftp</tt> <tt>URI</tt>
<pre>
rio(URI('ftp://ftp.example.com/afile.tar.gz'))
</pre>
</li>
<li>either of the above with additional path elements
<pre>
rio('ftp://ftp.gnu.org/pub/gnu','emacs','windows','README')
</pre>
</li>
</ul>
<h4>Creating Rios that do not have a path</h4>
<p>
To create a <a href="../Rio.html">Rio</a> without a path, the first
argument to <tt>rio</tt> is usually a single character.
</p>
<h5>Creating a <a href="../Rio.html">Rio</a> that refers to a clone of your programs stdin or stdout.</h5>
<p>
<tt>rio(?-)</tt> (mnemonic: ’-’ is used by some Unix programs
to specify stdin or stdout in place of a file)
</p>
<p>
Just as a <a href="../Rio.html">Rio</a> that refers to a file, does not
know whether that file will be opened for reading or writing until an io
operation is specified, a +stdio:+ <a href="../Rio.html">Rio</a> does not
know whether it will connect to stdin or stdout until an io operation is
specified.
</p>
<h5>Creating a <a href="../Rio.html">Rio</a> that refers to a clone of your programs stderr.</h5>
<p>
<tt>rio(?=)</tt> (mnemonic: ’-’ refers to fileno 1, so
’=’ refers to fileno 2)
</p>
<h5>Creating a <a href="../Rio.html">Rio</a> that refers to an arbitrary IO object.</h5>
<pre>
an_io = ::File.new('afile')
rio(an_io)
</pre>
<h5>Creating a <a href="../Rio.html">Rio</a> that refers to a file descriptor</h5>
<p>
<tt>rio(?#,fd)</tt> (mnemonic: a file descriptor is a number
’#’ )
</p>
<pre>
an_io = ::File.new('afile')
rio(an_io)
</pre>
<h5>Creating a <a href="../Rio.html">Rio</a> that refers to a StringIO object</h5>
<p>
<tt>rio(?")</tt> (mnemonic: ’"’ surrounds strings)
</p>
<ul>
<li>create a <a href="../Rio.html">Rio</a> that refers to its own string
</li>
</ul>
<pre>
rio(?")
</pre>
<ul>
<li>create a <a href="../Rio.html">Rio</a> that refers to a string of your
choosing
</li>
</ul>
<pre>
astring = ""
rio(?","")
</pre>
<h5>Creating a <a href="../Rio.html">Rio</a> that refers to a Tempfile object</h5>
<p>
<tt>rio(??)</tt> (mnemonic: ’?’ you don’t know its name)
</p>
<pre>
rio(??)
rio(??,basename='rio',tmpdir=Dir::tmpdir)
</pre>
<h5>Creating a <a href="../Rio.html">Rio</a> that refers to an arbitrary TCPSocket</h5>
<pre>
rio('tcp:',hostname,port)
</pre>
<p>
or
</p>
<pre>
rio('tcp://hostname:port')
</pre>
<h5>Creating a <a href="../Rio.html">Rio</a> that runs an external program and connects to its stdin and stdout</h5>
<p>
<tt>rio(?-,cmd)</tt> (mnemonic: ’-’ is used by some Unix
programs to specify stdin or stdout in place of a file)
</p>
<p>
or
</p>
<p>
<tt>rio(?`,cmd)</tt> (mnemonic: ’`’ (backtick) runs an external
program in ruby)
</p>
<p>
This is <a href="../Rio.html">Rio</a>’s interface to IO#popen
</p>
<h3>Path Manipulation</h3>
<p>
<a href="../Rio.html">Rio</a>’s path manipulation methods are for the
most part simply forwarded to the File or URI classes with the return
values converted to a <a href="../Rio.html">Rio</a>.
</p>
<h4>Creating a <a href="../Rio.html">Rio</a> from a <a href="../Rio.html">Rio</a>’s component parts.</h4>
<p>
The <a href="../Rio.html">Rio</a> methods for creating a <a
href="../Rio.html">Rio</a> from a <a href="../Rio.html">Rio</a>’s
component parts are <a href="../Rio.html#M000093">Rio#dirname</a>, <a
href="../Rio.html#M000095">Rio#filename</a>, <a
href="../Rio.html#M000092">Rio#basename</a>, and <a
href="../Rio.html#M000094">Rio#extname</a>. The behavior of <a
href="../Rio.html#M000092">Rio#basename</a> depends on the setting of the
<tt>ext</tt> configuration variable and is different from its counterpart
in the File class. The default value of the <tt>ext</tt> configuration
variable is the string returned File#extname. The <tt>ext</tt>
configuration variable can be changed using <a
href="../Rio.html#M000089">Rio#ext</a> and <a
href="../Rio.html#M000090">Rio#noext</a> and can be queried using <a
href="../Rio.html#M000089">Rio#ext</a>?. This value is used by calls to <a
href="../Rio.html#M000092">Rio#basename</a>.
</p>
<p>
<a href="../Rio.html#M000095">Rio#filename</a> returns the last component
of a path, and is basically the same as <tt>basename</tt> without
consideration of an extension. So
</p>
<pre>
rio('afile.txt').basename #=> rio('afile')
rio('afile.txt').filename #=> rio('afile.txt')
ario = rio('afile.tar.gz')
ario.basename #=> rio('afile.tar')
ario.ext? #=> ".gz"
ario.ext('.tar.gz').basename #=> rio('afile')
ario.ext? #=> ".tar.gz"
</pre>
<h4>Changing a path’s component parts.</h4>
<p>
<a href="../Rio.html">Rio</a> also provides methods for changing the
component parts of its path. They are <a
href="../Rio.html#M000093">Rio#dirname</a>=, <a
href="../Rio.html#M000095">Rio#filename</a>=, <a
href="../Rio.html#M000092">Rio#basename</a>=, and <a
href="../Rio.html#M000094">Rio#extname</a>=. These methods replace the part
extracted as described above with their argument.
</p>
<pre>
ario = rio('dirA/dirB/afile.rb')
ario.dirname = 'dirC' # rio('dirC/afile.rb')
ario.basename = 'bfile' # rio('dirC/bfile.rb')
ario.extname = '.txt' # rio('dirC/bfile.txt')
ario.filename = 'cfile.rb' # rio('dirC/cfile.rb')
</pre>
<p>
<a href="../Rio.html">Rio</a> also has a <tt>rename</tt> mode which causes
each of these to rename the actual file system object as well as changing
the <a href="../Rio.html">Rio</a>. This is discussed in the section on
Renaming and Moving.
</p>
<h4>Splitting a <a href="../Rio.html">Rio</a></h4>
<p>
<a href="../Rio.html#M000101">Rio#split</a> returns an array of Rios, one
for each path element. (Note that this behavior differs from File#split.)
</p>
<pre>
rio('a/b/c').split #=> [rio('a'),rio('b'),rio('c')]
</pre>
<p>
The array returned is extended with a <tt>to_rio</tt> method, which will
put the parts back together again.
</p>
<pre>
ary = rio('a/b/c').split #=> [rio('a'),rio('b'),rio('c')]
ary.to_rio #=> rio('a/b/c')
</pre>
<h4>Creating a <a href="../Rio.html">Rio</a> by specifying the individual parts of its path</h4>
<p>
The first way to create a <a href="../Rio.html">Rio</a> by specifying its
parts is to use the <a href="../Rio.html">Rio</a> constructor <a
href="../Rio.html#M000006">Rio#rio</a>. Since a <a
href="../Rio.html">Rio</a> is among the arguments the constructor will
take, the constructor can be used.
</p>
<pre>
ario = rio('adir')
rio(ario,'b') #=> rio('adir/b')
</pre>
<p>
<a href="../Rio.html#M000100">Rio#join</a> and <a
href="../Rio.html">Rio</a>#/ do the same thing, but the operator version
<tt>/</tt> can take only one argument.
</p>
<pre>
a = rio('a')
b = rio('b')
c = a.join(b) #=> rio('a/b')
c = a/b #=> rio('a/b')
</pre>
<p>
The arguments to <tt>join</tt> and <tt>/</tt> do not need to be Rios, of
course
</p>
<pre>
ario = rio('adir')
ario/'afile.rb' #=> rio('ario/afile.rb')
ario.join('b','c','d') #=> rio('ario/b/c/d')
ario/'b'/'c'/'d' #=> rio('ario/b/c/d')
ario /= 'e' #=> rio('ario/b/c/d/e')
</pre>
<h4>Manipulating a <a href="../Rio.html">Rio</a> path by treating it as a string.</h4>
<p>
The <a href="../Rio.html">Rio</a> methods which treat a <a
href="../Rio.html">Rio</a> as a string are <a
href="../Rio.html#M000104">Rio#sub</a>, <a
href="../Rio.html#M000105">Rio#gsub</a> and <a
href="../Rio.html">Rio</a>#+. These methods create a new <a
href="../Rio.html">Rio</a> using the string created by forwarding the
method to the String returned by <a
href="../Rio.html#M000008">Rio#to_s</a>.
</p>
<pre>
ario = rio('dirA/dirB/afile') + '-1.1.1' # rio('dirA/dirB/afile-1.1.1')
brio = ario.sub(/^dirA/, 'dirC') # rio('dirC/dirB/afile-1.1.1')
</pre>
<h4>Creating a <a href="../Rio.html">Rio</a> based on its relationship to another</h4>
<p>
<a href="../Rio.html#M000087">Rio#abs</a> creates a new rio whose path is
the absolute path of a <a href="../Rio.html">Rio</a>. If provided with an
argument, it uses that as the base path, otherwise it uses an internal base
path (usually the current working directory when it was created).
</p>
<pre>
rio('/tmp').chdir do
rio('a').abs #=> rio('/tmp/a')
rio('a').abs('/usr') #=> rio('/usr/a')
end
</pre>
<p>
<a href="../Rio.html#M000088">Rio#rel</a> creates a new rio with a path
relative to a <a href="../Rio.html">Rio</a>.
</p>
<pre>
rio('/tmp').chdir do
rio('/tmp/a').rel #=> rio('a')
end
rio('/tmp/b').rel('/tmp') #=> rio('b')
</pre>
<p>
<a href="../Rio.html#M000114">Rio#route_to</a> and <a
href="../Rio.html#M000113">Rio#route_from</a> creates a new rio with a path
representing the route to get to/from a <a href="../Rio.html">Rio</a>. They
are based on the methods of the same names in the URI class
</p>
<h3>Configuring a <a href="../Rio.html">Rio</a></h3>
<p>
The second step in using a rio is configuring it. Note that many times no
configuration is necessary and that this is not a comprehensive list of all
of <a href="../Rio.html">Rio</a>’s configuration methods.
</p>
<p>
<a href="../Rio.html">Rio</a>’s configuration mehods fall into three
categories.
</p>
<dl>
<dt>IO manipulators</dt><dd>An IO manipulator alters the behavior of a <a
href="../Rio.html">Rio</a>’s underlying IO object. These affect the
behaviour of I/O methods which are forwarded directly to the underlying
object as well as the grande I/O methods.
</dd>
<dt>Grande configuration methods</dt><dd>The grande configuration methods affect the behaviour of <a
href="../Rio.html">Rio</a>’s grande I/O methods
</dd>
<dt>Grande selection methods</dt><dd>The grande selection methods select what data is returned by <a
href="../Rio.html">Rio</a>’s grande I/O methods
</dd>
</dl>
<p>
All of <a href="../Rio.html">Rio</a>’s configuration and selection
methods can be passed a block, which will cause the <a
href="../Rio.html">Rio</a> to behave as if <tt>each</tt> had been called
with the block after the method.
</p>
<h4>IO manipulators</h4>
<ul>
<li><tt>gzip</tt> a file on output, and ungzip it on input
<pre>
rio('afile.gz').gzip
</pre>
<p>
This causes the rio to read through a Zlib::GzipReader and to write
Zlib::GzipWriter.
</p>
</li>
<li><tt>chomp</tt> lines as they are read
<pre>
rio('afile').chomp
</pre>
<p>
This causes a <a href="../Rio.html">Rio</a> to call String#chomp on the the
String returned by all line oriented read operations.
</p>
</li>
</ul>
<h4>Grande configuration methods</h4>
<ul>
<li><tt>all</tt>, <tt>recurse</tt>, <tt>norecurse</tt>
<pre>
rio('adir').all
rio('adir').norecurse('CVS')
</pre>
<p>
These methods instruct the <a href="../Rio.html">Rio</a> to also include
entries in subdirectories when iterating through directories and control
which subdirectories are included or excluded.
</p>
</li>
<li><tt>bytes</tt>
<pre>
rio('afile').bytes(1024)
</pre>
<p>
This causes a <a href="../Rio.html">Rio</a> to read the specified number of
bytes at a time as a file is iterated through.
</p>
</li>
</ul>
<h4>Grande selection methods</h4>
<ul>
<li><tt>lines</tt>, <tt>nolines</tt>
<pre>
rio('afile').lines(0..9)
rio('afile').nolines(/^\s*#/)
</pre>
<p>
Strictly speaking these are both configuration and selection methods. They
configure the <a href="../Rio.html">Rio</a> to iterate through an input
stream as lines. The arguments select which lines are actually returned.
Lines are included (<tt>lines</tt>) or excluded (<tt>nolines</tt>) if they
match <b>any</b> of the arguments as follows.
</p>
<p>
If the argument is a:
</p>
<table>
<tr><td valign="top"><tt>RegExp</tt>:</td><td>the line is matched against it
</td></tr>
<tr><td valign="top"><tt>Range</tt>:</td><td>the lineno is matched against it
</td></tr>
<tr><td valign="top"><tt>Integer</tt>:</td><td>the lineno is matched against it as if it were a one element range
</td></tr>
<tr><td valign="top"><tt>Symbol</tt>:</td><td>the symbol is <tt>sent</tt> to the string; the line is included unless it
returns false
</td></tr>
<tr><td valign="top"><tt>Proc</tt>:</td><td>the proc is called with the line as an argument; the line is included
unless it returns false
</td></tr>
</table>
</li>
<li><tt>entries</tt>, <tt>files</tt>, <tt>dirs</tt>, <tt>noentries</tt>,
<tt>nofiles</tt>, <tt>nodirs</tt>
<pre>
rio('adir').files('*.txt')
rio('adir').nofiles(/^\./)
</pre>
<p>
These methods select which entries will be returned when iterating throug
directories. Entries are included
(<tt>entries</tt>,<tt>files</tt>,<tt>dirs</tt>) or
excluded(<tt>noentries</tt>,<tt>nofiles</tt>,<tt>nodirs</tt>) if they match
<b>any</b> of the arguments as follows.
</p>
<p>
If the argument is a:
</p>
<table>
<tr><td valign="top"><tt>String</tt>:</td><td>the arg is treated as a glob; the filname is matched against it
</td></tr>
<tr><td valign="top"><tt>RegExp</tt>:</td><td>the filname is matched against it
</td></tr>
<tr><td valign="top"><tt>Symbol</tt>:</td><td>the symbol is <tt>sent</tt> to the entry (a <a href="../Rio.html">Rio</a>);
the entry is included unless it returns false
</td></tr>
<tr><td valign="top"><tt>Proc</tt>:</td><td>the proc is called with the entry (a <a href="../Rio.html">Rio</a>) as an
argument; the entry is included unless it returns false
</td></tr>
</table>
</li>
<li><tt>records</tt>, <tt>rows</tt>, <tt>norecords</tt>, <tt>norows</tt>
<pre>
rio('afile').bytes(1024).records(0...10)
</pre>
<p>
These select items from an input stream just as <tt>lines</tt>, but without
specifying lines as the input record type. They can be used to select
different record types in extension modules. The only such module at this
writing is the CSV extension. In that case <tt>records</tt> causes each
line of a CSV file to be parsed into an array while <tt>lines</tt> causes
each line of the file to be returned normally.
</p>
</li>
</ul>
<h3><a href="../Rio.html">Rio</a> I/O</h3>
<p>
As stated above the the three steps to using a <a
href="../Rio.html">Rio</a> are:
</p>
<ul>
<li>Creating a <a href="../Rio.html">Rio</a>
</li>
<li>Configuring a <a href="../Rio.html">Rio</a>
</li>
<li>Doing I/O
</li>
</ul>
<p>
This section describes that final step.
</p>
<p>
After creating and configuring a <a href="../Rio.html">Rio</a>, the
file-system has not been accessed, no socket has been opened, not so much
as a test for a files existance has been done. When an I/O method is called
on a <a href="../Rio.html">Rio</a>, the sequence of events required to
complete that operation on the underlying object takes place. <a
href="../Rio.html">Rio</a> takes care of creating the apropriate object (eg
IO,Dir), opening the object with the apropriate mode, performing the
operation, closing the object if required, and returning the results of the
operation.
</p>
<p>
<a href="../Rio.html">Rio</a>’s I/O operations can be divide into two
catagories:
</p>
<ul>
<li>Proxy operations
</li>
<li>Grande operations
</li>
</ul>
<h4>Proxy operations</h4>
<p>
These are calls which are forwarded to the underlying object (eg
IO,Dir,Net::FTP), after apropriately creating and configuring that object.
The result produced by the method is returned, and the object is closed.
</p>
<p>
In some cases the result is modified before being returned, as when a <a
href="../Rio.html">Rio</a> is configured with <tt>chomp</tt>.
</p>
<p>
In all cases, if the result returned by the underlying object, could itself
be used for further I/O operations it is returned as a <a
href="../Rio.html">Rio</a>. For example: where File#dirname returns a
string, <a href="../Rio.html#M000093">Rio#dirname</a> returns a <a
href="../Rio.html">Rio</a>; where Dir#read returns a string representing a
directory entry, <a href="../Rio.html#M000039">Rio#read</a> returns a <a
href="../Rio.html">Rio</a>.
</p>
<p>
With some noteable exceptions, most of the operations available if one were
using the underlying Ruby I/O class are available to the <a
href="../Rio.html">Rio</a> and will behave identically.
</p>
<p>
For things that exist on a file system:
</p>
<ul>
<li>All the methods in FileTest are available as <a href="../Rio.html">Rio</a>
instance methods. For example
<pre>
FileTest.file?('afile')
</pre>
<p>
becomes
</p>
<pre>
rio('afile').file?
</pre>
</li>
<li>All the instance methods of <tt>File</tt> except <tt>path</tt> are
available to a rio without change
</li>
<li>Most of the class methods of <tt>File</tt> are available.
<ul>
<li>For those that take a filename as their only argument the calls are mapped
to <a href="../Rio.html">Rio</a> instance methods as described above for
FileTest.
</li>
<li><tt>dirname</tt>, and <tt>readlink</tt> return Rios instead of strings
</li>
<li><a href="../Rio.html">Rio</a> has its own <a
href="../Rio.html#M000092">Rio#basename</a>, <a
href="../Rio.html#M000100">Rio#join</a> and <a
href="../Rio.html#M000036">Rio#symlink</a>, which provide similar
functionality.
</li>
<li>The class methods which take multiple filenames
(<tt>chmod</tt>,<tt>chown</tt>,<tt>lchmod</tt>,<tt>lchown</tt>) are
available as <a href="../Rio.html">Rio</a> instance methods. For example
<pre>
File.chmod(0666,'afile')
</pre>
<p>
becomes
</p>
<pre>
rio('afile').chmod(06660)
</pre>
</li>
</ul>
</li>
</ul>
<p>
For I/O Streams
</p>
<p>
Most of the instance methods of IO are available, and most do the same
thing, with some interface changes. <b>The big exception to this is the
’<<’ operator.</b> This is one of <a
href="../Rio.html">Rio</a>’s grande operators. While the symantics
one would use to write to an IO object would actually accomplish the same
thing with a <a href="../Rio.html">Rio</a>, It is a very different
operator. Read the section on grande operators. The other differences
between IO instance methods and the <a href="../Rio.html">Rio</a>
equivelence can be summarized as follows.
</p>
<ul>
<li>The simple instance methods (eg <tt>fcntl</tt>, <tt>eof?</tt>,
<tt>tty?</tt> etc.) are forwarded and the result returned as is
</li>
<li>Anywhere IO returns an IO, <a href="../Rio.html">Rio</a> returns a <a
href="../Rio.html">Rio</a>
</li>
<li><tt>close</tt> and its cousins return the <a href="../Rio.html">Rio</a>.
</li>
<li><tt>each_byte</tt> and <tt>each_line</tt> are forwarded as is.
</li>
<li>All methods which read (read*,get*,each*) will cause the file to closed
when the end of file is reached. This behavior is configurable, but the
default is to close on eof
</li>
<li>The methods which write (put*,print*) are forwarded as is; put* and print*
return the <a href="../Rio.html">Rio</a>; write returns the value returned
by IO#write; as mentioned above ’<<’ is a grande operator
in <a href="../Rio.html">Rio</a>.
</li>
</ul>
<p>
For directories:
</p>
<ul>
<li>all the instance methods of Dir are available except <tt>each</tt> which is
a grande method.
</li>
<li>the class methods <tt>mkdir</tt>, <tt>delete</tt>, <tt>rmdir</tt> are
provided as instance methods.
</li>
<li><tt>chdir</tt> is provided as an instance method. <a
href="../Rio.html#M000018">Rio#chdir</a> returns a <a
href="../Rio.html">Rio</a> and passes a <a href="../Rio.html">Rio</a> to a
block if one is provided.
</li>
<li><tt>glob</tt> is provided as an instance method, but returns an array of
Rios
</li>
<li><tt>foreach</tt> is not supported
</li>
<li><tt>each</tt> and <tt>[]</tt> have similar functionality provided by <a
href="../Rio.html">Rio</a>
</li>
</ul>
<p>
For other Rios, instance methods are generally forwarded where appropriate.
For example
</p>
<ul>
<li>Rios that refer to StringIO objects forward ‘string’ and
‘string=’
</li>
<li>Rios that refer to http URIs support all the Meta methods provided by
open-uri
</li>
</ul>
<h4>Grande operators</h4>
<p>
The primary grande operator is <a href="../Rio.html#M000046">Rio#each</a>.
<tt>each</tt> is used to iterate through Rios. When applied to a file it
iterates through records in the file. When applied to a directory it
iterates through the entries in the directory. Its behavior is modified by
configuring the <a href="../Rio.html">Rio</a> prior to calling it using the
configuration methods discussed above. Since iterating through things is
ubiquitous in ruby, it is implied by the presence of a block after any of
the grande configuration methods and many times does not need to be call
explicitly. For example:
</p>
<pre>
rio('afile.rb').chomp.lines(/^\s*#/) { |line| ... } # iterate through chomped ruby comment lines
rio('adir').all.files('*.rb') { |f| ... } # iterate through all .rb files in 'adir' and its subdirectories
</pre>
<p>
Because a <a href="../Rio.html">Rio</a> is an Enumerable, it supports
<tt>to_a</tt>, which is the basis for the grande subscript operator. <a
href="../Rio.html">Rio</a>#[] with no arguments simply calls to_a. With
arguments it behaves as if those arguments had been passed to the most
recently called of the grande selection methods listed above, and then
calls to_a. For example to get the first ten lines of a file into an array
with lines chomped
</p>
<pre>
rio('afile').chomp.lines(0...10).to_a
</pre>
<p>
can be written as
</p>
<pre>
rio('afile.gz').chomp.lines[0...10]
</pre>
<p>
or, to create an array of all the .c files in a directory, one could write
</p>
<pre>
rio('adir').files['*.c']
</pre>
<p>
The other grande operators are its copy operators. They are:
</p>
<ul>
<li><tt><</tt> (copy-from)
</li>
<li><tt><<</tt> (append-from)
</li>
<li><tt>></tt> (copy-to)
</li>
<li><tt>>></tt> (append-to)
</li>
</ul>
<p>
The only difference between the ‘copy’ and ‘append’
versions is how they deal with an unopened resource. In the former the open
it with mode ‘w’ and in the latter, mode ‘a’.
Beyond that, their behavior can be summarized as:
</p>
<pre>
source.each do |entry|
destination << entry
end
</pre>
<p>
Since they are based on the <tt>each</tt> operator, all of the selection
and configuration options are available. And the right-hand-side argument
of the operators are not restricted to Rios — Strings and Arrays are
also supported.
</p>
<p>
For example:
</p>
<pre>
rio('afile') > astring # copy a file into a string
rio('afile').chomp > anarray # copy the chomped lines of afile into an array
rio('afile.gz').gzip.lines(0...100) > rio('bfile') # copy 100 lines from a gzipped file into another file
rio(?-) < rio('http://rubydoc.org/') # copy a web page to stdout
rio('bdir') < rio('adir') # copy an entire directory structure
rio('adir').dirs.files('README') > rio('bdir') # same thing, but only README files
rio(?-,'ps -a').nolines(0,/ps$/) > anarray # copy the output of th ps command into an array, skippying
# the header line and the ps command entry
</pre>
<h3>Renaming and Moving</h3>
<p>
<a href="../Rio.html">Rio</a> provides two methods for directly renaming
objects on the filesystem: <a href="../Rio.html#M000038">Rio#rename</a> and
<a href="../Rio.html#M000038">Rio#rename</a>!. Both of these use
File#rename. The difference between them is the returned <a
href="../Rio.html">Rio</a>. <a href="../Rio.html#M000038">Rio#rename</a>
leaves the path of the <a href="../Rio.html">Rio</a> unchanged, while <a
href="../Rio.html#M000038">Rio#rename</a>! changes the path of the <a
href="../Rio.html">Rio</a> to refer to the renamed path.
</p>
<pre>
ario = rio('a')
ario.rename('b') # file 'a' has been renamed to 'b' but 'ario' => rio('a')
ario.rename!('b') # file 'a' has been renamed to 'b' and 'ario' => rio('b')
</pre>
<p>
<a href="../Rio.html">Rio</a> also has a <tt>rename</tt> mode, which causes
the path manipulation methods <a
href="../Rio.html#M000093">Rio#dirname</a>=, <a
href="../Rio.html#M000095">Rio#filename</a>=, <a
href="../Rio.html#M000092">Rio#basename</a>= and <a
href="../Rio.html#M000094">Rio#extname</a>= to rename an object on the
filesystem when they are used to change a <a
href="../Rio.html">Rio</a>’s path. A <a href="../Rio.html">Rio</a> is
put in <tt>rename</tt> mode by calling <a
href="../Rio.html#M000038">Rio#rename</a> with no arguments.
</p>
<pre>
rio('adir/afile.txt').rename.filename = 'bfile.rb' # adir/afile.txt => adir/bfile.rb
rio('adir/afile.txt').rename.basename = 'bfile' # adir/afile.txt => adir/bfile.txt
rio('adir/afile.txt').rename.extname = '.rb' # adir/afile.txt => adir/afile.rb
rio('adir/afile.txt').rename.dirname = 'b/c' # adir/afile.txt => b/c/afile.txt
</pre>
<p>
When <tt>rename</tt> mode is set for a directory <a
href="../Rio.html">Rio</a>, it is automatically set in the Rios created
when iterating through that directory.
</p>
<pre>
rio('adir').rename.files('*.htm') do |frio|
frio.extname = '.html' #=> changes the rio and renames the file
end
</pre>
<h3>Deleting</h3>
<p>
The <a href="../Rio.html">Rio</a> methods for deleting filesystem objects
are <a href="../Rio.html#M000034">Rio#rm</a>, <a
href="../Rio.html#M000030">Rio#rmdir</a>, <a
href="../Rio.html#M000031">Rio#rmtree</a>, <a
href="../Rio.html#M000047">Rio#delete</a>, and <a
href="../Rio.html#M000047">Rio#delete</a>!. <tt>rm</tt>, <tt>rmdir</tt> and
<tt>rmtree</tt> are passed the like named methods in the FileUtils module.
<a href="../Rio.html#M000047">Rio#delete</a> calls <tt>rmdir</tt> for
directories and <tt>rm</tt> for anything else, while <a
href="../Rio.html#M000047">Rio#delete</a>! calls <a
href="../Rio.html#M000031">Rio#rmtree</a> for directories.
</p>
<ul>
<li>To delete something only if it is not a directory use <a
href="../Rio.html#M000034">Rio#rm</a>
</li>
<li>To delete an empty directory use <a
href="../Rio.html#M000030">Rio#rmdir</a>
</li>
<li>To delete an entire directory tree use <a
href="../Rio.html#M000031">Rio#rmtree</a>
</li>
<li>To delete anything except a populated directory use <a
href="../Rio.html#M000047">Rio#delete</a>
</li>
<li>To delete anything use <a href="../Rio.html#M000047">Rio#delete</a>!
</li>
</ul>
<p>
It is not an error to call any of the deleting methods on something that
does not exist. <a href="../Rio.html">Rio</a> provides Rio#exist? and <a
href="../Rio.html#M000036">Rio#symlink</a>? to check if something exists
(<tt>exist?</tt> returns false for symlinks to non-existant object even
though the symlink itself exists). The deleting methods’ purpose is
to make things not exist, so calling one of them on something that already
does not exist is considered a success.
</p>
<p>
To create a clean copy of a directory whether or not anything with that
name exists you might do this
</p>
<pre>
rio('adir').delete!.mkpath.chdir do
# do something in adir
end
</pre>
<p>
See also:
</p>
<ul>
<li><a href="SYNOPSIS.html">RIO::Doc::SYNOPSIS</a>
</li>
<li><a href="HOWTO.html">RIO::Doc::HOWTO</a>
</li>
<li><a href="../Rio.html">RIO::Rio</a>
</li>
</ul>
</div>
</div>
</div>
<!-- if includes -->
<div id="section">
<!-- if method_list -->
</div>
<div id="validator-badges">
<p><small>Copyright © 2005 Christopher Kleckner. <a href="http://www.gnu.org/licenses/gpl.html">All rights reserved</a>.</small></p>
</div>
</body>
</html>