<ppdoc>
<copyright>
    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/).
</copyright>
<class name="Dir" super="Object" type="class">
<p/>
  Objects of class <classname>Dir</classname> are directory streams representing
  directories in the
  underlying file system. They provide a variety of ways to list
  directories and their contents.  See also <classname>File</classname>, page
  305. 
<p/>
  The directory used in these examples contains the two regular files
  (<tt>config.h</tt> and <tt>main.rb</tt>), the parent directory (<tt>..</tt>), and
  the directory itself (<tt>.</tt>).
  <mixins>
    <mixin name="Enumerable">
   collect, detect, each_with_index, entries, find, find_all, grep,
   include?, map, max, member?, min, reject, select, sort, to_a</mixin>
  </mixins>
<p/>
  <methods type="class">
<p/>
        <method name="[ ]" ref="_ob_cb">
      <callseq>
        Dir[ <obj>aString</obj> ]
      <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns <obj>anArray</obj> of filenames found by 
      expanding the pattern given in <obj>aString</obj>.
      Note that this pattern is not a regexp (it's closer to a shell glob)
      and may contain the following metacharacters:      
<p/>
      <table>
<p/>
        <toprule/><tr>
  <td><tt>**</tt></td>
  <td>Matches subdirectories recursively</td>
</tr>
<tr>
  <td><tt>*</tt></td>
  <td>Matches zero or more characters</td>
</tr>
<tr>
  <td><tt>?</tt></td>
  <td>Matches any single character</td>
</tr>
<tr>
  <td><tt>[ <em>charSet</em> ]</tt></td>
  <td>Matches any character from the given 
           set of characters. A range of characters is written as 
           <em>charFrom</em><tt>-</tt><em>charTo</em>. The set may be negated
           with an initial uparrow (<tt>^</tt>).</td>
</tr>
<tr>
  <td><tt>{ <em>opt, opt, ...</em> }</tt></td>
  <td>Matches any one of the
        optional strings</td>
</tr>
<bottomrule/></table>
<p/>
<codefragment>
<fullcode><![CDATA[!-          Dir.chdir("testdir") 
        Dir["config.?"]
        Dir["*.[a-z][a-z]"]
        Dir["*.[^r]*"]
        Dir["*.{rb,h}"]
        Dir["*"]
]]></fullcode><rubycode>
<tr>
  <td><tt>Dir["config.?"]</tt></td>
  <td>&#187;</td>
  <td><tt>["config.h"]</tt></td>
</tr>
<tr>
  <td><tt>Dir["*.[a-z][a-z]"]</tt></td>
  <td>&#187;</td>
  <td><tt>["main.rb"]</tt></td>
</tr>
<tr>
  <td><tt>Dir["*.[^r]*"]</tt></td>
  <td>&#187;</td>
  <td><tt>["config.h"]</tt></td>
</tr>
<tr>
  <td><tt>Dir["*.{rb,h}"]</tt></td>
  <td>&#187;</td>
  <td><tt>["main.rb",<nbsp/>"config.h"]</tt></td>
</tr>
<tr>
  <td><tt>Dir["*"]</tt></td>
  <td>&#187;</td>
  <td><tt>["config.h",<nbsp/>"main.rb"]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="chdir" ref="chdir">
      <callseq>
        Dir.chdir( <opt> <obj>aString</obj></opt> )
        <returns>0</returns>
      </callseq>
      <desc>
<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 <tt>HOME</tt>, or <tt>LOGDIR</tt>.      
      Raises a <exception>SystemCallError</exception> (probably <classname>Errno::ENOENT</classname>)
      if the target directory does not exist.
<p/>
<codefragment>
<fullcode><![CDATA[        Dir.chdir("/var/spool/mail")
        Dir.pwd
]]></fullcode><rubycode>
<tr>
  <td><tt>Dir.chdir("/var/spool/mail")</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>Dir.pwd</tt></td>
  <td>&#187;</td>
  <td><tt>"/var/spool/mail"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="chroot" ref="chroot">
      <callseq>
        Dir.chroot( <obj>aString</obj> )
        <returns>0</returns>
      </callseq>
      <desc>
<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
       <tt>chroot(2)</tt> for more information.
<p/>
      <codefragment>
        <table>
<tr>
  <td><tt>Dir.chdir("/production/secure/root")</tt></td>
  <td></td>
</tr>
<tr>
  <td><tt>Dir.chroot("/production/secure/root")</tt></td>
  <td> &#187;<tt>0</tt></td>
</tr>
<tr>
  <td><tt>Dir.pwd</tt></td>
  <td> &#187;<tt>"/"</tt></td>
</tr>
</table>
<p/>
      </codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="delete" ref="delete">
      <callseq>
        Dir.delete( <obj>aString</obj> )
        <returns>0</returns>
      </callseq>
      <desc>
<p/>
            Deletes the named directory. Raises a subclass of
      <exception>SystemCallError</exception> if the directory isn't empty.
<p/>
      </desc>
    </method>
<p/>
        <method name="entries" ref="entries">
      <callseq>
        Dir.entries( <obj>aString</obj> )
        <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns an array containing all of the filenames in the given
      directory. Will raise a <exception>SystemCallError</exception> if the named directory
      doesn't exist.
<p/>
<codefragment>
<fullcode><![CDATA[        Dir.entries("testdir")
]]></fullcode><rubycode>
<tr>
  <td><tt>Dir.entries("testdir")</tt></td>
  <td>&#187;</td>
  <td><tt>[".",<nbsp/>"..",<nbsp/>"config.h",<nbsp/>"main.rb"]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="foreach" ref="foreach">
      <callseq>
        Dir.foreach( <obj>aString</obj> )
        <block>{| filename | <blockbody>block</blockbody> }</block>
<p/>
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<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/>
<codefragment>
<alltt><fullcode><![CDATA[        Dir.foreach("testdir") {|x| puts("Got " + x) }
]]></fullcode>
Dir.foreach("testdir")<nbsp/>{|x|<nbsp/>puts("Got<nbsp/>"<nbsp/>+<nbsp/>x)<nbsp/>}
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Got<nbsp/>.
Got<nbsp/>..
Got<nbsp/>config.h
Got<nbsp/>main.rb
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="getwd" ref="getwd">
      <callseq>
        Dir.getwd
        <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the path to the current working directory of this
      process as a string.            
<p/>
<codefragment>
<fullcode><![CDATA[        Dir.chdir("/tmp")
        Dir.getwd
]]></fullcode><rubycode>
<tr>
  <td><tt>Dir.chdir("/tmp")</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>Dir.getwd</tt></td>
  <td>&#187;</td>
  <td><tt>"/tmp"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="glob" ref="glob">
      <callseq>
        Dir.glob( <obj>aString</obj> )
      <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <ccm><file>dir</file><front>Dir</front><back>[]</back><mref>_ob_cb</mref></ccm>.
<p/>
      </desc>
    </method>
<p/>
        <method name="mkdir" ref="mkdir">
      <callseq>
        Dir.mkdir( <obj>aString</obj> <opt>, <obj>anInteger</obj></opt> )
        <returns>0</returns>
      </callseq>
      <desc>
<p/>
            Makes a new directory named by <obj>aString</obj>, with
      permissions specified by the optional parameter
      <obj>anInteger</obj>. The
      permissions may be modified by the value of <ccm><file>file</file><front>File</front><back>umask</back><mref>umask</mref></ccm>,
      and are ignored on NT.
      Raises a <exception>SystemCallError</exception> if the directory cannot be created.
      See also the discussion of permissions on page 305.
<p/>
      </desc>
    </method>
<p/>
        <method name="new" ref="new">
      <callseq>
        Dir.new( <obj>aString</obj> ) <returns><obj>aDir</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a new directory object for the named directory.
<p/>
      </desc>
    </method>
<p/>
        <method name="open" ref="open">
      <callseq>
                  Dir.open( <obj>aString</obj> ) <returns><obj>aDir</obj></returns><br/>Dir.open( <obj>aString</obj> ) <block>{| aDir | <blockbody>block</blockbody> }</block>
 <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      With no block, <meth>open</meth> is a synonym  for <ccm><file>dir</file><front>Dir</front><back>new</back><mref>new</mref></ccm>.
      If a block is present, it is passed <obj>aDir</obj> as a parameter. The
      directory is closed at the end of the block, and <ccm><file>dir</file><front>Dir</front><back>open</back><mref>open</mref></ccm>
      returns <tt>nil</tt>.
<p/>
      </desc>
    </method>
<p/>
        <method name="pwd" ref="pwd">
      <callseq>
        Dir.pwd <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <ccm><file>dir</file><front>Dir</front><back>getwd</back><mref>getwd</mref></ccm>.
<p/>
      </desc>
    </method>
<p/>
        <method name="rmdir" ref="rmdir">
      <callseq>
        Dir.rmdir( <obj>aString</obj> )
        <returns><const>true</const></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <ccm><file>dir</file><front>Dir</front><back>delete</back><mref>delete</mref></ccm>.
<p/>
      </desc>
    </method>
<p/>
        <method name="unlink" ref="unlink">
      <callseq>
        Dir.unlink( <obj>aString</obj> )
        <returns><const>true</const></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <ccm><file>dir</file><front>Dir</front><back>delete</back><mref>delete</mref></ccm>.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
  <methods type="instance">
<p/>
        <method name="close" ref="close">
      <callseq>
        <em>dir</em>.close
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Closes the directory stream. 
      Any further attempts to access <em>dir</em> will raise an
      <exception>IOError</exception>.
<p/>
<codefragment>
<fullcode><![CDATA[        d = Dir.new("testdir")
        d.close
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>d<nbsp/>=<nbsp/>Dir.new("testdir")</tt></td>
</tr>
<tr>
  <td><tt>d.close</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="each" ref="each">
      <callseq>
        <em>dir</em>.each <block>{|  | <blockbody>block</blockbody> }</block>
<p/>
        <returns><em>dir</em></returns>
      </callseq>
      <desc>
<p/>
      Calls the block once for each entry in this directory,
      passing the filename of each entry as a parameter to the block.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        d = Dir.new("testdir")
        d.each  {|x| puts ("Got " + x) }
]]></fullcode>
d<nbsp/>=<nbsp/>Dir.new("testdir")
d.each<nbsp/><nbsp/>{|x|<nbsp/>puts<nbsp/>("Got<nbsp/>"<nbsp/>+<nbsp/>x)<nbsp/>}
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Got<nbsp/>.
Got<nbsp/>..
Got<nbsp/>config.h
Got<nbsp/>main.rb
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="read" ref="read">
      <callseq>
        <em>dir</em>.read
        <returns><obj>aString</obj> or <tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Reads the next entry from <em>dir</em> and returns it as a 
      string.  Returns <tt>nil</tt> at the end of the stream.
<p/>
<codefragment>
<fullcode><![CDATA[        d = Dir.new("testdir")
        d.read
        d.read
        d.read
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>d<nbsp/>=<nbsp/>Dir.new("testdir")</tt></td>
</tr>
<tr>
  <td><tt>d.read</tt></td>
  <td>&#187;</td>
  <td><tt>"."</tt></td>
</tr>
<tr>
  <td><tt>d.read</tt></td>
  <td>&#187;</td>
  <td><tt>".."</tt></td>
</tr>
<tr>
  <td><tt>d.read</tt></td>
  <td>&#187;</td>
  <td><tt>"config.h"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="rewind" ref="rewind">
      <callseq>
        <em>dir</em>.rewind
        <returns><em>dir</em></returns>
      </callseq>
      <desc>
<p/>
      Repositions <em>dir</em> to the first entry.
<p/>
<codefragment>
<fullcode><![CDATA[        d = Dir.new("testdir")
        d.read
        d.rewind
        d.read
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>d<nbsp/>=<nbsp/>Dir.new("testdir")</tt></td>
</tr>
<tr>
  <td><tt>d.read</tt></td>
  <td>&#187;</td>
  <td><tt>"."</tt></td>
</tr>
<tr>
  <td><tt>d.rewind</tt></td>
  <td>&#187;</td>
  <td><tt>#&lt;Dir:0x4018d784&gt;</tt></td>
</tr>
<tr>
  <td><tt>d.read</tt></td>
  <td>&#187;</td>
  <td><tt>"."</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="seek" ref="seek">
      <callseq>
        <em>dir</em>.seek( <obj>anInteger</obj> )
        <returns><em>dir</em></returns>
      </callseq>
      <desc>
<p/>
      Seeks to a particular location in <em>dir</em>.
      <obj>anInteger</obj> must be a value returned by
      <cim><file>dir</file><front>Dir</front><back>tell</back><mref>tell</mref></cim>.
<p/>
<codefragment>
<fullcode><![CDATA[        d = Dir.new("testdir")
        d.read
        i = d.tell
        d.read
        d.seek(i)
        d.read
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>d<nbsp/>=<nbsp/>Dir.new("testdir")</tt></td>
</tr>
<tr>
  <td><tt>d.read</tt></td>
  <td>&#187;</td>
  <td><tt>"."</tt></td>
</tr>
<tr>
<td colspan="3"><tt>i<nbsp/>=<nbsp/>d.tell</tt></td>
</tr>
<tr>
  <td><tt>d.read</tt></td>
  <td>&#187;</td>
  <td><tt>".."</tt></td>
</tr>
<tr>
  <td><tt>d.seek(i)</tt></td>
  <td>&#187;</td>
  <td><tt>#&lt;Dir:0x4018d5b8&gt;</tt></td>
</tr>
<tr>
  <td><tt>d.read</tt></td>
  <td>&#187;</td>
  <td><tt>".."</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="tell" ref="tell">
      <callseq>
        <em>dir</em>.tell
        <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the current position in <em>dir</em>. See also <cim><file>dir</file><front>Dir</front><back>seek</back><mref>seek</mref></cim>.
<p/>
<codefragment>
<fullcode><![CDATA[        d = Dir.new("testdir")
        d.tell
        d.read
        d.tell
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>d<nbsp/>=<nbsp/>Dir.new("testdir")</tt></td>
</tr>
<tr>
  <td><tt>d.tell</tt></td>
  <td>&#187;</td>
  <td><tt>0</tt></td>
</tr>
<tr>
  <td><tt>d.read</tt></td>
  <td>&#187;</td>
  <td><tt>"."</tt></td>
</tr>
<tr>
  <td><tt>d.tell</tt></td>
  <td>&#187;</td>
  <td><tt>12</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
</ppdoc>