casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Directory.h
Go to the documentation of this file.
00001 //# Directory.h: Get information about, and manipulate directories
00002 //# Copyright (C) 1996,1997,1999
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: Directory.h 20750 2009-10-01 06:32:18Z Malte.Marquarding $
00027 
00028 #ifndef CASA_DIRECTORY_H
00029 #define CASA_DIRECTORY_H
00030 
00031 //# Includes
00032 #include <casa/aips.h>
00033 #include <casa/OS/Path.h>
00034 #include <casa/OS/File.h>
00035    
00036 namespace casa { //# NAMESPACE CASA - BEGIN
00037 
00038 template<class T> class Vector;
00039 class Regex;
00040 class String;
00041 
00042 // <summary>  
00043 // Get information about, and manipulate directories
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=File>File</linkto>
00053 // </prerequisite>
00054 
00055 // <synopsis> 
00056 // Directory provides functions to manipulate and to get information about 
00057 // directories. The functions for getting information (like ownership, dates)
00058 // about directories are inherited from the <linkto class=File>File</linkto>
00059 // class.
00060 // Directory itself provides functions to create, copy, move, or remove
00061 // a directory. The file name can be a symbolic link resolving
00062 // (eventually) to a directory.
00063 // <p>
00064 // A separate class <linkto class=DirectoryIterator>DirectoryIterator</linkto>
00065 // allows one to traverse a directory to get the file names in it.
00066 // </synopsis>
00067 
00068 // <example>
00069 // <srcblock>
00070 //    Directory dir("someDir");
00071 //    // Create directory someDir in the working directory.
00072 //    dir.create();
00073 //    cout << dir.nEntries();        // #entries
00074 //    // Assign to another directory.
00075 //    dir = Directory("otherDir");
00076 //    // Remove the directory and its contents.
00077 //    dir.removeRecursive();
00078 // </srcblock>
00079 // </example>
00080 
00081 // <motivation> 
00082 // Provide functions for manipulating and getting information 
00083 // about directories.
00084 // </motivation>
00085 
00086 
00087 class Directory: public File
00088 {
00089 public:
00090 
00091     // Sets the path on the current working directory
00092     Directory();
00093 
00094     // Create a directory object for a file with the given path name.
00095     // An exception is thrown if the directory is illegal, i.e. if it does
00096     // not exist as a directory or symbolic link or if cannot be created.
00097     // Note that the directory is not created if it does not exist yet.
00098     // This can be done using the function create.
00099     // <br>
00100     // When the given path name is a symbolic link, the symbolic link
00101     // is resolved (recursively) and the resulting directory name is used
00102     // instead.
00103     // <group>
00104     Directory (const Path& name);
00105     Directory (const String& name);
00106     Directory (const File& name);
00107     // </group>
00108 
00109     // Copy constructor (copy semantics).
00110     Directory (const Directory& that);
00111 
00112     ~Directory();
00113 
00114     // Assignment (copy semantics).
00115     Directory& operator= (const Directory& that);
00116 
00117     // Check if directory is empty.
00118     // If the directory does not exist, an exception will be thrown.
00119     Bool isEmpty() const;
00120 
00121     // Return the number of entries in the directory (not counting . and ..).
00122     // If the directory does not exist, an exception will be thrown.
00123     uInt nEntries() const;
00124 
00125     // Get the amount of free space (in bytes) on the file system this
00126     // directory is on. When the directory path is a symbolic link, that
00127     // link is resolved first.
00128     // <group>
00129     Double freeSpace() const;
00130     uInt freeSpaceInMB() const;
00131     // </group>
00132 
00133     // Create the directory.
00134     // <br>If the directory exists and overwrite=True, it will be removed
00135     // (recursively). Otherwise an exception is thrown.
00136     void create (Bool overwrite = True);
00137 
00138     // Remove a directory.
00139     // An exception is thrown if the directory is not empty.
00140     // If a symbolic link is given, the link chain pointing to the directory
00141     // will also be removed.
00142     void remove();
00143 
00144     // Remove all files in the directory except subdirectories.
00145     // The directory itself is not removed.
00146     void removeFiles();
00147 
00148     // Remove the directory and its contents (recursively in all
00149     // subdirectories).
00150     // If <src>keepDir==True</src>, the directory itself is kept
00151     //(to keep properties like placement on Lustre).
00152     void removeRecursive (Bool keepDir = False);
00153 
00154     // Copy the directory and its contents (recursively) to the target
00155     // path using the system command cp -r.
00156     // If the target already exists (as a file, directory or symlink),
00157     // and overwrite=True, it will first be removed.
00158     // The target directory is created and the data in the source
00159     // directory is copied to the new directory.
00160     // <br>An exception is thrown if:
00161     // <br>- the target directory is not writable
00162     // <br>- or the target already exists and overwrite!=True
00163     // <note role=caution>
00164     // 1. The behavior of this copy function is different from cp when the
00165     // target directory already exists. Cp copies the source to a
00166     // subdirectory of the target, while copy recreates the target.
00167     // <br>2. When a readonly file is copied, <src>cp</src> the resulting
00168     // file is also readonly. Therefore <src>chmod</src> is used to
00169     // set user write permission after the copy.
00170     // The flag <src>setUserWritePermission</src> can be set to False
00171     // when that should not be done.
00172     // </note>
00173     // <group>
00174     void copy (const Path& target, Bool overwrite = True,
00175                Bool setUserWritePermission = True) const;
00176     void copy (const String& target, Bool overwrite = True,
00177                Bool setUserWritePermission = True) const;
00178     // </group>
00179 
00180     // Copy a directory recursively in a manual way.
00181     // This is used in a copy using the system command is not possible
00182     // (like on the Cray XT3).
00183     void copyRecursive (const String& target) const;
00184 
00185     // Move the directory to the target path using the system command mv.
00186     // If the target already exists (as a file, directory or symlink),
00187     // and overwrite=True, it will first be removed.
00188     // The source directory is moved (thus renamed) to the target.
00189     // <br>An exception is thrown if:
00190     // <br>- the target directory is not writable
00191     // <br>- or the target already exists and overwrite!=True
00192     // <note role=caution>
00193     // The behavior of this move function is different from mv when the
00194     // target directory already exists. Mv moves the source to a
00195     // subdirectory of the target, while move recreates the target.
00196     // </note>
00197     // <group>
00198     void move (const Path& target, Bool overwrite = True);
00199     void move (const String& target, Bool overwrite = True);
00200     // </group>
00201 
00202     // Find all files which whose names match <src>regex</src>.  You
00203     // can do this recursively (default) or not.  Note that the 
00204     // matching is a regular expression match, not a shell file-expansion 
00205     // match. However, a shell file pattern can be converted to a regexp
00206     // using the function <linkto class=Regex>Regex::fromPattern</linkto>.
00207     // <src>Regex::fromString</src> allows one to convert a file name
00208     // to a regexp and to use this function for eact file name matching.
00209     // <br>To match the semantics of the unix <src>find</src> command,
00210     // symbolic links are not followed by default, but this behavior
00211     // can be over-ridden. 
00212     Vector<String> find (const Regex& regexp, Bool followSymLinks=False,
00213                          Bool recursive=True) const;
00214 
00215 
00216     // For each element of <src>files</src>, find all file names matching
00217     // it using shell file-expansion rules.  Return the list of all matched files
00218     // as absolute path + file names.  You may optionally drop the path and just return
00219     // the file names.   Note tha if <src>files(i)</src> contains a path as well as a file
00220     // name, no matching is done on the path, just the trailing file name.
00221     // Throws an AipsError if the shell pattern is illegal.
00222     static Vector<String> shellExpand (const Vector<String>& files, Bool stripPath=False);
00223     // Return the total size  of everything in the Directory. If the Directory
00224     // does not exist, an exception will be thrown.
00225     virtual Int64 size() const;
00226 
00227     //Check if a directory is mounted via NFS or not.
00228     Bool isNFSMounted() const;
00229     
00230 private:
00231     // Check if the path defines a directory.
00232     // Also resolve possible symlinks.
00233     void checkPath();
00234 
00235     // This variable is used when a symbolic link is given to be
00236     // a directory.
00237     File itsFile;
00238 };
00239 
00240 
00241 
00242 inline void Directory::copy (const String& target, Bool overwrite,
00243                              Bool setUserWritePermission) const
00244 {
00245     copy (Path(target), overwrite, setUserWritePermission);
00246 }
00247 inline void Directory::move (const String& target, Bool overwrite)
00248 {
00249     move (Path(target), overwrite);
00250 }
00251 inline uInt Directory::freeSpaceInMB() const
00252 {
00253     return uInt (0.5 + freeSpace() / (1024*1024));
00254 }
00255 
00256 
00257 
00258 } //# NAMESPACE CASA - END
00259 
00260 #endif