casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
DirectoryIterator.h
Go to the documentation of this file.
00001 //# DirectoryIterator.h: Traverse the contents of a directory
00002 //# Copyright (C) 1996
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id: DirectoryIterator.h 20551 2009-03-25 00:11:33Z Malte.Marquarding $
00027 
00028 #ifndef CASA_DIRECTORYITERATOR_H
00029 #define CASA_DIRECTORYITERATOR_H
00030 
00031 //# Includes
00032 #include <casa/aips.h>
00033 #include <casa/OS/File.h>
00034 #include <casa/OS/Directory.h>
00035 #include <casa/Utilities/Regex.h>
00036 
00037 #include <dirent.h>                          // needed for DIR
00038 
00039 
00040 namespace casa { //# NAMESPACE CASA - BEGIN
00041 
00042 // <summary>  
00043 // Traverse the contents of a directory
00044 // </summary>
00045 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
00046 // </reviewed>
00047 
00048 // <use visibility=export>
00049 
00050 // <prerequisite> 
00051 //    <li> Basic knowledge of the UNIX file system
00052 //    <li> <linkto class=Directory>Directory</linkto>
00053 //    <li> possibly <linkto class=Regex>Regex</linkto>
00054 // </prerequisite>
00055 
00056 // <synopsis>
00057 // DirectoryIterator allows to traverse a directory. In this way all
00058 // file names in a directory can be gotten. Files . and .. will
00059 // always be skipped.
00060 // <p>
00061 // By means of a regular expression it is possible to traverse the
00062 // directory selectively. That is, only the file names matching the regular
00063 // expression will be returned. Note that the regular expression is
00064 // a true regular expression (as defined by class <linkto class=Regex>
00065 // Regex</linkto> and not a file expression as used in shells.
00066 // Thus to get all .cc files, one has to specify ".*\.cc" and not "*.cc".
00067 // <p>
00068 // The <linkto class=File>File</linkto> class can be used to determine if
00069 // a file represents a symlink, directory or regular file.
00070 // </synopsis>
00071 
00072 // <example>
00073 // <srcblock>
00074 //    Directory dir("testdir");
00075 //    // Get all .cc files.
00076 //    // Note that Regex is a true regular expression and not a
00077 //    // simplified file expression (like *.cc) as used in shells.
00078 //    DirectoryIterator dirIter(dir, ".*.\cc");
00079 //    while (!dirIter.pastEnd()){
00080 //        cout << dirIter.name() << endl;
00081 //        dirIter++;
00082 //    }
00083 // </srcblock>
00084 // </example>
00085 
00086 // <motivation> 
00087 // With this class it is easy to iterate through a directory.
00088 // </motivation>
00089 
00090 // <todo asof=$DATE$>
00091 // <li> Allow file expressions like *.cc.
00092 //      However, it's probably better to make that part of Regex.
00093 // </todo>
00094 
00095 
00096 class DirectoryIterator
00097 {
00098 public:
00099 
00100     // Construct the iterator for the working directory.
00101     // All entries (except . and ..) will be traversed.
00102     // It positions the iterator on the first entry.
00103     DirectoryIterator();
00104 
00105     // Construct the iterator for the given directory.
00106     // All entries (except . and ..) will be traversed.
00107     // It positions the iterator on the first entry.
00108     DirectoryIterator (const Directory& dir);
00109 
00110     // Construct the iterator for the given directory.
00111     // All entries matching the regular expression will be traversed.
00112     // It positions the iterator on the first entry.
00113     DirectoryIterator (const Directory& dir, const Regex& regExpression);
00114 
00115     // Copy constructor (copy semantics).
00116     // The iterator will be positioned at the beginning.
00117     DirectoryIterator (const DirectoryIterator& that);
00118 
00119     // Assignment (copy semantics).
00120     // The iterator will be positioned at the beginning.
00121     DirectoryIterator& operator= (const DirectoryIterator& that);
00122 
00123     ~DirectoryIterator();
00124 
00125     // Position on the next matching entry in the directory.
00126     // <br>An exception is thrown if the iterator is already past the end.
00127     // <group>
00128     void operator++();
00129     void operator++(int);
00130     // </group>
00131 
00132     // Returns the file name at the current position.
00133     // <br>An exception is thrown if the iterator is already past the end.
00134     String name() const;
00135 
00136     // Returns a File object for the file at the current position.
00137     // Note that this adds the path of the directory to get the
00138     // correct path for the file.
00139     // <br>An exception is thrown if the iterator is already past the end.
00140     File file() const;
00141 
00142     // Reposition the directory stream on the first entry.
00143     void reset();
00144 
00145     // Checks if the iterator is past the end.
00146     Bool pastEnd() const;
00147 
00148 private:
00149     // Initialize the iterator.
00150     void init();
00151 
00152     // This variable is used for seeking in the directory.
00153     // The directory is opened and closed once during the lifetime 
00154     // of the class.
00155     DIR *itsDirectoryDescriptor;
00156 
00157     // This structure is used for information of the directory.
00158     dirent *itsDirectoryEntry;
00159 
00160     // Boolean to check if the directory stream has past the end
00161     Bool itsEnd;
00162 
00163     // class directory 
00164     Directory itsDirectory;
00165     
00166     // Regular expression if given, with this variable it is possible 
00167     // to compare files with regular expression.
00168     Regex itsExpression;
00169 
00170     // Cray XT3 does not support readdir on compute nodes.
00171     // Use scandir instead.
00172     dirent** itsNameList;
00173     int      itsNrNames;
00174     int      itsNameInx;
00175 };
00176 
00177 
00178 
00179 } //# NAMESPACE CASA - END
00180 
00181 #endif