Description

Functions for dealing with files.

Definition at line 26 of file VuoFileUtilities.hh.

Classes
class	Archive
	An archive of files. More...

class	File
	A file in either a directory or an archive. More...

Static Public Member Functions
static void	splitPath (string path, string &dir, string &file, string &extension)
	Splits `path` into its directory, file name, and file extension. More...

static void	canonicalizePath (string &path)
	Transforms path to a standard format. More...

static bool	arePathsEqual (string path1, string path2)
	Returns true if the paths refer to the same location. More...

static string	getAbsolutePath (const string &path)
	Returns the absolute path of path (which may be relative or absolute). More...

static string	makeTmpFile (string file, string extension, string directory="/tmp")
	Creates a new temporary file, avoiding any name conflicts with existing files. More...

static string	makeTmpDir (string dir)
	Creates a new temporary directory, avoiding any name conflicts with existing files. More...

static string	makeTmpDirOnSameVolumeAsPath (string path)
	Creates a new temporary directory, avoiding any name conflicts with existing files. More...

static string	getTmpDir (void)
	Returns the path of the default temporary directory. More...

static void	makeDir (string path)
	Creates a new directory (and parent directories if needed), if it doesn't already exist. More...

static string	getVuoFrameworkPath (void)
	Returns the absolute path of Vuo.framework (without a trailing slash), or an empty string if Vuo.framework cannot be located. More...

static string	getVuoRunnerFrameworkPath (void)
	Returns the absolute path of VuoRunner.framework (without a trailing slash), or an empty string if VuoRunner.framework cannot be located. More...

static string	getCompositionLocalModulesPath (const string &compositionPath)
	Returns the path of the composition-local Modules folder for a composition located at compositionPath. More...

static string	getUserModulesPath (void)
	Returns the filesystem path to the user-specific Vuo Modules folder (without a trailing slash). More...

static string	getSystemModulesPath (void)
	Returns the filesystem path to the system-wide Vuo Modules folder (without a trailing slash). More...

static string	getCachePath (void)
	Returns the filesystem path to the folder that Vuo uses to cache data (without a trailing slash). More...

static bool	isInstalledAsModule (const string &path)
	Returns true if path (a source file or compiled module) is located in a Modules folder. More...

static void	preserveOriginalFileName (string &fileContents, string originalFileName)
	Saves originalFileName into fileContents so that, when fileContents is written to some other file path, originalFileName will still be the name that shows up in compile errors/warnings and in the `FILE` macro. More...

static size_t	getFirstInsertionIndex (string s)
	Returns the first index at which content can be inserted into a string that was read from a file. More...

static string	readStdinToString (void)
	Reads from standard input into a string until the end-of-file is reached. More...

static string	readFileToString (string path)
	Reads the whole contents of the file into a string. More...

static void	writeRawDataToFile (const char *data, size_t numBytes, string file)
	Writes the array of bytes to the file. More...

static void	writeStringToFile (string s, string file)
	Writes the string to the file. More...

static void	writeStringToFileSafely (string s, string path)
	Saves to file using the standard Unix procedure (write to temporary file, then rename). More...

static bool	fileExists (string path)
	Returns true if the file exists. More...

static bool	dirExists (string path)
	Returns true if `path` exists and is a directory. More...

static bool	isSymlink (string path)
	Returns true if `path` exists and is a symlink. More...

static bool	fileIsReadable (string path)
	Returns true if the file or directory is readable. More...

static bool	fileContainsReadableData (string path)
	Returns true if the file exists, can be opened, and has a size of more than 0 bytes. More...

static void	createFile (string path)
	Creates the file if it does not exist already; otherwise, has no effect on the file. More...

static void	deleteFile (string path)
	Deletes the file or directory if it exists and, if a directory, is empty; otherwise, has no effect. More...

static void	deleteDir (string path)
	Deletes the directory and its contents if the directory exists; otherwise, has no effect. More...

static void	moveFile (string fromPath, string toPath)
	Moves the file from fromPath to toPath. More...

static void	moveFileToTrash (string filePath)
	Moves the specified file to the user's trash folder. More...

static void	copyFile (string fromPath, string toPath, bool preserveMetadata=false)
	Copies the file from fromPath to toPath. More...

static void	copyDirectory (string fromPath, string toPath)
	Recursively copies the provided file or directory from `fromPath` to `toPath`. More...

static unsigned long	getFileLastModifiedInSeconds (string path)
	Returns the time that the file was last modified, in seconds from a reference date. More...

static unsigned long	getSecondsSinceFileLastAccessed (string path)
	Returns the time since the file was last accessed, in seconds. More...

static set< File * >	findAllFilesInDirectory (string dirPath, set< string > archiveExtensions=set< string >(), bool shouldSearchRecursively=false)
	Searches a directory for files. More...

static set< File * >	findFilesInDirectory (string dirPath, set< string > extensions, set< string > archiveExtensions=set< string >())
	Searches a directory for files with a given extension. More...

static set< File * >	findAllFilesInArchive (string archivePath)
	Recursively searches an archive for files. More...

static set< File * >	findFilesInArchive (string archivePath, string dirPath, set< string > extensions)
	Recursively searches an archive for files within a given directory and with a given extension. More...

static string	getArchiveFileContentsAsString (string archivePath, string filePath)
	Returns the contents of a file within an archive. More...

static size_t	getAvailableSpaceOnVolumeContainingPath (string path)
	Returns the available space, in bytes, on the volume containing the specified path. More...

static void	focusProcess (pid_t pid, bool force=false)
	Attempts to focus the specified `pid` (i.e., bring all its windows to the front and make one of them key). More...

static bool	isCompositionExtension (string extension)
	Returns true if the given extension (without leading dot) is a Vuo composition file. More...

static set< string >	getCSourceExtensions (void)
	Returns C/C++/Objective-C/Objective-C++ source file extensions (without a leading dot). More...

static bool	isCSourceExtension (string extension)
	Returns true if the given extension (without leading dot) is a C/C++/Objective-C/Objective-C++ source file. More...

static bool	isIsfSourceExtension (string extension)
	Returns true if the given extension (without leading dot) is an ISF source file. More...

Member Function Documentation

◆ arePathsEqual()

bool VuoFileUtilities::arePathsEqual	(	string	path1,
		string	path2
	)

static

Returns true if the paths refer to the same location.

This handles different formats for the same path (by comparing the canonicalized paths). It does not follow symlinks.

Definition at line 87 of file VuoFileUtilities.cc.

◆ canonicalizePath()

void VuoFileUtilities::canonicalizePath ( string & path )

static

Transforms path to a standard format.

The returned path is absolute if path is absolute, relative if path is relative.

Definition at line 68 of file VuoFileUtilities.cc.

◆ copyDirectory()

void VuoFileUtilities::copyDirectory	(	string	fromPath,
		string	toPath
	)

static

Recursively copies the provided file or directory from fromPath to toPath.

Preserves symlinks (rather than copying their target files).

Exceptions

std::runtime_error The file couldn't be copied.

Definition at line 718 of file VuoFileUtilities.cc.

◆ copyFile()

void VuoFileUtilities::copyFile	(	string	fromPath,
		string	toPath,
		bool	preserveMetadata = `false`
	)

static

Copies the file from fromPath to toPath.

If preserveMetadata is true and toPath already exists, the file's inode and stat info is preserved, thus so are any locks on the file.

Exceptions

std::runtime_error The file couldn't be copied.

Definition at line 689 of file VuoFileUtilities.cc.

◆ createFile()

void VuoFileUtilities::createFile ( string path )

static

Creates the file if it does not exist already; otherwise, has no effect on the file.

Definition at line 608 of file VuoFileUtilities.cc.

◆ deleteDir()

void VuoFileUtilities::deleteDir ( string path )

static

Deletes the directory and its contents if the directory exists; otherwise, has no effect.

Definition at line 627 of file VuoFileUtilities.cc.

◆ deleteFile()

void VuoFileUtilities::deleteFile ( string path )

static

Deletes the file or directory if it exists and, if a directory, is empty; otherwise, has no effect.

Definition at line 617 of file VuoFileUtilities.cc.

◆ dirExists()

bool VuoFileUtilities::dirExists ( string path )

static

Returns true if path exists and is a directory.

If path is a symlink or macOS Alias, it is dereferenced.

Definition at line 539 of file VuoFileUtilities.cc.

◆ fileContainsReadableData()

bool VuoFileUtilities::fileContainsReadableData ( string path )

static

Returns true if the file exists, can be opened, and has a size of more than 0 bytes.

If path is a symlink or macOS Alias, it is dereferenced.

Definition at line 579 of file VuoFileUtilities.cc.

◆ fileExists()

bool VuoFileUtilities::fileExists ( string path )

static

Returns true if the file exists.

If path is a symlink or macOS Alias, it is dereferenced.

Definition at line 525 of file VuoFileUtilities.cc.

◆ fileIsReadable()

bool VuoFileUtilities::fileIsReadable ( string path )

static

Returns true if the file or directory is readable.

If path is a symlink or macOS Alias, it is dereferenced.

Definition at line 565 of file VuoFileUtilities.cc.

◆ findAllFilesInArchive()

set< VuoFileUtilities::File * > VuoFileUtilities::findAllFilesInArchive ( string archivePath )

static

Recursively searches an archive for files.

Parameters

archivePath The archive to search in.

Returns: All files found.

Definition at line 889 of file VuoFileUtilities.cc.

◆ findAllFilesInDirectory()

set< VuoFileUtilities::File * > VuoFileUtilities::findAllFilesInDirectory	(	string	dirPath,
		set< string >	archiveExtensions = `set<string>()`,
		bool	shouldSearchRecursively = `false`
	)

static

Searches a directory for files.

If dirPath is a symlink or macOS Alias, it is dereferenced.

Parameters

dirPath	The directory to search in. Only the top level is searched.
archiveExtensions	The file extensions for archives to search in. Any archive with one of these extensions found in the top level of the directory will be searched recursively.
shouldSearchRecursively	If true, the directory will be searched searched recursively.

Returns: All files found.

Exceptions

std::runtime_error The directory couldn't be read.

Definition at line 784 of file VuoFileUtilities.cc.

◆ findFilesInArchive()

set< VuoFileUtilities::File * > VuoFileUtilities::findFilesInArchive	(	string	archivePath,
		string	dirPath,
		set< string >	extensions
	)

static

Recursively searches an archive for files within a given directory and with a given extension.

Parameters

archivePath	The archive to search in.
dirPath	The directory to search in within the archive. The path should be relative to the archive's root. The path should omit the trailing file separator (e.g. "examples" not "examples/").
extensions	The file extensions to search for, without the '.' character (e.g. "bc" not ".bc").

Returns: All files found.

Definition at line 930 of file VuoFileUtilities.cc.

◆ findFilesInDirectory()

set< VuoFileUtilities::File * > VuoFileUtilities::findFilesInDirectory	(	string	dirPath,
		set< string >	extensions,
		set< string >	archiveExtensions = `set<string>()`
	)

static

Searches a directory for files with a given extension.

Parameters

dirPath	The directory to search in. Only the top level is searched.
archiveExtensions	The file extensions for archives to search in. Any archive with one of these extensions found in the top level of the directory will be searched recursively.
extensions	The file extensions to search for, without the '.' character (e.g. "bc" not ".bc").

Returns: All files found.

Definition at line 862 of file VuoFileUtilities.cc.

◆ focusProcess()

void VuoFileUtilities::focusProcess	(	pid_t	pid,
		bool	force = `false`
	)

static

Attempts to focus the specified pid (i.e., bring all its windows to the front and make one of them key).

This function may only be called on the main thread.

Definition at line 1264 of file VuoFileUtilities.cc.

◆ getAbsolutePath()

string VuoFileUtilities::getAbsolutePath ( const string & path )

static

Returns the absolute path of path (which may be relative or absolute).

Definition at line 97 of file VuoFileUtilities.cc.

◆ getArchiveFileContentsAsString()

string VuoFileUtilities::getArchiveFileContentsAsString	(	string	archivePath,
		string	filePath
	)

static

Returns the contents of a file within an archive.

If the file doesn't exist, returns an empty string.

Parameters

archivePath	The archive containing the file.
filePath	The file. The path should be relative to the archive's root.

Returns: The file's contents.

Definition at line 966 of file VuoFileUtilities.cc.

◆ getAvailableSpaceOnVolumeContainingPath()

size_t VuoFileUtilities::getAvailableSpaceOnVolumeContainingPath ( string path )

static

Returns the available space, in bytes, on the volume containing the specified path.

path should be an absolute POSIX path. Its last few path components needn't exist.

Exceptions

std::runtime_error

Definition at line 988 of file VuoFileUtilities.cc.

◆ getCachePath()

string VuoFileUtilities::getCachePath ( void )

static

Returns the filesystem path to the folder that Vuo uses to cache data (without a trailing slash).

Definition at line 372 of file VuoFileUtilities.cc.

◆ getCompositionLocalModulesPath()

string VuoFileUtilities::getCompositionLocalModulesPath ( const string & compositionPath )

static

Returns the path of the composition-local Modules folder for a composition located at compositionPath.

(The composition file need not actually exist.)

If the composition is installed as a subcomposition (it's located in a folder called Modules), returns that folder. Otherwise, returns a Modules folder located in the same folder as the composition.

Definition at line 335 of file VuoFileUtilities.cc.

◆ getCSourceExtensions()

set< string > VuoFileUtilities::getCSourceExtensions ( void )

static

Returns C/C++/Objective-C/Objective-C++ source file extensions (without a leading dot).

Definition at line 1280 of file VuoFileUtilities.cc.

◆ getFileLastModifiedInSeconds()

unsigned long VuoFileUtilities::getFileLastModifiedInSeconds ( string path )

static

Returns the time that the file was last modified, in seconds from a reference date.

This is useful for checking which of two files was modified more recently.

Definition at line 750 of file VuoFileUtilities.cc.

◆ getFirstInsertionIndex()

size_t VuoFileUtilities::getFirstInsertionIndex ( string s )

static

Returns the first index at which content can be inserted into a string that was read from a file.

This comes after the Unicode BOM, if present.

Definition at line 410 of file VuoFileUtilities.cc.

◆ getSecondsSinceFileLastAccessed()

unsigned long VuoFileUtilities::getSecondsSinceFileLastAccessed ( string path )

static

Returns the time since the file was last accessed, in seconds.

Definition at line 760 of file VuoFileUtilities.cc.

◆ getSystemModulesPath()

string VuoFileUtilities::getSystemModulesPath ( void )

static

Returns the filesystem path to the system-wide Vuo Modules folder (without a trailing slash).

Definition at line 364 of file VuoFileUtilities.cc.

◆ getTmpDir()

string VuoFileUtilities::getTmpDir ( void )

static

Returns the path of the default temporary directory.

Definition at line 167 of file VuoFileUtilities.cc.

◆ getUserModulesPath()

string VuoFileUtilities::getUserModulesPath ( void )

static

Returns the filesystem path to the user-specific Vuo Modules folder (without a trailing slash).

Definition at line 356 of file VuoFileUtilities.cc.

◆ getVuoFrameworkPath()

string VuoFileUtilities::getVuoFrameworkPath ( void )

static

Returns the absolute path of Vuo.framework (without a trailing slash), or an empty string if Vuo.framework cannot be located.

For a C version accessible from nodes and libraries, see VuoApp_getVuoFrameworkPath.

Definition at line 205 of file VuoFileUtilities.cc.

◆ getVuoRunnerFrameworkPath()

string VuoFileUtilities::getVuoRunnerFrameworkPath ( void )

static

Returns the absolute path of VuoRunner.framework (without a trailing slash), or an empty string if VuoRunner.framework cannot be located.

Definition at line 265 of file VuoFileUtilities.cc.

◆ isCompositionExtension()

bool VuoFileUtilities::isCompositionExtension ( string extension )

static

Returns true if the given extension (without leading dot) is a Vuo composition file.

Definition at line 1272 of file VuoFileUtilities.cc.

◆ isCSourceExtension()

bool VuoFileUtilities::isCSourceExtension ( string extension )

static

Returns true if the given extension (without leading dot) is a C/C++/Objective-C/Objective-C++ source file.

Definition at line 1297 of file VuoFileUtilities.cc.

◆ isInstalledAsModule()

bool VuoFileUtilities::isInstalledAsModule ( const string & path )

static

Returns true if path (a source file or compiled module) is located in a Modules folder.

Definition at line 380 of file VuoFileUtilities.cc.

◆ isIsfSourceExtension()

bool VuoFileUtilities::isIsfSourceExtension ( string extension )

static

Returns true if the given extension (without leading dot) is an ISF source file.

Definition at line 1306 of file VuoFileUtilities.cc.

◆ isSymlink()

bool VuoFileUtilities::isSymlink ( string path )

static

Returns true if path exists and is a symlink.

Definition at line 553 of file VuoFileUtilities.cc.

◆ makeDir()

void VuoFileUtilities::makeDir ( string path )

static

Creates a new directory (and parent directories if needed), if it doesn't already exist.

Exceptions

std::runtime_error The directory couldn't be created.

Definition at line 177 of file VuoFileUtilities.cc.

◆ makeTmpDir()

string VuoFileUtilities::makeTmpDir ( string dir )

static

Creates a new temporary directory, avoiding any name conflicts with existing files.

Returns the path of the directory (without a trailing slash).

Definition at line 140 of file VuoFileUtilities.cc.

◆ makeTmpDirOnSameVolumeAsPath()

string VuoFileUtilities::makeTmpDirOnSameVolumeAsPath ( string path )

static

Creates a new temporary directory, avoiding any name conflicts with existing files.

The temporary directory will be on the same filesystem as the specified path, to facilitate using rename() (for example). onSameVolumeAsPath needn't already exist.

Returns the path of the directory (without a trailing slash).

Definition at line 159 of file VuoFileUtilities.cc.

◆ makeTmpFile()

string VuoFileUtilities::makeTmpFile	(	string	file,
		string	extension,
		string	directory = `"/tmp"`
	)

static

Creates a new temporary file, avoiding any name conflicts with existing files.

Creates the file in the specified directory if one is provided, or in "/tmp" otherwise.

Returns the path of the file.

Definition at line 120 of file VuoFileUtilities.cc.

◆ moveFile()

void VuoFileUtilities::moveFile	(	string	fromPath,
		string	toPath
	)

static

Moves the file from fromPath to toPath.

Exceptions

std::runtime_error The file couldn't be moved.

Definition at line 664 of file VuoFileUtilities.cc.

◆ moveFileToTrash()

void VuoFileUtilities::moveFileToTrash ( string filePath )

static

Moves the specified file to the user's trash folder.

Exceptions

std::runtime_error The file couldn't be moved.

Definition at line 676 of file VuoFileUtilities.cc.

◆ preserveOriginalFileName()

void VuoFileUtilities::preserveOriginalFileName	(	string &	fileContents,
		string	originalFileName
	)

static

Saves originalFileName into fileContents so that, when fileContents is written to some other file path, originalFileName will still be the name that shows up in compile errors/warnings and in the FILE macro.

This function inserts a preprocessor directive at the beginning of fileContents. Any modifications to fileContents after this function is called should keep the preprocessor directive on the first line.

Definition at line 401 of file VuoFileUtilities.cc.

◆ readFileToString()

string VuoFileUtilities::readFileToString ( string path )

static

Reads the whole contents of the file into a string.

Exceptions

std::runtime_error The file couldn't be read.

Definition at line 449 of file VuoFileUtilities.cc.

◆ readStdinToString()

string VuoFileUtilities::readStdinToString ( void )

static

Reads from standard input into a string until the end-of-file is reached.

Definition at line 432 of file VuoFileUtilities.cc.

◆ splitPath()

void VuoFileUtilities::splitPath	(	string	path,
		string &	dir,
		string &	file,
		string &	extension
	)

static

Splits path into its directory, file name, and file extension.

Parameters

[in]	path	The path to split.
[out]	dir	The directory in `path`, if any. Ends with a file separator (e.g. '/') if there was one in `path`.
[out]	file	The file name in `path`, if any.
[out]	extension	The file extension in `path`, if any. Does not include the '.' character.

See also: VuoUrl_getFileParts

Definition at line 32 of file VuoFileUtilities.cc.

◆ writeRawDataToFile()

void VuoFileUtilities::writeRawDataToFile	(	const char *	data,
		size_t	numBytes,
		string	file
	)

static

Writes the array of bytes to the file.

If the file already exists, it gets overwritten.

Exceptions

std::runtime_error The file couldn't be written.

Definition at line 473 of file VuoFileUtilities.cc.

◆ writeStringToFile()

void VuoFileUtilities::writeStringToFile	(	string	s,
		string	file
	)

static

Writes the string to the file.

If the file already exists, it gets overwritten.

Exceptions

std::runtime_error The file couldn't be written.

Definition at line 496 of file VuoFileUtilities.cc.

◆ writeStringToFileSafely()

void VuoFileUtilities::writeStringToFileSafely	(	string	s,
		string	path
	)

static

Saves to file using the standard Unix procedure (write to temporary file, then rename).

This prevents the destination file from becoming corrupted if the write fails.

If the file already exists, it gets overwritten.

Exceptions

std::runtime_error The file couldn't be written.

Definition at line 509 of file VuoFileUtilities.cc.

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

base/VuoFileUtilities.hh
base/VuoFileUtilities.cc

Description

Classes

Static Public Member Functions

Member Function Documentation

◆ arePathsEqual()

◆ canonicalizePath()

◆ copyDirectory()

◆ copyFile()

◆ createFile()

◆ deleteDir()

◆ deleteFile()

◆ dirExists()

◆ fileContainsReadableData()

◆ fileExists()

◆ fileIsReadable()

◆ findAllFilesInArchive()

◆ findAllFilesInDirectory()

◆ findFilesInArchive()

◆ findFilesInDirectory()

◆ focusProcess()

◆ getAbsolutePath()

◆ getArchiveFileContentsAsString()

◆ getAvailableSpaceOnVolumeContainingPath()

◆ getCachePath()

◆ getCompositionLocalModulesPath()

◆ getCSourceExtensions()

◆ getFileLastModifiedInSeconds()

◆ getFirstInsertionIndex()

◆ getSecondsSinceFileLastAccessed()

◆ getSystemModulesPath()

◆ getTmpDir()

◆ getUserModulesPath()

◆ getVuoFrameworkPath()

◆ getVuoRunnerFrameworkPath()

◆ isCompositionExtension()

◆ isCSourceExtension()

◆ isInstalledAsModule()

◆ isIsfSourceExtension()

◆ isSymlink()

◆ makeDir()

◆ makeTmpDir()

◆ makeTmpDirOnSameVolumeAsPath()

◆ makeTmpFile()

◆ moveFile()

◆ moveFileToTrash()

◆ preserveOriginalFileName()

◆ readFileToString()

◆ readStdinToString()

◆ splitPath()

◆ writeRawDataToFile()

◆ writeStringToFile()

◆ writeStringToFileSafely()