path.h

This software aims to create an applet and panel tools to manage a wireless interface card, such as

//
// Path.h
//
// $Id: //poco/Main/Foundation/include/Foundation/Path.h#5 $
//
// Definition of the Path class.
//
// Copyright (c) 2004, Guenter Obiltschnig/Applied Informatics.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
//
// 1. Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//
// 3. Redistributions in any form must be accompanied by information on
//    how to obtain complete source code for this software and any
//    accompanying software that uses this software.  The source code
//    must either be included in the distribution or be available for no
//    more than the cost of distribution plus a nominal fee, and must be
//    freely redistributable under reasonable conditions.  For an
//    executable file, complete source code means the source code for all
//    modules it contains.  It does not include source code for modules or
//    files that typically accompany the major components of the operating
//    system on which the executable file runs.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
// FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
// COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
// ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
//


#ifndef Foundation_Path_INCLUDED
#define Foundation_Path_INCLUDED


#ifndef Foundation_Foundation_INCLUDED
#include "Foundation/Foundation.h"
#endif
#ifndef STD_VECTOR_INCLUDED
#include <vector>
#define STD_VECTOR_INCLUDED
#endif


Foundation_BEGIN


class Foundation_API Path
	/// This class represents filesystem paths in a 
	/// platform-independent manner.
	/// Unix, Windows and OpenVMS all use a different
	/// syntax for filesystem paths.
	/// This class can work with all three formats.
	/// A path is made up of an optional node name
	/// (only Windows and OpenVMS), an optional
	/// device name (also only Windows and OpenVMS),
	/// a list of directory names and an optional
	/// filename.
{
public:
	enum Style
	{
		PATH_UNIX,    /// Unix-style path
		PATH_WINDOWS, /// Windows-style path
		PATH_VMS,     /// VMS-style path
		PATH_NATIVE,  /// The current platform's native style
		PATH_GUESS    /// Guess the style by examining the path
	};
	
	typedef std::vector<std::string> StringVec;

	Path();
		/// Creates an empty relative path.

	Path(bool absolute);
		/// Creates an empty absolute or relative path.

	Path(const char* path);
		/// Creates a path from a string.

	Path(const char* path, Style style);
		/// Creates a path from a string.

	Path(const std::string& path);
		/// Creates a path from a string.

	Path(const std::string& path, Style style);
		/// Creates a path from a string.

	Path(const Path& path);
		/// Copy constructor

	Path(const Path& parent, const std::string& fileName);
		/// Creates a path from a parent path and a filename.
		/// The parent path is expected to reference a directory.

	~Path();
		/// Destroys the Path.
		
	Path& operator = (const Path& path);
		/// Assignment operator.
		
	Path& operator = (const std::string& path);
		/// Assigns a string containing a path.

	Path& operator = (const char* path);
		/// Assigns a string containing a path.

	Path& assign(const std::string& path);
		/// Assigns a string containing a path.
		
	Path& assign(const std::string& path, Style style);
		/// Assigns a string containing a path.

	std::string toString() const;
		/// Returns a string containing the path in native format.
		
	std::string toString(Style style) const;
		/// Returns a string containing the path in the given format.
		
	Path& parse(const std::string& path);
		/// Same as assign().

	Path& parse(const std::string& path, Style style);
		/// Assigns a string containing a path.

	Path& parseDirectory(const std::string& path);
		/// The resulting path always refers to a directory and
		/// the filename part is empty.

	Path& parseDirectory(const std::string& path, Style style);
		/// The resulting path always refers to a directory and
		/// the filename part is empty.

	Path& makeDirectory();
		/// If the path contains a filename, the filename is appended
		/// to the directory list and cleared. Thus the resulting path
		/// always refers to a directory.

	Path& makeFile();
		/// If the path contains no filename, the last directory
		/// becomes the filename.

	Path& makeParent();
		/// Makes the path refer to its parent.
		
	Path& makeAbsolute();
		/// Makes the path absolute if it is relative.
		/// The current working directory is taken as base directory.

	Path& makeAbsolute(const Path& base);
		/// Makes the path absolute if it is relative.
		/// The given path is taken as base. 

	Path& append(const Path& path);
		/// Appends the given path.

	bool isAbsolute() const;
		/// Returns true iff the path is absolute.
		
	bool isRelative() const;
		/// Returns true iff the path is relative.
	
	bool isDirectory() const;
		/// Returns true iff the path references a directory
		/// (the filename part is empty).
		
	bool isFile() const;
		/// Returns true iff the path references a file
		/// (the filename part is not empty).
	
	void setNode(const std::string& node);
		/// Sets the node name.
		/// Setting a non-empty node automatically makes
		/// the path an absolute one.
		
	const std::string& getNode() const;
		/// Returns the node name.
		
	void setDevice(const std::string& device);
		/// Sets the device name.
		/// Setting a non-empty device automatically makes
		/// the path an absolute one.
		
	const std::string& getDevice() const;
		/// Returns the device name.
	
	int depth() const;
		/// Returns the number of directories in the directory list.

	const std::string& directory(int n) const;
		/// Returns the n'th directory in the directory list.
		/// If n == depth(), returns the filename.
		
	const std::string& operator [] (int n) const;
		/// Returns the n'th directory in the directory list.
		/// If n == depth(), returns the filename.
		
	void pushDirectory(const std::string& dir);
		/// Adds a directory to the directory list.
		
	void popDirectory();
		/// Removes the last directory from the directory list.
		
	void setFileName(const std::string& name);
		/// Sets the filename.
		
	const std::string& getFileName() const;
		/// Returns the filename.

	void setBaseName(const std::string& name);
		/// Sets the basename part of the filename and
		/// does not change the extension.

	std::string getBaseName() const;
		/// Returns the basename (the filename sans
		/// extension) of the path.

	void setExtension(const std::string& extension);
		/// Sets the filename extension.
				
	std::string getExtension() const;
		/// Returns the filename extension.
		
	const std::string& version() const;
		/// Returns the file version. VMS only.
		
	void clear();
		/// Clears all components.

	Path parent() const;
		/// Returns a path referring to the path's
		/// directory.
		
	Path absolute() const;
		/// Returns an absolute variant of the path,
		/// taking the current working directory as base.

	Path absolute(const Path& base) const;
		/// Returns an absolute variant of the path,
		/// taking the given path as base.

	static Path forDirectory(const std::string& path);
		/// Creates a path referring to a directory.

	static Path forDirectory(const std::string& path, Style style);
		/// Creates a path referring to a directory.

	static char separator();
		/// Returns the platform's path name separator, which separates
		/// the components (names) in a path. 
		///
		/// On Unix systems, this is the slash '/'. On Windows systems, 
		/// this is the backslash '\'. On OpenVMS systems, this is the
		/// period '.'.
		
	static char pathSeparator();
		/// Returns the platform's path separator, which separates
		/// single paths in a list of paths.
		///
		/// On Unix systems, this is the colon ':'. Opn Windows systems,
		/// this is the semicolon ';'. On OpenVMS systems, this is the
		/// comma ','.
		
	static std::string current();
		/// Returns the current working directory.
		
	static std::string home();
		/// Returns the user's home directory.
		
	static std::string temp();
		/// Returns the temporary directory.
		
	static std::string null();
		/// Returns the name of the null device.
		
	static std::string expand(const std::string& path);
		/// Expands all environment variables contained in the path.

	static void listRoots(std::vector<std::string>& roots);
		/// Fills the vector with all filesystem roots available on the
		/// system. On Unix, there is exactly one root, "/".
		/// On Windows, the roots are the drive letters.
		/// On OpenVMS, the roots are the mounted disks.
		
	static bool find(StringVec::const_iterator it, StringVec::const_iterator end, const std::string& name, Path& path);
		/// Searches the file with the given name in the locations (paths) specified
		/// by it and end. 
		///
		/// If the file is found in one of the locations, the complete
		/// path of the file is stored in the path given as argument and true is returned. 
		/// Otherwise false is returned and the path argument remains unchanged.

	static bool find(const std::string& pathList, const std::string& name, Path& path);
		/// Searches the file with the given name in the locations (paths) specified
		/// in pathList. The paths in pathList must be delimited by the platform's
		/// path separator (see pathSeparator()). 
		///
		/// If the file is found in one of the locations, the complete
		/// path of the file is stored in the path given as argument and true is returned. 
		/// Otherwise false is returned and the path argument remains unchanged.

protected:
	void parseUnix(const std::string& path);
	void parseWindows(const std::string& path);
	void parseVMS(const std::string& path);
	void parseGuess(const std::string& path);
	std::string buildUnix() const;
	std::string buildWindows() const;
	std::string buildVMS() const;

private:
	std::string _node;
	std::string _device;
	std::string _name;
	std::string _version;
	StringVec   _dirs;
	bool        _absolute;
};


//
// inlines
//
inline bool Path::isAbsolute() const
{
	return _absolute;
}

	
inline bool Path::isRelative() const
{
	return !_absolute;
}


inline bool Path::isDirectory() const
{
	return _name.empty();
}


inline bool Path::isFile() const
{
	return !_name.empty();
}


inline Path& Path::parse(const std::string& path)
{
	return assign(path);
}


inline Path& Path::parse(const std::string& path, Style style)
{
	return assign(path, style);
}


inline const std::string& Path::getNode() const
{
	return _node;
}


inline const std::string& Path::getDevice() const
{
	return _device;
}


inline const std::string& Path::getFileName() const
{
	return _name;
}


inline int Path::depth() const
{
	return int(_dirs.size());
}


inline const std::string& Path::version() const
{
	return _version;
}


inline Path Path::forDirectory(const std::string& path)
{
	Path p;
	return p.parseDirectory(path);
}
	

inline Path Path::forDirectory(const std::string& path, Style style)
{
	Path p;
	return p.parseDirectory(path, style);
}


inline char Path::separator()
{
#if defined(POCO_OS_FAMILY_VMS)
	return '.';
#elif defined(POCO_OS_FAMILY_WINDOWS)
	return '\\';
#else
	return '/';
#endif
}


inline char Path::pathSeparator()
{
#if defined(POCO_OS_FAMILY_VMS)
	return ',';
#elif defined(POCO_OS_FAMILY_WINDOWS)
	return ';';
#else
	return ':';
#endif
}


Foundation_END


#endif // Foundation_Path_INCLUDED