Path.h

The term 'path' is the standard term for describing the location of a file in a hierarchy of possibly nested directories. In order to find a particular file you must travel a specific path strating from a known point. We use the term in its standard sense in this class.

Synopsis

This class can be used to describe a pathname. One can also create, validate, parse (get base or directory names or original, expanded or absolute names), query and append strings. The client programmer can give a string, at construction, which describes a path. This string can be a relative or an absolute name. Environment variables and a tilde (with or without user name) can also be used in the string and will be expanded by the function expandedName.
The function Once a Path has been constructed, you can query the object for its original name, expanded name, absolute name, the name of the directory where it is found or the name of only the file. Expanding the path name means that possible environment variables and tilde get expanded. There are also functions to get the length or maximum length of a path. Pathnames can also be checked on correctness and they can be checked if they conform the POSIX standard.

Example

In this example a few pathnames are created.

    Path test1("~/test/$TEST1/..");     // absolute path
    Path test2("/$HOME/./analyse");     // absolute path
    Path test3("myFile");               // relative path
 
    cout << test1.originalName() << endl;

    // Test1 is according the POSIX standard
    if (test1.isStrictlyPosix()){         
       cout << "test1 is strictly POSIX << endl;  
    }
 
    // Test1 is valid
    if (test1.isValid()){                 
       cout << test1.isValid() << endl;
    }

    // if "TEST1=$TEST2 and TEST2=$TEST1"(recursive environment variables) 
    // an exception will be thrown. ~ is replaced by the homedirectory
    cout << test1.expandedName() << endl;
    // $HOME is expanded 
    cout << test2.expandedName() << endl; 
    cout << test1.absoluteName() << endl; 
    cout << test2.absoluteName() << endl; 
    cout << test2.baseName() << endl;
    cout << test1.dirName() << endl;
    cout << test3.originalName() << endl; // myFile is returned 
    cout << test3.expandedName() << endl; // Nothing is changed
    cout << test3.absoluteName() << endl; // The current working directory
                                             is placed before 'myFile'  
    cout << test3.baseName() << endl; // The current working directory 
                                      // is returned
    cout << test3.dirName() << endl;  // myFile is returned

Motivation

Programmer convenience and (eventually) OS independence.

To Do

To make the class OS independent some functions should be rebuild. These functions could be expandedName or absoluteName.
The function expandedName or absoluteName could map the filename to the native convention
A (maybe static) function contractName(const String& pathName) could be implemented to remove . and .. from the file name.

Member Description

Path()

Default constructor, the path is set to . (working directory).

Path (const String& pathName)

Construct a path with the given name. When the name is empty, it is set to . (working directory). It is not checked if the path name is valid. Function isValid() can be used for that purpose.

Path (const Path& that)

Copy constructor, copy semantics.

~Path()

Destructor

Path& operator= (const Path& that)

Assignment, copy semantics.

void append (const String& string)

Append a string to the path name. When the current path does not end with a / and the string to append does not start with a /, an intermediate / is also added.

const String& originalName () const

Returns the string as given at construction.

const String& expandedName () const

Return a string giving the expanded pathname. This means that the environment variables are expanded and the tilde is replaced by the home directory. An expanded name can still be a relative path. An exception is thrown when converting a recursive environment variable results in an endless loop (that is, more than 25 substitutions).

const String& absoluteName () const

Return the string which giving the absolute pathname. It is generated from the expanded pathname by adding the working directory when needed.

Bool isValid() const

Check if pathname is valid. This function checks for: double slashes, non-printable characters, pathname length and filename lenghts, this function is more OS-specific.

Bool isStrictlyPosix() const

Check if pathname is valid according the POSIX standard. This function checks for double slashes, non-printable characters,pathname length and filename lenghts, all according to the POSIX-standard.

uInt length() const

Return length of path name

uInt maxLength() const

Return the maximum length a path name can have.

String baseName() const

Return the basename of the path; this is only the name of the file. It takes it from the expanded path name.

String dirName() const

Return the dirname of the path; this is the directory where the filename is found. It takes it from the expanded path name.
To get the absolute dirname one could do:

     Path tmpPath (myPath.dirName());
     String absDir (tmpPath.absoluteName());

     Path tmpPath (myPath.absoluteName());
     String absDir (tmpPath.dirName());

static String stripDirectory (const String& name, const String& otherName)

Strip otherName from this name. If stripped, the result gets a leading ././ If not stripped, it is tried if name can be stripped from otherName. If stripped, the result gets a trailing /. If still not stripped, it is tried to strip the directory of otherName. If that succeeds, the result gets a leading ./ This is used by RefTable and TableKeyword to ensure that the name of a subtable or referenced table is always relative to the main table.

static String addDirectory (const String& name, const String& otherName)

If the name starts with ././ add otherName to it. If the name ends with /. strip name from otherName and return the remainder. If the name starts with ./ add the directory of otherName to it. It is the opposite of stripDirectory.

static uInt getMaxPathNameSize ()

Define the maximum number of bytes in a pathname This definition does not use Posix values.

static uInt getMaxNameSize ()

Define the maximum number of bytes in a filename This definition does not use Posix values.

String expandName (const String& inString) const

This function is used by expandedName to replace the tilde and to expand the environment variables

String makeAbsoluteName (const String& inString) const

This function is used by absoluteName to make a name absolute, this means that the name is described from the root

String removeDots (const String& inString) const

Remove . and .. from the path name. Also multiple slashes are replaced by a single.

void getNextName (const String& inString, uInt& count) const

This function is used by expandName and absoluteName. It sets the integer "count" on the next slash or on the end of a string