This class encapsulates the handling of file and directory pathnames in a platform-independent manner. More...

#include <Plugin.h>

Static Public Member Functions
static void	deconstructPathname (const std::string &name, bool &isAbsolutePath, std::string &directory, std::string &fileName, std::string &extension)
	Dismantle a supplied pathname into its component parts.
static std::string	getAbsolutePathname (const std::string &pathname)
	Get canonicalized absolute pathname from a given pathname which can be relative or absolute.
static std::string	getAbsoluteDirectoryPathname (const std::string &dirPathname)
	This is the same as getAbsolutePathname() except that the final segment is interpreted as a directory name rather than a file name, meaning that we append a slash if necessary.
static std::string	getDefaultInstallDir ()
	Get the default installation directory for this platform.
static std::string	addDirectoryOffset (const std::string &base, const std::string &offset)
	Append a subdirectory offset to an existing pathname (relative or absolute).
static std::string	getInstallDir (const std::string &envInstallDir, const std::string &offsetFromDefaultInstallDir)
	Find the installation directory for something, using the named installation directory environment variable if it exists, otherwise by appending the supplied path offset to the default install directory.
static std::string	getThisExecutablePath ()
	Get the absolute pathname of the currently executing program.
static std::string	getThisExecutableDirectory ()
	Get the absolute pathname of the directory which contains the currently executing program.
static std::string	getCurrentWorkingDirectory (const std::string &drive="")
	Get the absolute pathname of the current working directory including a trailing separator character.
static std::string	getRootDirectory (const std::string &drive="")
	Get the canonicalized name of the root directory.
static std::string	getCurrentDriveLetter ()
	On Windows, return the current drive letter in lowercase, with no trailing ":"; on other platforms return an empty string.
static std::string	getCurrentDrive ()
	On Windows, return the current drive letter in lowercase, followed by ":"; on other platforms just return an empty string.
static bool	environmentVariableExists (const std::string &name)
	Return true if the named environment variable is present in the environment.
static std::string	getEnvironmentVariable (const std::string &name)
	Return the value of the named environment variable or the empty string if the variable is not found.
static std::string	getPathSeparator ()
	Return this platform's pathname separator character as a string.
static char	getPathSeparatorChar ()
	Return this platform's pathname separator character as a char.
static bool	isPathSeparator (char c)
	Returns true if the character is slash or backslash.

Detailed Description

This class encapsulates the handling of file and directory pathnames in a platform-independent manner.

We consider a pathname to consist of three components:

 [directory] [filename [extension]]

where the directory may be an absolute location or relative to a current working directory.

Several special directory names are supported here:

root (/)
current working directory (.)
current executable directory (@)
platform default installation directory
parent directory (..)

On Windows root and current working directory are drive-specific, referring to the current drive if none is specified. The current executable directory is the absolute directory name containing the executable program which is currently running.

A pathname has "segments" which are separated by either forward slashes or backslashes. We are relaxed about the slashes and will accept either one and pathnames which use both. However, each operating system platform has a preferred separator character, backslash on Windows and forward slash everywhere else and we will clean up returned pathnames to use exclusively the preferred separator for the current platform.

Pathnames that end in an empty segment, or a segment consisting of just "." or ".." are directory path names, meaning that the "filename" and "extension" components are empty. Other pathnames may be directories or filenames depending on context. Whenever we generate a pathname that we know to e a directory, it will end in a final slash.

There is also the concept of a "drive" which on Windows is a drive letter followed by a colon (e.g. "c:") but is always the empty string on non-Windows platforms. The drive, if present is considered part of the directory and does not affect whether the directory is considered relative or absolute. Drive designators are recognized only on Windows; they are just considered ordinary pathname characters on other platforms.

This class is useful for generating "canonicalized" pathnames from names that have been pieced together from environment variables and user entry. Canonicalized names are always absolute pathnames; they contain no empty, ".", or ".." segments. On Windows a canonicalized name is always prefixed by an explicit disk designator followed by a backslash; on other platforms the canonicalized name will always begin with a forward slash.

Member Function Documentation

static void SimTK::Pathname::deconstructPathname	(	const std::string &	name,
		bool &	isAbsolutePath,
		std::string &	directory,
		std::string &	fileName,
		std::string &	extension
	)		`[static]`

Dismantle a supplied pathname into its component parts.

This can take pathnames like

   
            /usr/local/libMyDll_d.so
            e:\Program Files\Something\myLibrary_d.dll

and chop them into

        directory                       fileName       extension
        ------------------------------- -------------- ---------
        /usr/local/                     libMyDll_d     .so 
        e:\Program Files\Something\     myLibrary_d    .dll

as well as tell you whether the given pathname is absolute or relative (and thus subject to search rules). At the beginning of the pathname (or right after the drive specification on Windows) we recognize three special symbols:

"/" means root; i.e., this is an absolute path name starting from the root directory (this drive's root for Windows).
"." starts an absolute path name which is relative to the current working directory (or drive's cwd on Windows).
"@" starts an absolute path name which is relative to the directory in which the currently running executable is located.

Anywhere in the pathname, the name ".." means "go up one level from the prior directory". ".." at the start is interpreted as "./..". A '.' appearing anywhere in the path name except the begining is ignored. An '@' appearing anywhere in the pathname other than the beginning is treated as an ordinary file character.

The pathname components are returned as separate strings with separators included such that concatenating all the strings reproduces the pathname in a canonicalized form. The "drive" letter prefix is recognized only when running on Windows; otherwise a prefix like "C:" is treated as ordinary file name characters. Note that we include the drive letter as part of the absolute directory. White space is removed, and path separator characters in the directory are changed to the appropriate slash for the currently running platform (i.e. backslash for Windows and forward slash everywhere else).

static std::string SimTK::Pathname::getAbsolutePathname ( const std::string & pathname ) [inline, static]

Get canonicalized absolute pathname from a given pathname which can be relative or absolute.

Canonicalizing means

drive designator is recognized if we're on Windows;
leading "." and "@" are replaced with the current working directory or the executable directory, resp.
each ".." segment is processed, removing it and its previous segment; initial ".." is treated as "./..".
empty segments and interior "." segments are removed
if the input pathname ends in a slash after above processing, then the returned pathname will also end in a slash.
separators are made all-forward slash or all-backslash
on Windows, the returned pathname begins with an explicit disk designator in lower case, e.g. "c:".

The result here is what you get by reassembling the components from deconstructPathname(), plus inserting the current working directory in front if the path name was relative.

static std::string SimTK::Pathname::getAbsoluteDirectoryPathname ( const std::string & dirPathname ) [inline, static]

This is the same as getAbsolutePathname() except that the final segment is interpreted as a directory name rather than a file name, meaning that we append a slash if necessary.

static std::string SimTK::Pathname::getDefaultInstallDir ( ) [static]

Get the default installation directory for this platform.

This will be /usr/local/ for Linux and Apple, and the value of the %ProgramFiles% registry entry on Windows (typically c:\Program Files\).

static std::string SimTK::Pathname::addDirectoryOffset	(	const std::string &	base,
		const std::string &	offset
	)		`[static]`

Append a subdirectory offset to an existing pathname (relative or absolute).

A leading "/" in the offset is ignored, and the result ends in "/".

static std::string SimTK::Pathname::getInstallDir	(	const std::string &	envInstallDir,
		const std::string &	offsetFromDefaultInstallDir
	)		`[static]`

Find the installation directory for something, using the named installation directory environment variable if it exists, otherwise by appending the supplied path offset to the default install directory.

static std::string SimTK::Pathname::getThisExecutablePath ( ) [static]

Get the absolute pathname of the currently executing program.

static std::string SimTK::Pathname::getThisExecutableDirectory ( ) [static]

Get the absolute pathname of the directory which contains the currently executing program.

static std::string SimTK::Pathname::getCurrentWorkingDirectory ( const std::string & drive = "" ) [static]

Get the absolute pathname of the current working directory including a trailing separator character.

Windows keeps a current working directory for each drive which can be optionally specified (otherwise we use the current drive). If the specified drive doesn't exist we'll behave as though root were its current working directory. The drive argument is ignored on non-Windows platforms.

static std::string SimTK::Pathname::getRootDirectory ( const std::string & drive = "" ) [static]

Get the canonicalized name of the root directory.

This is "x:\" on Windows with "x" replaced by the current drive letter or the specified drive (in lowercase), and just "/" on non-Windows systems.

static std::string SimTK::Pathname::getCurrentDriveLetter ( ) [static]

On Windows, return the current drive letter in lowercase, with no trailing ":"; on other platforms return an empty string.

static std::string SimTK::Pathname::getCurrentDrive ( ) [static]

On Windows, return the current drive letter in lowercase, followed by ":"; on other platforms just return an empty string.

static bool SimTK::Pathname::environmentVariableExists ( const std::string & name ) [static]

Return true if the named environment variable is present in the environment.

static std::string SimTK::Pathname::getEnvironmentVariable ( const std::string & name ) [static]

Return the value of the named environment variable or the empty string if the variable is not found.

Note that that is indistinguishable from a variable that is present but with a null value -- use environmentVariableExists() if you really need to know the difference.

static std::string SimTK::Pathname::getPathSeparator ( ) [static]

Return this platform's pathname separator character as a string.

This is backslash on Windows and forward slash everywhere else.

static char SimTK::Pathname::getPathSeparatorChar ( ) [static]

Return this platform's pathname separator character as a char.

This is backslash on Windows and forward slash everywhere else.

static bool SimTK::Pathname::isPathSeparator ( char c ) [inline, static]

Returns true if the character is slash or backslash.

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

Plugin.h

SimTK::Pathname Class Reference

Static Public Member Functions

Detailed Description

Member Function Documentation