casa::Path Class Reference

Path name of a file. More...

#include <Path.h>

List of all members.

Public Member Functions
	Path ()
	Default constructor, the path is set to .
	Path (const String &pathName)
	Construct a path with the given name.
	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.
const String &	originalName () const
	Returns the string as given at construction.
const String &	expandedName () const
	Return a string giving the expanded pathname.
const String &	absoluteName () const
	Return the string which giving the absolute pathname.
String	resolvedName () const
	Return the realpath which is the absolute pathname with possible symlinks resolved.
Bool	isValid () const
	Check if pathname is valid.
Bool	isStrictlyPosix () const
	Check if pathname is valid according 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.
String	dirName () const
	Return the dirname of the path; this is the directory where the filename is found.
Static Public Member Functions
static String	stripDirectory (const String &name, const String &otherName)
	Strip otherName from this name.
static String	addDirectory (const String &name, const String &otherName)
	If the name starts with .
Private Member Functions
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 .
void	getNextName (const String &inString, uInt &count) const
	This function is used by expandName and absoluteName.
Static Private Member Functions
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.
Private Attributes
String	itsOriginalPathName
	Strings to describe the pathname in three different ways.
String	itsAbsolutePathName
	These variables are pointer to strings because the functions which use these variables are const functions.
String	itsExpandedPathName

---

Detailed Description

Path name of a file.

Review Status

Reviewed By:

UNKNOWN

Date Reviewed:

before2004/08/25

Prerequisite

• Basic knowledge of the UNIX file system

Etymology

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.

Definition at line 126 of file Path.h.

---

Constructor & Destructor Documentation

casa::Path::Path

(

)

Default constructor, the path is set to .

(working directory).

casa::Path::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.

casa::Path::Path

(

const Path &

that

)

Copy constructor, copy semantics.

casa::Path::~Path

(

)

Destructor.

---

Member Function Documentation

const String& casa::Path::absoluteName

(

)

const

Return the string which giving the absolute pathname.

It is generated from the expanded pathname by adding the working directory when needed.

static String casa::Path::addDirectory	(	const String &	name,
		const String &	otherName
	)		[static]

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.

void casa::Path::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.

String casa::Path::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 casa::Path::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());

or

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

const String& casa::Path::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).

String casa::Path::expandName

(

const String &

inString

)

const [private]

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

static uInt casa::Path::getMaxNameSize

(

)

[static, private]

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

static uInt casa::Path::getMaxPathNameSize

(

)

[static, private]

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

void casa::Path::getNextName	(	const String &	inString,
		uInt &	count
	)		const [private]

This function is used by expandName and absoluteName.

It sets the integer "count" on the next slash or on the end of a string

Bool casa::Path::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.

Bool casa::Path::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.

uInt casa::Path::length

(

)

const

Return length of path name.

String casa::Path::makeAbsoluteName

(

const String &

inString

)

const [private]

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

uInt casa::Path::maxLength

(

)

const

Return the maximum length a path name can have.

Path& casa::Path::operator=

(

const Path &

that

)

Assignment, copy semantics.

const String & casa::Path::originalName

(

)

const [inline]

Returns the string as given at construction.

Definition at line 265 of file Path.h.

References itsOriginalPathName.

String casa::Path::removeDots

(

const String &

inString

)

const [private]

Remove .

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

String casa::Path::resolvedName

(

)

const

Return the realpath which is the absolute pathname with possible symlinks resolved.

It also resolves //, /./, /../ and trailing /.
The path must be an existing file or directory. It uses the system's realpath function. In case it fails, an exception is thrown.

static String casa::Path::stripDirectory	(	const String &	name,
		const String &	otherName
	)		[static]

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.

---

Member Data Documentation

String casa::Path::itsAbsolutePathName [mutable, private]

These variables are pointer to strings because the functions which use these variables are const functions.

This means that they would not be able to modify the string, now they can.

Definition at line 236 of file Path.h.

String casa::Path::itsExpandedPathName [mutable, private]

Definition at line 237 of file Path.h.

String casa::Path::itsOriginalPathName [private]

Strings to describe the pathname in three different ways.

Definition at line 232 of file Path.h.

Referenced by originalName().

---

The documentation for this class was generated from the following file:

• casacore/casa/OS/Path.h