File: ref_c_dir.html

package info (click to toggle)
rubybook 0.2.1-1
links: PTS
area: non-free
in suites: etch, etch-m68k, lenny, squeeze, wheezy
size: 4,248 kB
ctags: 1,042
sloc: xml: 60,486; makefile: 25
file content (510 lines) | stat: -rw-r--r-- 20,432 bytes
parent folder | download | duplicates (3)
<html><title>Programming Ruby: The Pragmatic Programmer's Guide</title><head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><STYLE TYPE="text/css"><!--
       BODY    { margin-left: 1in;
                 width: 6in;
                 font-family: helvetica, arial, sans-serif;
               }
       H1      { color: #000080;
                 font-family: helvetica, arial, sans-serif;
                 font-size: 22pt;
                 margin-left: 0in
               }
       H2      { color: #000080;  font: bold x-large helvetica, sans-serif;
                 margin-left: 0in }
       H3      { color: #000080;  font: bold   large helvetica, sans-serif; }
       H4      { color: #000080;  font: italic large helvetica, sans-serif; }
       .ruby   { background: #fff0f0 }
       .header { color: white }
       .subheader { color: #ffdddd }
       .sidebar   { width: 6in }
       span.sans { font-family: helvetica, arial, sans-serif }
       -->
   </STYLE><table bgcolor="#a03030" cellpadding="3" border="0" cellspacing="0"><tr><td colspan="3"><table bgcolor="#902020" cellpadding="20"><tr><td><h1 class="header">Programming Ruby</h1><h3 class="subheader">The Pragmatic Programmer's Guide</h3></td></tr></table></td></tr><tr><td width="33%" align="left"><a class="subheader" href="ref_c_continuation.html">Previous &lt;</a></td><td width="33%" align="center" valign="middle"><a class="subheader" href="builtins.html">Contents ^</a><br></td><td width="33%" align="right"><a class="subheader" href="ref_c_exception.html">Next ></a><br></td></tr></table></head><body bgcolor="white">
<!--
    Copyright (c) 2001 by Addison Wesley Longman.  This
    material may be distributed only subject to the terms and
    conditions set forth in the Open Publication License, v1.0 or
    later (the latest version is presently available at
    http://www.opencontent.org/openpub/).
-->
<table><tr><td height="20"><img src="dot.gif" width="1" height="20"></td></tr></table><table border="0" width="100%" bgcolor="660066" cellpadding="10"><tr><td valign="center"><font color="white" size="7">class Dir</font></td><td><table border="0"><tr><td><font color="white">
                Parent:
              </font></td><td><font color="white">Object</font></td></tr><tr><td><font color="white">
                Version:
              </font></td><td><font color="white">
               1.6
              </font></td></tr></table></td></tr></table><p></p><H3>Index:</H3><a href="#_ob_cb">[ ]</a> <a href="#chdir">chdir</a> <a href="#chroot">chroot</a> <a href="#delete">delete</a> <a href="#entries">entries</a> <a href="#foreach">foreach</a> <a href="#getwd">getwd</a> <a href="#glob">glob</a> <a href="#mkdir">mkdir</a> <a href="#new">new</a> <a href="#open">open</a> <a href="#pwd">pwd</a> <a href="#rmdir">rmdir</a> <a href="#unlink">unlink</a> <a href="#close"><i>close</i></a> <a href="#each"><i>each</i></a> <a href="#read"><i>read</i></a> <a href="#rewind"><i>rewind</i></a> <a href="#seek"><i>seek</i></a> <a href="#tell"><i>tell</i></a> <p></p><hr>
<P></P>
  Objects of class <code>Dir</code> are directory streams representing
  directories in the
  underlying file system. They provide a variety of ways to list
  directories and their contents.  See also <code>File</code>, page
  305. 
<P></P>
  The directory used in these examples contains the two regular files
  (<code>config.h</code> and <code>main.rb</code>), the parent directory (<code>..</code>), and
  the directory itself (<code>.</code>).
  <table border="0" width="100%" cellpadding="10"><tr><td valign="center" colspan="2" bgcolor="990066"><font color="white" size="6">
         mixins
       </font></td></tr>
    <tr><td>Enumerable:
    </td><td>
   collect, detect, each_with_index, entries, find, find_all, grep,
   include?, map, max, member?, min, reject, select, sort, to_a</td></tr>
  </table>
<P></P>
  <table border="0" width="100%" cellpadding="10"><tr><td valign="center" colspan="2" bgcolor="990066"><font color="white" size="6">class methods
       </font></td></tr><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="_ob_cb"><b>[ ]</b></a></font></td><td bgcolor="#ffaaaa">
        Dir[ <i>aString</i> ]
      -> <i>anArray</i>
      </td></tr><td></td><td>
<P></P>
      Returns <i>anArray</i> of filenames found by 
      expanding the pattern given in <i>aString</i>.
      Note that this pattern is not a regexp (it's closer to a shell glob)
      and may contain the following metacharacters:      
<P></P>
      <table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3">
<P></P>
        <tr><td colspan="9" bgcolor="#ff9999" height="3"><img src="dot.gif" width="1" height="1"></td></tr><tr>
  <td valign="top"><code>**</code></td>
  <td valign="top">Matches subdirectories recursively</td>
</tr>
<tr>
  <td valign="top"><code>*</code></td>
  <td valign="top">Matches zero or more characters</td>
</tr>
<tr>
  <td valign="top"><code>?</code></td>
  <td valign="top">Matches any single character</td>
</tr>
<tr>
  <td valign="top"><code>[ <em>charSet</em> ]</code></td>
  <td valign="top">Matches any character from the given 
           set of characters. A range of characters is written as 
           <em>charFrom</em><code>-</code><em>charTo</em>. The set may be negated
           with an initial uparrow (<code>^</code>).</td>
</tr>
<tr>
  <td valign="top"><code>{ <em>opt, opt, ...</em> }</code></td>
  <td valign="top">Matches any one of the
        optional strings</td>
</tr>
<tr><td colspan="9" bgcolor="#ff9999" height="2"><img src="dot.gif" width="1" height="1"></td></tr></table>
<P></P>

<table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3" width="500">
<tr>
  <td valign="top"><code>Dir["config.?"]</code></td>
  <td valign="top"></td>
  <td valign="top"><code>["config.h"]</code></td>
</tr>
<tr>
  <td valign="top"><code>Dir["*.[a-z][a-z]"]</code></td>
  <td valign="top"></td>
  <td valign="top"><code>["main.rb"]</code></td>
</tr>
<tr>
  <td valign="top"><code>Dir["*.[^r]*"]</code></td>
  <td valign="top"></td>
  <td valign="top"><code>["config.h"]</code></td>
</tr>
<tr>
  <td valign="top"><code>Dir["*.{rb,h}"]</code></td>
  <td valign="top"></td>
  <td valign="top"><code>["main.rb",&nbsp;"config.h"]</code></td>
</tr>
<tr>
  <td valign="top"><code>Dir["*"]</code></td>
  <td valign="top"></td>
  <td valign="top"><code>["config.h",&nbsp;"main.rb"]</code></td>
</tr>
</table>
<P></P>

<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="chdir"><b>chdir</b></a></font></td><td bgcolor="#ffaaaa">
        Dir.chdir( <i>[</i> <i>aString</i><i>]</i> )
        -> 0
      </td></tr><td></td><td>
<P></P>
            Changes the current working directory of the process to the given
      string.
      When called without an argument, changes the directory to the value
      of the environment variable <code>HOME</code>, or <code>LOGDIR</code>.      
      Raises a <code>SystemCallError</code> (probably <code>Errno::ENOENT</code>)
      if the target directory does not exist.
<P></P>

<table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3" width="500">
<tr>
  <td valign="top"><code>Dir.chdir("/var/spool/mail")</code></td>
  <td valign="top"></td>
  <td valign="top"><code>0</code></td>
</tr>
<tr>
  <td valign="top"><code>Dir.pwd</code></td>
  <td valign="top"></td>
  <td valign="top"><code>"/var/spool/mail"</code></td>
</tr>
</table>
<P></P>

<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="chroot"><b>chroot</b></a></font></td><td bgcolor="#ffaaaa">
        Dir.chroot( <i>aString</i> )
        -> 0
      </td></tr><td></td><td>
<P></P>
             Changes this process's idea of the file system root.  
       Only a privileged process may make this call.
       Not available on all platforms.  On Unix systems, see
       <code>chroot(2)</code> for more information.
<P></P>
      
        <table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3">
<tr>
  <td valign="top"><code>Dir.chdir("/production/secure/root")</code></td>
  <td valign="top"></td>
</tr>
<tr>
  <td valign="top"><code>Dir.chroot("/production/secure/root")</code></td>
  <td valign="top"> <code>0</code></td>
</tr>
<tr>
  <td valign="top"><code>Dir.pwd</code></td>
  <td valign="top"> <code>"/"</code></td>
</tr>
</table>
<P></P>
      
<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="delete"><b>delete</b></a></font></td><td bgcolor="#ffaaaa">
        Dir.delete( <i>aString</i> )
        -> 0
      </td></tr><td></td><td>
<P></P>
            Deletes the named directory. Raises a subclass of
      <code>SystemCallError</code> if the directory isn't empty.
<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="entries"><b>entries</b></a></font></td><td bgcolor="#ffaaaa">
        Dir.entries( <i>aString</i> )
        -> <i>anArray</i>
      </td></tr><td></td><td>
<P></P>
      Returns an array containing all of the filenames in the given
      directory. Will raise a <code>SystemCallError</code> if the named directory
      doesn't exist.
<P></P>

<table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3" width="500">
<tr>
  <td valign="top"><code>Dir.entries("testdir")</code></td>
  <td valign="top"></td>
  <td valign="top"><code>[".",&nbsp;"..",&nbsp;"config.h",&nbsp;"main.rb"]</code></td>
</tr>
</table>
<P></P>

<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="foreach"><b>foreach</b></a></font></td><td bgcolor="#ffaaaa">
        Dir.foreach( <i>aString</i> )
        {| filename | block }
<P></P>
        -> <code>nil</code>
      </td></tr><td></td><td>
<P></P>
      Calls the block once for each entry in the named directory,
      passing the filename of each entry as a parameter to the block.
<P></P>

<table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3" width="400"><tr><td><pre>
Dir.foreach("testdir")&nbsp;{|x|&nbsp;puts("Got&nbsp;"&nbsp;+&nbsp;x)&nbsp;}
</pre></td></tr></table>

<em>produces:</em>
<table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3" width="400"><tr><td><pre>
Got&nbsp;.
Got&nbsp;..
Got&nbsp;config.h
Got&nbsp;main.rb
</pre></td></tr></table>

<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="getwd"><b>getwd</b></a></font></td><td bgcolor="#ffaaaa">
        Dir.getwd
        -> <i>aString</i>
      </td></tr><td></td><td>
<P></P>
      Returns the path to the current working directory of this
      process as a string.            
<P></P>

<table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3" width="500">
<tr>
  <td valign="top"><code>Dir.chdir("/tmp")</code></td>
  <td valign="top"></td>
  <td valign="top"><code>0</code></td>
</tr>
<tr>
  <td valign="top"><code>Dir.getwd</code></td>
  <td valign="top"></td>
  <td valign="top"><code>"/tmp"</code></td>
</tr>
</table>
<P></P>

<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="glob"><b>glob</b></a></font></td><td bgcolor="#ffaaaa">
        Dir.glob( <i>aString</i> )
      -> <i>anArray</i>
      </td></tr><td></td><td>
<P></P>
      Synonym for <a href="ref_c_dir.html#_ob_cb"><code>Dir::[]</code></a>.
<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="mkdir"><b>mkdir</b></a></font></td><td bgcolor="#ffaaaa">
        Dir.mkdir( <i>aString</i> <i>[</i>, <i>anInteger</i><i>]</i> )
        -> 0
      </td></tr><td></td><td>
<P></P>
            Makes a new directory named by <i>aString</i>, with
      permissions specified by the optional parameter
      <i>anInteger</i>. The
      permissions may be modified by the value of <a href="ref_c_file.html#umask"><code>File::umask</code></a>,
      and are ignored on NT.
      Raises a <code>SystemCallError</code> if the directory cannot be created.
      See also the discussion of permissions on page 305.
<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="new"><b>new</b></a></font></td><td bgcolor="#ffaaaa">
        Dir.new( <i>aString</i> ) -> <i>aDir</i>
      </td></tr><td></td><td>
<P></P>
      Returns a new directory object for the named directory.
<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="open"><b>open</b></a></font></td><td bgcolor="#ffaaaa">
                  Dir.open( <i>aString</i> ) -> <i>aDir</i><br>Dir.open( <i>aString</i> ) {| aDir | block }
 -> <code>nil</code>
      </td></tr><td></td><td>
<P></P>
      With no block, <code>open</code> is a synonym  for <a href="ref_c_dir.html#new"><code>Dir::new</code></a>.
      If a block is present, it is passed <i>aDir</i> as a parameter. The
      directory is closed at the end of the block, and <a href="ref_c_dir.html#open"><code>Dir::open</code></a>
      returns <code>nil</code>.
<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="pwd"><b>pwd</b></a></font></td><td bgcolor="#ffaaaa">
        Dir.pwd -> <i>aString</i>
      </td></tr><td></td><td>
<P></P>
      Synonym for <a href="ref_c_dir.html#getwd"><code>Dir::getwd</code></a>.
<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="rmdir"><b>rmdir</b></a></font></td><td bgcolor="#ffaaaa">
        Dir.rmdir( <i>aString</i> )
        -> <code>true</code>
      </td></tr><td></td><td>
<P></P>
      Synonym for <a href="ref_c_dir.html#delete"><code>Dir::delete</code></a>.
<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="unlink"><b>unlink</b></a></font></td><td bgcolor="#ffaaaa">
        Dir.unlink( <i>aString</i> )
        -> <code>true</code>
      </td></tr><td></td><td>
<P></P>
      Synonym for <a href="ref_c_dir.html#delete"><code>Dir::delete</code></a>.
<P></P>
      </td></table>
<P></P>
  <table border="0" width="100%" cellpadding="10"><tr><td valign="center" colspan="2" bgcolor="990066"><font color="white" size="6">instance methods
       </font></td></tr><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="close"><b>close</b></a></font></td><td bgcolor="#ffaaaa">
        <em>dir</em>.close
        -> <code>nil</code>
      </td></tr><td></td><td>
<P></P>
      Closes the directory stream. 
      Any further attempts to access <em>dir</em> will raise an
      <code>IOError</code>.
<P></P>

<table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3" width="500">
<tr>
<td colspan="3" valign="top"><code>d&nbsp;=&nbsp;Dir.new("testdir")</code></td>
</tr>
<tr>
  <td valign="top"><code>d.close</code></td>
  <td valign="top"></td>
  <td valign="top"><code>nil</code></td>
</tr>
</table>
<P></P>

<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="each"><b>each</b></a></font></td><td bgcolor="#ffaaaa">
        <em>dir</em>.each {|  | block }
<P></P>
        -> <em>dir</em>
      </td></tr><td></td><td>
<P></P>
      Calls the block once for each entry in this directory,
      passing the filename of each entry as a parameter to the block.
<P></P>

<table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3" width="400"><tr><td><pre>
d&nbsp;=&nbsp;Dir.new("testdir")
d.each&nbsp;&nbsp;{|x|&nbsp;puts&nbsp;("Got&nbsp;"&nbsp;+&nbsp;x)&nbsp;}
</pre></td></tr></table>

<em>produces:</em>
<table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3" width="400"><tr><td><pre>
Got&nbsp;.
Got&nbsp;..
Got&nbsp;config.h
Got&nbsp;main.rb
</pre></td></tr></table>

<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="read"><b>read</b></a></font></td><td bgcolor="#ffaaaa">
        <em>dir</em>.read
        -> <i>aString</i> or <code>nil</code>
      </td></tr><td></td><td>
<P></P>
      Reads the next entry from <em>dir</em> and returns it as a 
      string.  Returns <code>nil</code> at the end of the stream.
<P></P>

<table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3" width="500">
<tr>
<td colspan="3" valign="top"><code>d&nbsp;=&nbsp;Dir.new("testdir")</code></td>
</tr>
<tr>
  <td valign="top"><code>d.read</code></td>
  <td valign="top"></td>
  <td valign="top"><code>"."</code></td>
</tr>
<tr>
  <td valign="top"><code>d.read</code></td>
  <td valign="top"></td>
  <td valign="top"><code>".."</code></td>
</tr>
<tr>
  <td valign="top"><code>d.read</code></td>
  <td valign="top"></td>
  <td valign="top"><code>"config.h"</code></td>
</tr>
</table>
<P></P>

<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="rewind"><b>rewind</b></a></font></td><td bgcolor="#ffaaaa">
        <em>dir</em>.rewind
        -> <em>dir</em>
      </td></tr><td></td><td>
<P></P>
      Repositions <em>dir</em> to the first entry.
<P></P>

<table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3" width="500">
<tr>
<td colspan="3" valign="top"><code>d&nbsp;=&nbsp;Dir.new("testdir")</code></td>
</tr>
<tr>
  <td valign="top"><code>d.read</code></td>
  <td valign="top"></td>
  <td valign="top"><code>"."</code></td>
</tr>
<tr>
  <td valign="top"><code>d.rewind</code></td>
  <td valign="top"></td>
  <td valign="top"><code>#&lt;Dir:0x4018d784></code></td>
</tr>
<tr>
  <td valign="top"><code>d.read</code></td>
  <td valign="top"></td>
  <td valign="top"><code>"."</code></td>
</tr>
</table>
<P></P>

<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="seek"><b>seek</b></a></font></td><td bgcolor="#ffaaaa">
        <em>dir</em>.seek( <i>anInteger</i> )
        -> <em>dir</em>
      </td></tr><td></td><td>
<P></P>
      Seeks to a particular location in <em>dir</em>.
      <i>anInteger</i> must be a value returned by
      <a href="ref_c_dir.html#tell"><code>Dir#tell</code></a>.
<P></P>

<table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3" width="500">
<tr>
<td colspan="3" valign="top"><code>d&nbsp;=&nbsp;Dir.new("testdir")</code></td>
</tr>
<tr>
  <td valign="top"><code>d.read</code></td>
  <td valign="top"></td>
  <td valign="top"><code>"."</code></td>
</tr>
<tr>
<td colspan="3" valign="top"><code>i&nbsp;=&nbsp;d.tell</code></td>
</tr>
<tr>
  <td valign="top"><code>d.read</code></td>
  <td valign="top"></td>
  <td valign="top"><code>".."</code></td>
</tr>
<tr>
  <td valign="top"><code>d.seek(i)</code></td>
  <td valign="top"></td>
  <td valign="top"><code>#&lt;Dir:0x4018d5b8></code></td>
</tr>
<tr>
  <td valign="top"><code>d.read</code></td>
  <td valign="top"></td>
  <td valign="top"><code>".."</code></td>
</tr>
</table>
<P></P>

<P></P>
      </td><tr><td valign="center" bgcolor="#ff9999"><font size="4"><a name="tell"><b>tell</b></a></font></td><td bgcolor="#ffaaaa">
        <em>dir</em>.tell
        -> <i>anInteger</i>
      </td></tr><td></td><td>
<P></P>
      Returns the current position in <em>dir</em>. See also <a href="ref_c_dir.html#seek"><code>Dir#seek</code></a>.
<P></P>

<table bgcolor="#fff0f0" cellspacing="0" border="0" cellpadding="3" width="500">
<tr>
<td colspan="3" valign="top"><code>d&nbsp;=&nbsp;Dir.new("testdir")</code></td>
</tr>
<tr>
  <td valign="top"><code>d.tell</code></td>
  <td valign="top"></td>
  <td valign="top"><code>0</code></td>
</tr>
<tr>
  <td valign="top"><code>d.read</code></td>
  <td valign="top"></td>
  <td valign="top"><code>"."</code></td>
</tr>
<tr>
  <td valign="top"><code>d.tell</code></td>
  <td valign="top"></td>
  <td valign="top"><code>12</code></td>
</tr>
</table>
<P></P>

<P></P>
      </td></table>
<P></P>

<p></p><hr><table bgcolor="#a03030" cellpadding="10" border="0" cellspacing="0"><tr><td width="33%" align="left"><a class="subheader" href="ref_c_continuation.html">Previous &lt;</a></td><td width="33%" align="center" valign="middle"><a class="subheader" href="builtins.html">Contents ^</a><br></td><td width="33%" align="right"><a class="subheader" href="ref_c_exception.html">Next ></a><br></td></tr></table><p></p><font size="-1">Extracted from the book "Programming Ruby -
     The Pragmatic Programmer's Guide"</font><br><font size="-3">
      Copyright
      &#169;
      2000 Addison Wesley Longman, Inc. Released under the terms of the
      <a href="http://www.opencontent.org/openpub/">Open Publication License</a> V1.0.
        <br>
      This reference is available for
        <a href="http://www.pragmaticprogrammer.com/ruby/downloads/book.html">download</a>.
   </font></body></html>