A VFSNode represents a file or directory in the file system, whether it actually exists or not, and provides some methods for operating on it. More...

#include <vfsnode.h>

Public Types
enum	KnownDirectoryIdentifier { USER_HOME_DIRECTORY, LOG_FILES_DIRECTORY, USER_PREFERENCES_DIRECTORY, CACHED_DATA_DIRECTORY, APPLICATION_DATA_DIRECTORY, CURRENT_WORKING_DIRECTORY, EXECUTABLE_DIRECTORY }
	These values identify different known folders whose location you can access by calling VFSNode::getKnownDirectoryNode(). More...
Public Member Functions
	VFSNode ()
	Constructs an undefined VFSNode object (you will have to set its path with a subsequent call to setPath()).
	VFSNode (const VFSNode &rhs)
	Copy constructor.
	VFSNode (const VString &path)
	Constructs a VFSNode with a path.
	VFSNode (const VFSNode &directory, const VString &childName)
	Constructs a VFSNode with a parent directory node and a child directory or file name within it.
virtual	~VFSNode ()
	Destructor.
VFSNode &	operator= (const VFSNode &other)
	Assignment operator.
void	setPath (const VString &path)
	Specifies the path of the node.
void	getPath (VString &path) const
	Gets the path of the node.
const VString &	getPath () const
	Returns a reference to the node's path.
void	getName (VString &name) const
	Returns the node's name, without any directory path information.
VString	getName () const
	Alternate convenience function for getName().
void	setName (const VString &name)
	Specifies the name of the node, without changing the parent path nor actually renaming anything on disk (as one of the renameXXX() methods would do).
void	getParentPath (VString &parentPath) const
	Gets the path of the node's parent.
void	getParentNode (VFSNode &parent) const
	Gets a VFSNode of the node's parent.
void	getChildPath (const VString &childName, VString &childPath) const
	Gets the path of a child of the node (the node must be a directory).
void	getChildNode (const VString &childName, VFSNode &child) const
	Gets the node of a child of the node (the node must be a directory).
void	mkdirs () const
	Creates the directory the node represents, and all non-existent directories above it.
void	mkdir () const
	Creates the directory the node represents.
bool	rm () const
	Deletes the node; if it is a directory its contents are deleted first.
bool	rmDirContents () const
	Deletes the contents of the directory node (the node must be a directory).
bool	exists () const
	Returns true if the node (file or directory) currently exists.
VInstant	creationDate () const
	Returns the node's creation date.
VInstant	modificationDate () const
	Returns the node's modification date.
VFSize	size () const
	Returns the file node's size (must be a file node).
bool	isFile () const
	Returns true if the node is a file.
bool	isDirectory () const
	Returns true if the node is a directory.
void	renameToPath (const VString &newPath) const
	Renames the node by specifying its new path; this could include changing its directory location.
void	renameToName (const VString &newName) const
	Renames the node by specifying its new name; this means just changing the leaf file or dir name, without changing its containing path.
void	renameToName (const VString &newName, VFSNode &nodeToUpdate) const
	Renames the node by specifying its new name; this means just changing the leaf file or dir name, without changing its containing path.
void	renameToNode (const VFSNode &newNode) const
	Renames the node by specifying a node whose path to use; this could include changing its directory location.
void	list (VStringVector &children) const
	Returns a vector of strings containing the names of the node's children (the node must be a directory).
void	list (VFSNodeVector &children) const
	Returns a vector of nodes, one for each of the node's children (the node must be a directory).
void	iterate (VDirectoryIterationCallback &callback) const
	Iterates over the directory's nodes, calling the supplied callback object for each one (the "." and ".." are omitted).
bool	find (const VString &name, VFSNode &node) const
	Iterates over the directory until it finds the specified child node using a case-insensitive match on the node names.
void	readAll (VString &s, bool includeLineEndings=true)
	This convenience function does the following in a single call:
void	readAll (VStringVector &lines)
	This convenience function is like the other readAll, but it returns the file's contents as a vector of strings rather than a single giant string.
Static Public Member Functions
static VString	normalizePath (const VString &path)
	Takes a platform-specific directory path and returns the normalized form necessary for use with VFSNode.
static VString	denormalizePath (const VString &path)
	The reverse of normalizePath -- takes a normalized path and undoes the normalization, turning it into a platform-specific path.
static VFSNode	getKnownDirectoryNode (KnownDirectoryIdentifier id, const VString &companyName, const VString &appName)
	Returns a node identifying an identified directory, creating it if it does not exist.
static VFSNode	getCurrentWorkingDirectory ()
	This convenience function returns the current working directory path node; it is equivalent to calling getKnownDirectoryNode with CURRENT_WORKING_DIRECTORY.
static VFSNode	getExecutableDirectory ()
	This convenience function returns the directory path node of the directory containing the application executable; it is equivalent to calling getKnownDirectoryNode with EXECUTABLE_DIRECTORY.
static VFSNode	getExecutable ()
	This function returns the file node of the application executable.
static void	safelyOverwriteFile (const VFSNode &target, Vs64 dataLength, VBinaryIOStream &dataStream)
	This function safely overwrites an existing file using a temporary file, to ensure that the original file is intact if the write fails.
static VString	readTextFile (const VString &path, bool includeLineEndings=true)
	The static version of readAll(VString&), for more concise calling code, at the expense of a likely string copy to return by value.
static void	readTextFile (const VString &path, VStringVector &lines)
	The static version of readAll(VStringVector&), for more concise calling code.
Friends
bool	operator< (const VFSNode &lhs, const VFSNode &rhs)
bool	operator<= (const VFSNode &lhs, const VFSNode &rhs)
bool	operator>= (const VFSNode &lhs, const VFSNode &rhs)
bool	operator> (const VFSNode &lhs, const VFSNode &rhs)

Detailed Description

A VFSNode represents a file or directory in the file system, whether it actually exists or not, and provides some methods for operating on it.

Definition at line 120 of file vfsnode.h.

Member Enumeration Documentation

enum VFSNode::KnownDirectoryIdentifier

These values identify different known folders whose location you can access by calling VFSNode::getKnownDirectoryNode().

These are useful as default locations to store or find data in a location that is appropriate to the platform.

Enumerator:

USER_HOME_DIRECTORY	The user's home directory.
LOG_FILES_DIRECTORY	Where to write log files.
USER_PREFERENCES_DIRECTORY	Where to store user preferences files.
CACHED_DATA_DIRECTORY	Where to store non-critical cached data files.
APPLICATION_DATA_DIRECTORY	Where to find application data files other than user documents.
CURRENT_WORKING_DIRECTORY	The application environment's "current working directory" by path (not as simply ".").
EXECUTABLE_DIRECTORY	The directory where the app executable lives. (See notes below.)

Definition at line 149 of file vfsnode.h.

Constructor & Destructor Documentation

VFSNode::VFSNode ( const VString & path )

Constructs a VFSNode with a path.

Parameters:

path	the path of the file or directory

Definition at line 238 of file vfsnode.cpp.

References VString::isEmpty().

VFSNode::VFSNode	(	const VFSNode &	directory,
		const VString &	childName
	)

Constructs a VFSNode with a parent directory node and a child directory or file name within it.

Parameters:

directory	the parent directory of the node
childName	the name of the subdirectory or file within the parent

Definition at line 247 of file vfsnode.cpp.

References getChildNode().

Member Function Documentation

VString VFSNode::normalizePath ( const VString & path ) [static]

Takes a platform-specific directory path and returns the normalized form necessary for use with VFSNode.

If you are given a path from the user or OS that is in the OS path format (for example, a DOS path with backslashes), you need to normalize it (with slashes as path separators) before supplying it to VFSNode.

Parameters:

path	a string containing a platform-specific path, which will be modified in place into normalized form

Returns:: the normalized form of the path

Definition at line 124 of file vfsnode.cpp.

VString VFSNode::denormalizePath ( const VString & path ) [static]

The reverse of normalizePath -- takes a normalized path and undoes the normalization, turning it into a platform-specific path.

Parameters:

path	a string containing a normalized path, which will be modified in place into platform-specific form

Returns:: the denormalized form of the path

Definition at line 129 of file vfsnode.cpp.

VFSNode VFSNode::getKnownDirectoryNode	(	KnownDirectoryIdentifier	id,
		const VString &	companyName,
		const VString &	appName
	)		`[static]`

Returns a node identifying an identified directory, creating it if it does not exist.

(*) Below are the platform-specific path examples. Note that these are merely examples, because the OS may return something else as appropriate when we call the platform-specific APIs to locate the suitable directories. (* The user home directory is never created, because it is assumed to exist.)

Unix: (note that "~" denotes the user's home directory, wherever that may be, and does not actually appear in the path) Most of these we would prefer to locate under /var, but it is often not writable. USER_HOME_DIRECTORY: ~ is typically /home/(user) LOG_FILES_DIRECTORY: ~/log/(company)/(app) USER_PREFERENCES_DIRECTORY: ~/.(company)/(app) CACHED_DATA_DIRECTORY: ~/cache/(company)/(app) APPLICATION_DATA_DIRECTORY: ~/data/(company)/(app) CURRENT_WORKING_DIRECTORY: the full path to the current working directory EXECUTABLE_DIRECTORY: the full path to the directory containing the executable

Mac OS X: (note that "~" denotes the user's home directory, wherever that may be, and does not actually appear in the path) USER_HOME_DIRECTORY: ~ is typically /Users/(user) LOG_FILES_DIRECTORY: ~/Library/Logs/(company)/(app) USER_PREFERENCES_DIRECTORY: ~/Library/Preferences/(company)/(app) CACHED_DATA_DIRECTORY: ~/Library/Caches/(company)/(app) APPLICATION_DATA_DIRECTORY: ~/Library/(company)/(app) CURRENT_WORKING_DIRECTORY: the full path to the current working directory EXECUTABLE_DIRECTORY: the full path to the directory containing this app bundle or executable

iOS: (note that "@" here denotes the app install sandbox directory, and does not actually appear in the path) On iOS an app gets installed in its own sandbox at: /var/mobile/Applications/(random serial number for this install) USER_HOME_DIRECTORY: @ (the same dir as the app install sandbox; it is thus different when queried by each installed app) LOG_FILES_DIRECTORY: @/Library/Logs/(company)/(app) USER_PREFERENCES_DIRECTORY: @/Library/Preferences/(company)/(app) CACHED_DATA_DIRECTORY: @/Library/Caches/(company)/(app) APPLICATION_DATA_DIRECTORY: @/Library/(company)/(app) CURRENT_WORKING_DIRECTORY: / (obviously this is not a writeable directory in this environment) EXECUTABLE_DIRECTORY: @

Windows XP: (note that the OS can return a different Application Data path, including a different drive letter, if so configured; these are just the typical case examples) USER_HOME_DIRECTORY: C:/Documents and Settings/(user) LOG_FILES_DIRECTORY: C:/Documents and Settings/(user)/Application Data/(company)/(app)/Logs USER_PREFERENCES_DIRECTORY: C:/Documents and Settings/(user)/Application Data/(company)/(app)/Preferences CACHED_DATA_DIRECTORY: C:/Documents and Settings/(user)/Application Data/(company)/(app)/Caches APPLICATION_DATA_DIRECTORY: C:/Documents and Settings/(user)/Application Data/(company)/(app) CURRENT_WORKING_DIRECTORY: the full path to the current working directory EXECUTABLE_DIRECTORY: the full path to the directory containing this app's .exe file

Windows 7: (note that the OS can return a different Application Data path, including a different drive letter, if so configured; these are just the typical case examples; use of the "Roaming" folder is merely one type of network configuration) USER_HOME_DIRECTORY: C:/Users/(user)/AppData LOG_FILES_DIRECTORY: C:/Users/(user)/AppData/Roaming/(company)/(app)/Logs USER_PREFERENCES_DIRECTORY: C:/Users/(user)/AppData/Roaming/(company)/(app)/Preferences CACHED_DATA_DIRECTORY: C:/Users/(user)/AppData/Roaming/(company)/(app)/Caches APPLICATION_DATA_DIRECTORY: C:/Documents and Settings/(user)/Application Data/(company)/(app) CURRENT_WORKING_DIRECTORY: the full path to the current working directory EXECUTABLE_DIRECTORY: the full path to the directory containing this app's .exe file

When asking for the user home directory, the supplied company and app names are not used.

Parameters:

id	the directory identifier
companyName	if not empty, a first-level subdirectory used in the hierarchy (not used for USER_HOME_DIRECTORY and CURRENT_WORKING_DIRECTORY)
appName	if not empty, a second-level subdirectory used in the hierarchy (not used for USER_HOME_DIRECTORY and CURRENT_WORKING_DIRECTORY)

Returns:: the specified directory node

Exceptions:

may	throw VException if there is an error attempting to locate the specified directory

Definition at line 134 of file vfsnode.cpp.

VFSNode VFSNode::getCurrentWorkingDirectory ( ) [static]

This convenience function returns the current working directory path node; it is equivalent to calling getKnownDirectoryNode with CURRENT_WORKING_DIRECTORY.

Returns:: the current working directory node, defined by a full path rather than simply "."

Exceptions:

may	throw VException if there is an error attempting to locate the specified directory

Definition at line 139 of file vfsnode.cpp.

References CURRENT_WORKING_DIRECTORY, VString::EMPTY(), and getKnownDirectoryNode().

VFSNode VFSNode::getExecutableDirectory ( ) [static]

This convenience function returns the directory path node of the directory containing the application executable; it is equivalent to calling getKnownDirectoryNode with EXECUTABLE_DIRECTORY.

Returns:: the directory node in which the executable is located

Exceptions:

may	throw VException if there is an error attempting to locate the specified directory

Definition at line 144 of file vfsnode.cpp.

References VString::EMPTY(), EXECUTABLE_DIRECTORY, and getKnownDirectoryNode().

VFSNode VFSNode::getExecutable ( ) [static]

This function returns the file node of the application executable.

Returns:: the file node representing the application executable

Exceptions:

may	throw VException if there is an error attempting to locate the file

Definition at line 149 of file vfsnode.cpp.

void VFSNode::safelyOverwriteFile	(	const VFSNode &	target,
		Vs64	dataLength,
		VBinaryIOStream &	dataStream
	)		`[static]`

This function safely overwrites an existing file using a temporary file, to ensure that the original file is intact if the write fails.

Specifically, the sequence is: 1. create a temporary file next to the target file (named uniquely via current timestamp string) 2. write to the temporary file 3. delete the target file (it's OK if it doesn't exist) 4. rename the temporary file to the target file's name If steps 1, 2, or 3 fails, the original remains and the temporary is deleted. If there is a failure, a VException is thrown.

Parameters:

target	the file node to be overwritten (if it exists)
dataLength	the length of the data to be written
dataStream	the stream to be written to the file

Definition at line 156 of file vfsnode.cpp.

References exists(), VIOStream::flush(), VInstant::getLocalString(), getName(), getParentNode(), getPath(), VBufferedFileStream::openWrite(), renameToNode(), rm(), VStream::streamCopy(), and VException::what().

VFSNode & VFSNode::operator= ( const VFSNode & other )

Assignment operator.

Parameters:

other the node to copy

Definition at line 253 of file vfsnode.cpp.

void VFSNode::setPath ( const VString & path )

Specifies the path of the node.

Parameters:

path	the path of the file or directory

Definition at line 258 of file vfsnode.cpp.

References VString::isEmpty().

void VFSNode::getPath ( VString & path ) const

Gets the path of the node.

Parameters:

path	the string to set

Definition at line 265 of file vfsnode.cpp.

const VString & VFSNode::getPath ( ) const

Returns a reference to the node's path.

Returns:: the path

Definition at line 269 of file vfsnode.cpp.

void VFSNode::getName ( VString & name ) const

Returns the node's name, without any directory path information.

That is, the file or directory name, only.

Parameters:

name	the string to set to the file or node name

Definition at line 273 of file vfsnode.cpp.

References VString::chars(), VString::copyFromBuffer(), VString::lastIndexOf(), and VString::length().

VString VFSNode::getName ( ) const

Alternate convenience function for getName().

May require an extra string copy.

Returns:: the node name

Definition at line 279 of file vfsnode.cpp.

void VFSNode::setName ( const VString & name )

Specifies the name of the node, without changing the parent path nor actually renaming anything on disk (as one of the renameXXX() methods would do).

Parameters:

name	the name of the file or directory

Definition at line 285 of file vfsnode.cpp.

References VString::chars(), getParentPath(), and setPath().

void VFSNode::getParentPath ( VString & parentPath ) const

Gets the path of the node's parent.

Parameters:

parentPath the string to set

Definition at line 293 of file vfsnode.cpp.

References VString::chars(), VString::copyFromBuffer(), and VString::lastIndexOf().

void VFSNode::getParentNode ( VFSNode & parent ) const

Gets a VFSNode of the node's parent.

Parameters:

parent the object to set

Definition at line 297 of file vfsnode.cpp.

References getParentPath(), and setPath().

void VFSNode::getChildPath	(	const VString &	childName,
		VString &	childPath
	)		const

Gets the path of a child of the node (the node must be a directory).

Parameters:

childName	the name of the child file or directory
childPath	the string to set

Definition at line 304 of file vfsnode.cpp.

References VString::chars().

void VFSNode::getChildNode	(	const VString &	childName,
		VFSNode &	child
	)		const

Gets the node of a child of the node (the node must be a directory).

Parameters:

childName	the name of the child file or directory
child	the node to set

Definition at line 308 of file vfsnode.cpp.

References getChildPath(), and setPath().

bool VFSNode::rm ( ) const

Deletes the node; if it is a directory its contents are deleted first.

Returns:: true if the deletion was successful; false if the node itself, or any contained nodes could not be deleted

Definition at line 335 of file vfsnode.cpp.

References exists(), isDirectory(), and rmDirContents().

bool VFSNode::rmDirContents ( ) const

Deletes the contents of the directory node (the node must be a directory).

Returns:: true if the deletion was successful; false if one or more contained nodes could not be deleted

Definition at line 364 of file vfsnode.cpp.

References list().

bool VFSNode::exists ( ) const

Returns true if the node (file or directory) currently exists.

Returns:: true if the node exists, false if not

Definition at line 445 of file vfsnode.cpp.

VInstant VFSNode::creationDate ( ) const

Returns the node's creation date.

Returns:: the node's creation date

Definition at line 464 of file vfsnode.cpp.

References VString::chars(), and VInstant::instantFromRawValue().

VInstant VFSNode::modificationDate ( ) const

Returns the node's modification date.

Returns:: the node's modification date

Definition at line 474 of file vfsnode.cpp.

References VString::chars(), and VInstant::instantFromRawValue().

VFSize VFSNode::size ( ) const

Returns the file node's size (must be a file node).

Throws a VException if the node is not a file or does not exist.

Returns:: the file size

Definition at line 484 of file vfsnode.cpp.

References VString::chars().

bool VFSNode::isFile ( ) const

Returns true if the node is a file.

Returns:: true if the node is a file, false if not

Definition at line 494 of file vfsnode.cpp.

bool VFSNode::isDirectory ( ) const

Returns true if the node is a directory.

Returns:: true if the node is a directory, false if not

Definition at line 501 of file vfsnode.cpp.

void VFSNode::renameToPath ( const VString & newPath ) const

Renames the node by specifying its new path; this could include changing its directory location.

This function does NOT update this VFSNode's path property (it continues to describe the node at the old path, even though it is no longer present if the rename succeeded).

Parameters:

newPath the new path to rename to

Definition at line 377 of file vfsnode.cpp.

void VFSNode::renameToName ( const VString & newName ) const

Renames the node by specifying its new name; this means just changing the leaf file or dir name, without changing its containing path.

That is, this function does not move the file or dir to another directory. This function does NOT update this VFSNode's path property (it continues to describe the node at the old path, even though it is not present if the rename succeeded).

Parameters:

newName the new name to rename to

Definition at line 381 of file vfsnode.cpp.

void VFSNode::renameToName	(	const VString &	newName,
		VFSNode &	nodeToUpdate
	)		const

Renames the node by specifying its new name; this means just changing the leaf file or dir name, without changing its containing path.

That is, this function does not move the file or dir to another directory. This function does NOT update this VFSNode's path property (it continues to describe the node at the old path, even though it is not present if the rename succeeded). However, it updates the supplied nodeToUpdate, which could be this node if you pass *this for the parameter.

Parameters:

newName	the new name to rename to
nodeToUpdate	a VFSNode whose path to rename

Definition at line 386 of file vfsnode.cpp.

References getChildPath(), getParentNode(), and setPath().

void VFSNode::renameToNode ( const VFSNode & newNode ) const

Renames the node by specifying a node whose path to use; this could include changing its directory location.

This function does NOT update this VFSNode's path property (it continues to describe the node at the old path, even though it is no longer present if the rename succeeded).

Parameters:

newNode a node whose path is the path to rename the node to

Definition at line 398 of file vfsnode.cpp.

References getPath().

void VFSNode::list ( VStringVector & children ) const

Returns a vector of strings containing the names of the node's children (the node must be a directory).

Parameters:

children the vector of strings to be filled in

Definition at line 405 of file vfsnode.cpp.

void VFSNode::list ( VFSNodeVector & children ) const

Returns a vector of nodes, one for each of the node's children (the node must be a directory).

Parameters:

children the vector of node objects to be filled in

Definition at line 410 of file vfsnode.cpp.

void VFSNode::iterate ( VDirectoryIterationCallback & callback ) const

Iterates over the directory's nodes, calling the supplied callback object for each one (the "." and ".." are omitted).

The callback can process each node as needed, and can halt the iteration at any time.

Parameters:

callback the object that will be called for each node iterated over

Definition at line 415 of file vfsnode.cpp.

bool VFSNode::find	(	const VString &	name,
		VFSNode &	node
	)		const

Iterates over the directory until it finds the specified child node using a case-insensitive match on the node names.

This is useful if you need to open a file but don't know what case it is in due to cross-platform naming issues. If you know the case, you should just open the file rather than trying to find it first before opening.

Parameters:

name	the name to match (matching is not case-sensitive)
node	the node to be returned indicating the actual name in its particular case; node is unmodified if there was no match

Returns:: true if a match was found and node contains the match

Definition at line 419 of file vfsnode.cpp.

void VFSNode::readAll	(	VString &	s,
		bool	includeLineEndings = `true`
	)

This convenience function does the following in a single call:

Open the file read-only.
Create a text input stream.
Read the entire file as text into the supplied string.
Close the file. Note that the default value for includeLineEndings is the opposite of VTextIOStream::readLine(), because here you probably want the whole file with lines separated, whereas when you read one line you probably don't want the end of line characters.
Parameters:

s a VString to append to

includeLineEndings true if you want the line ending character(s) to be included in the string that is returned

Exceptions:

VException if the file cannot be opened or read

Definition at line 431 of file vfsnode.cpp.

References VBufferedFileStream::openReadOnly(), and VTextIOStream::readAll().

void VFSNode::readAll ( VStringVector & lines )

This convenience function is like the other readAll, but it returns the file's contents as a vector of strings rather than a single giant string.

The lines do not have line ending characters at the end.

Parameters:

lines a vector of strings; lines are appended to this vector

Exceptions:

VException if the file cannot be opened or read

Definition at line 438 of file vfsnode.cpp.

References VBufferedFileStream::openReadOnly(), and VTextIOStream::readAll().

VString VFSNode::readTextFile	(	const VString &	path,
		bool	includeLineEndings = `true`
	)		`[static]`

The static version of readAll(VString&), for more concise calling code, at the expense of a likely string copy to return by value.

Parameters:

path	the path of the VFSNode from which to read
includeLineEndings	true if you want the line ending character(s) to be included in the string that is returned

Exceptions:

VException if the file cannot be opened or read

Definition at line 451 of file vfsnode.cpp.

References readAll().

void VFSNode::readTextFile	(	const VString &	path,
		VStringVector &	lines
	)		`[static]`

The static version of readAll(VStringVector&), for more concise calling code.

Parameters:

path	the path of the VFSNode from which to read
lines	a vector of strings; lines are appended to this vector

Exceptions:

VException if the file cannot be opened or read

Definition at line 459 of file vfsnode.cpp.

References readAll().

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

s	a VString to append to
includeLineEndings	true if you want the line ending character(s) to be included in the string that is returned

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation