Directory.h

Classes

Directory -- Get information about, and manipulate directories (full description)

class Directory: public File

Interface

Public Members
Directory()
Directory (const Path& name)
Directory (const String& name)
Directory (const File& name)
Directory (const Directory& that)
~Directory()
Directory& operator= (const Directory& that)
Bool isEmpty() const
uInt nEntries() const
Double freeSpace() const
uInt freeSpaceInMB() const
void create (Bool overwrite = True)
void remove()
void removeFiles()
void removeRecursive()
void copy (const Path& target, Bool overwrite = True, Bool setUserWritePermission = True) const
void copy (const String& target, Bool overwrite = True, Bool setUserWritePermission = True) const
void move (const Path& target, Bool overwrite = True)
void move (const String& target, Bool overwrite = True)
Vector<String> find (const Regex& regexp, Bool followSymLinks=False, Bool recursive=True) const
static Vector<String> shellExpand (const Vector<String>& files, Bool stripPath=False)
Private Members
void checkPath()

Description

Review Status

Reviewed By:
UNKNOWN
Date Reviewed:
before2004/08/25

Prerequisite

Synopsis

Directory provides functions to manipulate and to get information about directories. The functions for getting information (like ownership, dates) about directories are inherited from the File class. Directory itself provides functions to create, copy, move, or remove a directory. The file name can be a symbolic link resolving (eventually) to a directory.

A separate class DirectoryIterator allows one to traverse a directory to get the file names in it.

Example

    Directory dir("someDir");
    // Create directory someDir in the working directory.
    dir.create();
    cout << dir.nEntries();        // #entries
    // Assign to another directory.
    dir = Directory("otherDir");
    // Remove the directory and its contents.
    dir.removeRecursive();

Motivation

Provide functions for manipulating and getting information about directories.

Member Description

Directory()

Sets the path on the current working directory

Directory (const Path& name)
Directory (const String& name)
Directory (const File& name)

Create a directory object for a file with the given path name. An exception is thrown if the directory is illegal, i.e. if it does not exist as a directory or symbolic link or if cannot be created. Note that the directory is not created if it does not exist yet. This can be done using the function create.
When the given path name is a symbolic link, the symbolic link is resolved (recursively) and the resulting directory name is used instead.

Directory (const Directory& that)

Copy constructor (copy semantics).

~Directory()

Directory& operator= (const Directory& that)

Assignment (copy semantics).

Bool isEmpty() const

Check if directory is empty. If the directory does not exist, an exception will be thrown.

uInt nEntries() const

Return the number of entries in the directory (not counting . and ..). If the directory does not exist, an exception will be thrown.

Double freeSpace() const
uInt freeSpaceInMB() const

Get the amount of free space (in bytes) on the file system this directory is on. When the directory path is a symbolic link, that link is resolved first.

void create (Bool overwrite = True)

Create the directory.
If the directory exists and overwrite=True, it will be removed (recursively). Otherwise an exception is thrown.

void remove()

Remove a directory. An exception is thrown if the directory is not empty. If a symbolic link is given, the link chain pointing to the directory will also be removed.

void removeFiles()

Remove all files in the directory except subdirectories. The directory itself is not removed.

void removeRecursive()

Remove the directory and its contents (recursively in all subdirectories).

void copy (const Path& target, Bool overwrite = True, Bool setUserWritePermission = True) const
void copy (const String& target, Bool overwrite = True, Bool setUserWritePermission = True) const

Copy the directory and its contents (recursively) to the target path using the system command cp -r. If the target already exists (as a file, directory or symlink), and overwrite=True, it will first be removed. The target directory is created and the data in the source directory is copied to the new directory.
An exception is thrown if:
- the target directory is not writable
- or the target already exists and overwrite!=True

Caution 1. The behavior of this copy function is different from cp when the target directory already exists. Cp copies the source to a subdirectory of the target, while copy recreates the target.
2. When a readonly file is copied, cp the resulting file is also readonly. Therefore chmod is used to set user write permission after the copy. The flag setUserWritePermission can be set to False when that should not be done.

void move (const Path& target, Bool overwrite = True)
void move (const String& target, Bool overwrite = True)

Move the directory to the target path using the system command mv. If the target already exists (as a file, directory or symlink), and overwrite=True, it will first be removed. The source directory is moved (thus renamed) to the target.
An exception is thrown if:
- the target directory is not writable
- or the target already exists and overwrite!=True

Caution The behavior of this move function is different from mv when the target directory already exists. Mv moves the source to a subdirectory of the target, while move recreates the target.

Vector<String> find (const Regex& regexp, Bool followSymLinks=False, Bool recursive=True) const

Find all files which whose names match regex. You can do this recursively (default) or not. Note that the matching is a regular expression match, not a shell file-expansion match. However, a shell file pattern can be converted to a regexp using the function Regex::fromPattern. Regex::fromString allows one to convert a file name to a regexp and to use this function for eact file name matching.
To match the semantics of the unix find command, symbolic links are not followed by default, but this behavior can be over-ridden.

static Vector<String> shellExpand (const Vector<String>& files, Bool stripPath=False)

For each element of files, find all file names matching it using shell file-expansion rules. Return the list of all matched files as absolute path + file names. You may optionally drop the path and just return the file names. Note tha if files(i) contains a path as well as a file name, no matching is done on the path, just the trailing file name. Throws an AipsError if the shell pattern is illegal.

void checkPath()

Check if the path defines a directory. Also resolve possible symlinks.