doc/rdoc/classes/RIO/Doc/INTRO.html in rio-0.3.1 vs doc/rdoc/classes/RIO/Doc/INTRO.html in rio-0.3.2
- old
+ new
@@ -117,11 +117,11 @@
<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)
+result of one of the path manipulation methods)
</li>
<li>Configuring a <a href="../Rio.html">Rio</a>
</li>
@@ -267,13 +267,13 @@
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.
+operation is specified, a <tt>stdio:</tt> <a href="../Rio.html">Rio</a>
+does not know whether it will connect to stdin or stdout until an I/O
+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)
@@ -312,18 +312,49 @@
</ul>
<pre>
astring = ""
rio(?","")
</pre>
-<h5>Creating a <a href="../Rio.html">Rio</a> that refers to a Tempfile object</h5>
+<h5>Creating a <a href="../Rio.html">Rio</a> that refers to a Temporary object</h5>
<p>
<tt>rio(??)</tt> (mnemonic: ’?’ you don’t know its name)
</p>
+<p>
+To create a temporary object that will become a file or a directory,
+depending on how you use it:
+</p>
<pre>
rio(??)
rio(??,basename='rio',tmpdir=Dir::tmpdir)
</pre>
+<p>
+To force it to become a file
+</p>
+<pre>
+ rio(??).file
+</pre>
+<p>
+or just write to it.
+</p>
+<p>
+To force it to become a directory:
+</p>
+<pre>
+ rio(??).dir
+</pre>
+<p>
+or
+</p>
+<pre>
+ rio(??).mkdir
+</pre>
+<p>
+or
+</p>
+<pre>
+ rio(??).chdir
+</pre>
<h5>Creating a <a href="../Rio.html">Rio</a> that refers to an arbitrary TCPSocket</h5>
<pre>
rio('tcp:',hostname,port)
</pre>
<p>
@@ -474,11 +505,11 @@
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
+<a href="../Rio.html#M000086">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>
@@ -486,22 +517,22 @@
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
+<a href="../Rio.html#M000087">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
+<a href="../Rio.html#M000113">Rio#route_to</a> and <a
+href="../Rio.html#M000112">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>
@@ -726,11 +757,11 @@
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
+directory entry, <a href="../Rio.html#M000038">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
@@ -769,11 +800,11 @@
</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
+href="../Rio.html#M000035">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
@@ -844,11 +875,11 @@
<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#M000017">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
@@ -877,11 +908,11 @@
</li>
</ul>
<h4>Grande operators</h4>
<p>
-The primary grande operator is <a href="../Rio.html#M000046">Rio#each</a>.
+The primary grande operator is <a href="../Rio.html#M000045">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
@@ -971,16 +1002,16 @@
# 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
+objects on the filesystem: <a href="../Rio.html#M000037">Rio#rename</a> and
+<a href="../Rio.html#M000037">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>
+href="../Rio.html">Rio</a>. <a href="../Rio.html#M000037">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#M000037">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')
@@ -994,11 +1025,11 @@
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.
+href="../Rio.html#M000037">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
@@ -1015,60 +1046,248 @@
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
+are <a href="../Rio.html#M000033">Rio#rm</a>, <a
+href="../Rio.html#M000029">Rio#rmdir</a>, <a
+href="../Rio.html#M000030">Rio#rmtree</a>, <a
+href="../Rio.html#M000046">Rio#delete</a>, and <a
+href="../Rio.html#M000046">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
+<a href="../Rio.html#M000046">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.
+href="../Rio.html#M000046">Rio#delete</a>! calls <a
+href="../Rio.html#M000030">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>
+href="../Rio.html#M000033">Rio#rm</a>
</li>
<li>To delete an empty directory use <a
-href="../Rio.html#M000030">Rio#rmdir</a>
+href="../Rio.html#M000029">Rio#rmdir</a>
</li>
<li>To delete an entire directory tree use <a
-href="../Rio.html#M000031">Rio#rmtree</a>
+href="../Rio.html#M000030">Rio#rmtree</a>
</li>
<li>To delete anything except a populated directory use <a
-href="../Rio.html#M000047">Rio#delete</a>
+href="../Rio.html#M000046">Rio#delete</a>
</li>
-<li>To delete anything use <a href="../Rio.html#M000047">Rio#delete</a>!
+<li>To delete anything use <a href="../Rio.html#M000046">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
+href="../Rio.html#M000035">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
+name exists one might do this
</p>
<pre>
- rio('adir').delete!.mkpath.chdir do
- # do something in adir
- end
+ rio('adir').delete!.mkpath.chdir do
+ # do something in adir
+ end
</pre>
+<hr size="1"></hr><h2>Miscellany</h2>
+<h4>Using Symbolic Links</h4>
<p>
+To create a symbolic link (symlink) to the file-system entry refered to by
+a <a href="../Rio.html">Rio</a>, use <a
+href="../Rio.html#M000035">Rio#symlink</a>. <a
+href="../Rio.html#M000035">Rio#symlink</a> differs from File#symlink in
+that it calculates the path from the symlink location to the <a
+href="../Rio.html">Rio</a>’s position. So:
+</p>
+<pre>
+ File#symlink('adir/afile','adir/alink')
+</pre>
+<p>
+creates a symlink in the directory ‘adir’ named
+‘alink’ which references ‘adir/afile’. From the
+perspective of ‘alink’, ‘adir/afile’ does not
+exist. While:
+</p>
+<pre>
+ rio('adir/afile').symlink('adir/alink')
+</pre>
+<p>
+creates a symlink in the directory ‘adir’ named
+‘alink’ which references ‘afile’. This is the route
+to ‘adir/afile’ from the perspective of
+‘adir/alink’.
+</p>
+<p>
+Note that the return value from <tt>symlink</tt> is the calling <a
+href="../Rio.html">Rio</a> and not a <a href="../Rio.html">Rio</a> refering
+to the symlink. This is done for consistency with the rest of <a
+href="../Rio.html">Rio</a>.
+</p>
+<p>
+<a href="../Rio.html#M000035">Rio#symlink</a>? can be used to test if a
+file-system object is a symlink. A <a href="../Rio.html">Rio</a> is
+extended with <a href="../Rio.html#M000036">Rio#readlink</a>, and <a
+href="../Rio.html#M000161">Rio#lstat</a> only if <a
+href="../Rio.html#M000035">Rio#symlink</a>? returns true. So for
+non-symlinks, these will raise a NoMethodError. These are both passed to
+their counterparts in File. <a href="../Rio.html#M000036">Rio#readlink</a>
+returns a <a href="../Rio.html">Rio</a> refering to the result of
+File#readlink.
+</p>
+<h4>Using A <a href="../Rio.html">Rio</a> as an IO (or File or Dir)</h4>
+<p>
+<a href="../Rio.html">Rio</a> supports so much of IO’s interface that
+one might be tempted to pass it to a method that expects an IO. While <a
+href="../Rio.html">Rio</a> is not and is not intended to be a stand in for
+IO, this can work. It requires knowledge of every IO method that will be
+called, under any circumstances.
+</p>
+<p>
+Even in cases where <a href="../Rio.html">Rio</a> supports the required IO
+interface, A <a href="../Rio.html">Rio</a> feature that seems to cause the
+most incompatibility, is its automatic closing of files. To turn off all of
+<a href="../Rio.html">Rio</a>’s automatic closing use
+Rio#noautoclose.
+</p>
+<p>
+For example:
+</p>
+<pre>
+ require 'yaml'
+ yrio = rio('ran.yaml').delete!.noautoclose
+ YAML.dump( ['badger', 'elephant', 'tiger'], yrio )
+ obj = YAML::load( yrio ) #=> ["badger", "tiger", "elephant"]
+</pre>
+<h4>Automatic Closing of Files</h4>
+<p>
+<a href="../Rio.html">Rio</a> closes files automatically in three
+instances.
+</p>
+<p>
+When reading from an IO it is closed when the end of file is reached. While
+this is a reasonable thing to do in many cases, sometimes this is not
+desired. To turn <a href="../Rio.html">Rio</a>’s automatic closing on
+end of file use <a href="../Rio.html#M000069">Rio#nocloseoneof</a> (it can
+be turned back on via <a href="../Rio.html#M000068">Rio#closeoneof</a>)
+</p>
+<pre>
+ ario = rio('afile').nocloseoneof
+ lines = ario[]
+ ario.closed? #=> false
+</pre>
+<p>
+Closing on end-of-file is necessary for many of <a
+href="../Rio.html">Rio</a>’s "one-liners", but has an
+implication that may be surprising at first. A <a
+href="../Rio.html">Rio</a> starts life as a path, not much more than a
+string. When one of its read methods is called it becomes an input stream.
+When the stream is closed, it becomes a path again. This means that when
+reading from a <a href="../Rio.html">Rio</a>, the end-of-file condition is
+seen only once before it becomes a path again, and will be reopened if
+another read operation is attempted.
+</p>
+<p>
+Another time a <a href="../Rio.html">Rio</a> will be closed atomatically is
+when writing to it with one of the copy operators (<tt><, <<,
+>, >></tt>). This behavior can be turned off with <a
+href="../Rio.html#M000072">Rio#nocloseoncopy</a>.
+</p>
+<p>
+To turn off both of thes types of automatic closing use Rio#noautoclose.
+</p>
+<p>
+The third instance when <a href="../Rio.html">Rio</a> will close a file
+automatically is when a file opened for one type of access receives a
+method which that access mode does not support. So, the code
+</p>
+<pre>
+ rio('afile').puts("Hello World").gets
+</pre>
+<p>
+will open the file for write access when the <tt>puts</tt> method is
+received. When <tt>gets</tt> is called the file is closed and reopened with
+read access.
+</p>
+<h4>Explicit Closing of Files</h4>
+<p>
+<a href="../Rio.html">Rio</a> can not determine when the client is finished
+writing to it, as it does using <tt>eof</tt> on read. It is the
+author’s understanding that Ruby does not support a mechanism to have
+code run when there are no more references to it — that finalizers
+are not necessarily run immediatly upon an object’s reference count
+reaching 0. If this understanding is incorrect, some of <a
+href="../Rio.html">Rio</a>’s extranious ways of closing a file may be
+rethought.
+</p>
+<p>
+That being said, <a href="../Rio.html">Rio</a> support several ways to
+explicitly close a file. <a href="../Rio.html#M000141">Rio#close</a> will
+close any open <a href="../Rio.html">Rio</a>. The output methods <a
+href="../Rio.html#M000132">Rio#puts</a>!, <a
+href="../Rio.html#M000131">Rio#putc</a>!, <a
+href="../Rio.html#M000129">Rio#printf</a>!, <a
+href="../Rio.html#M000126">Rio#print</a>!, and <a
+href="../Rio.html#M000135">Rio#write</a>! behave as if their counterparts
+without the exclamation point had been called and then call <a
+href="../Rio.html#M000141">Rio#close</a> or Rio#close_write if the
+underlying IO object is opened for duplex access.
+</p>
+<h4>Open mode selection</h4>
+<p>
+A <a href="../Rio.html">Rio</a> is typically not explicitly opened. It
+opens a file automatically when an input or output methed is called. For
+output methods <a href="../Rio.html">Rio</a> opens a file with mode
+‘w’, and otherwise opens a file with mode ‘r’. This
+behavior can be modified using the tersely named methods <a
+href="../Rio.html#M000062">Rio#a</a>, <a
+href="../Rio.html#M000062">Rio#a</a>!, <a
+href="../Rio.html#M000064">Rio#r</a>, <a
+href="../Rio.html#M000064">Rio#r</a>!, <a
+href="../Rio.html#M000066">Rio#w</a>, and <a
+href="../Rio.html#M000066">Rio#w</a>!, which cause the <a
+href="../Rio.html">Rio</a> to use modes
+‘a’,’a+’,’r’,’r+’,’w’,and
+‘w+’ respectively.
+</p>
+<p>
+One way to append a string to a file and close it in one line is
+</p>
+<pre>
+ rio('afile').a.puts!("Hello World")
+</pre>
+<p>
+Run a cmd that must be opened for read and write
+</p>
+<pre>
+ ans = rio(?-,'cat').w!.puts!("Hello Kitty").readlines
+</pre>
+<p>
+The automatic selection of mode can be bypassed entirely using <a
+href="../Rio.html#M000139">Rio#mode</a> and <a
+href="../Rio.html#M000007">Rio#open</a>.
+</p>
+<p>
+If a mode is specified using <tt>mode</tt>, the file will still be opened
+automatically, but the mode specified in the <tt>mode</tt> method will be
+used regardless of whether it makes sense.
+</p>
+<p>
+A <a href="../Rio.html">Rio</a> can also be opened explicitly using <a
+href="../Rio.html#M000007">Rio#open</a>. <tt>open</tt> takes one parameter,
+a mode. This also will override all of <a
+href="../Rio.html">Rio</a>’s automatic mode selection.
+</p>
+<hr size="1"></hr><p>
See also:
</p>
<ul>
<li><a href="SYNOPSIS.html">RIO::Doc::SYNOPSIS</a>
\ No newline at end of file