the FsUtil namespace contains all the objects in the FsUtil module More...

Classes
class	PathHandler
	generic path handler implementing functionality common for both platforms More...

class	PosixPathHandler
	path handler implementing POSIX specific functionality More...

class	TmpDir
	Class implementing a user friendly temporary directory creation. More...

class	TmpFile
	Class implementing a user friendly temporary file creation; the file is removed in the destructor. More...

class	WinPathHandler
	path handler implementing Windows specific functionality More...

Functions
string	basename_ext (string path, *string extension)
	this function returns the segment of given path after the last delimiter

string	copy_dir_structure (string source, string destination, *int depth)
	Copies a structure of directories, files are ignored.

string	copy_file (string source, string destination, bool follow_symlinks=False, bool overwrite=False)
	Copies a file (regular or symlink) from source to destination.

	copy_file_obj (File source, File destination, bool close=False, int buf_size=DefaultBufferSize)
	Copies a file object data from source to destination.

string	copy_path (string source, string destination, bool follow_symlinks=False, bool overwrite=False, bool fail_immediately=True, *int depth)
	Universal copy function.

string	copy_tree (string source, string destination, bool follow_symlinks=False, bool overwrite=False, bool fail_immediately=True)
	Copies a directory tree from source to destination.

string	copy_tree_internal (string source, string destination, bool follow_symlinks=False, bool overwrite=False, bool merge=False, bool fail_immediately=True, *int depth)
	Private internal copy tree function implementation.

string	join_paths ()
	Returns the path resulting from joining the given paths.

string	join_paths (list< string > paths)
	Returns the path resulting from joining the given paths.

string	join_paths (string path1, list< auto > paths)
	Returns the path resulting from joining the given paths.

string	make_tmp_dir (string prefix, string suffix, *string path)
	Creates a unique temporary directory and returns its absolute path.

hash< TmpFileHash >	make_tmp_file (string prefix, string suffix, *string path)
	Creates and opens a unique temporary file and returns its absolute path as well as its File object.

string	merge_path (string source, string destination, bool follow_symlinks=False, bool overwrite=False, bool fail_immediately=True, *int depth)
	Universal merge function.

string	merge_tree (string source, string destination, bool follow_symlinks=False, bool overwrite=False, bool fail_immediately=True, *int depth)
	Merges a copy of the source directory tree to the destination directory tree.

string	move_path (string source, string destination, bool overwrite=False)
	Moves a path from source to destination.

bool	path_exists (string path, bool follow_symlinks=False)
	Check whether the given path exists or not.

	remove_file (string path)
	Removes a regular file or symlink specified by path.

	remove_path (string path)
	Universal remove function.

	remove_tree (string path, bool fail_immediately=True)
	Removes the filesystem tree specified by path.

bool	same_file (string path1, string path2, bool follow_symlinks=True, bool ignore_errors=True)
	Checks whether two paths point to the same file/directory or not.

bool	same_file_stat (hash< StatInfo > stat1, hash< StatInfo > stat2, bool ignore_errors=True)
	Checks whether two stat hashes point to the same file or not.

Variables
const	DefaultBufferSize = 16 * 1024
	Default file block buffer size.

Detailed Description

the FsUtil namespace contains all the objects in the FsUtil module

Function Documentation

◆ basename_ext()

string FsUtil::basename_ext	(	string	path,
		*string	extension
	)

this function returns the segment of given path after the last delimiter

Parameters

path	the path to be processed
extension	the extension to cut from basename

Returns: everything after the last delimiter except for the extension if present

Exceptions

EXTENSION-NOT-FOUND if the extension is not a part of the path

Delimiters for the current platform are used.

◆ copy_dir_structure()

string FsUtil::copy_dir_structure	(	string	source,
		string	destination,
		*int	depth
	)

Copies a structure of directories, files are ignored.

Parameters

source	path to be copied (must be a directory or a symlink pointing to one if follow_symlinks is set)
destination	path where the copy should be created (must be a directory or must not exist)
depth	determines how many levels of subdirectories should be copied

Exceptions

DIR-STAT-ERROR	If stat call for the source path fails.
PATH-EXISTS-ERROR	If destination path exists
NOT-DIRECTORY-ERROR	If source is not a directory

Source must be a directory, destination must not exist.

Mode (permissions) bits are preserved but UID/GID, access time and modification time are not. If the whole tree (to the specified depth) is copied correctly, the function returns the path to the new copy.

◆ copy_file()

string FsUtil::copy_file	(	string	source,
		string	destination,
		bool	follow_symlinks = `False`,
		bool	overwrite = `False`
	)

Copies a file (regular or symlink) from source to destination.

Parameters

source	path to the file to be copied
destination	path where the copy should be created
follow_symlinks	flag indicating whether symlink should be followed in source (False by default)
overwrite	flag indicating whether destination should be overwritten if exists (False by default)

Exceptions

SAME-FILE-ERROR	If both paths point to the same file.
FILE-STAT-ERROR	If stat call for the source path fails.
PATH-EXISTS-ERROR	If destination path exists and overwrite flag is False
UNSUPPORTED-TYPE-ERROR	If a given file is not a regular path or a symbolic link.

Destination can be a directory. If that's the case, this function will attempt to create a copy of source using the same filename in the destination directory. Symlinks in destination are always followed (even dangling links). Mode (permissions) bits are preserved but UID/GID, access time and modification time are not. If the file is copied correctly, the function returns the path to the new copy.

◆ copy_file_obj()

FsUtil::copy_file_obj	(	File	source,
		File	destination,
		bool	close = `False`,
		int	buf_size = `DefaultBufferSize`
	)

Copies a file object data from source to destination.

Parameters

source	an open file object to be copied from
destination	an open file object to be copied to
close	flag indicating whether the file objects should be closed afterwards
buf_size	size of the buffer used to copy the file

By default this function does not close the file objects after the copy is made. This can be changed using the close parameter.

◆ copy_path()

string FsUtil::copy_path	(	string	source,
		string	destination,
		bool	follow_symlinks = `False`,
		bool	overwrite = `False`,
		bool	fail_immediately = `True`,
		*int	depth
	)

Universal copy function.

Parameters

source	path to be copied
destination	path where the copy should be created
follow_symlinks	flag indicating whether symlink should be followed in source (False by default)
overwrite	flag indicating whether destination should be overwritten if exists (False by default)
fail_immediately	flag indicates if the function is supposed to fail with an exception immediately on the first error instead of accumulating all exceptions (True by default)
depth	determines how many levels of subdirectories and files should be copied

Exceptions

SAME-DIR-ERROR	If both paths point to the same file
DIR-STAT-ERROR	If stat call for the source path fails
PATH-EXISTS-ERROR	If destination path exists and overwrite flag is not set
COPY-TREE-ERROR	If something goes wrong in the recursive calls. In such case the rest of the tree is copied anyway and this exception's description contains a list of exceptions thrown in the recursive calls unless fail_immediately flag is True

This wrapper function exists for convenience. Source can be a regular file, symlink or a directory, the respective functions for copying files/links or directories will be called. Destination can either be a path that doesn't exist on the filesystem yet (and then it will be created as a copy of source) or it can be an existing path if overwrite flag is set (and then the original contents will be replaced by a copy of source). Mode (permissions) bits are preserved but UID/GID, access time and modification time are not. If the source is copied correctly, the function returns the path to the new copy.

◆ copy_tree()

string FsUtil::copy_tree	(	string	source,
		string	destination,
		bool	follow_symlinks = `False`,
		bool	overwrite = `False`,
		bool	fail_immediately = `True`
	)

Copies a directory tree from source to destination.

Parameters

source	path to be copied (must be a directory or a symlink pointing to one if follow_symlinks is set)
destination	path where the copy should be created (must not exist, except with overwrite)
follow_symlinks	flag indicating whether symlink should be followed in source (False by default)
overwrite	flag indicating whether destination should be overwritten if exists (False by default)
fail_immediately	flag indicating whether the function is supposed to fail with an exception immediately on the first error instead of accumulating all exceptions (True by default)

Exceptions

SAME-DIR-ERROR	If both paths point to the same file
DIR-STAT-ERROR	If stat call for the source path fails
PATH-EXISTS-ERROR	If destination path exists and overwrite flag is not set
COPY-TREE-ERROR	If something goes wrong in the recursive calls. In such case the rest of the tree is copied anyway and this exception's description contains a list of exceptions thrown in the recursive calls unless fail_immediately flag is True

Source must be a directory (or a symlink pointing to a directory if follow_symlinks is True). Destination must not exist unless the function is called with the overwrite flag. Mode (permissions) bits are preserved but UID/GID, access time and modification time are not. As mentioned in description of COPY-TREE-ERROR exception, if only some parts of the tree can't be copied (e.g. due to permissions) and if fail_immediately is False, the tree is partially copied anyway and COPY-TREE-ERROR is thrown and describes what exactly went wrong for each error. If the whole tree is copied correctly, the function returns the path to the new copy.

◆ copy_tree_internal()

string FsUtil::copy_tree_internal	(	string	source,
		string	destination,
		bool	follow_symlinks = `False`,
		bool	overwrite = `False`,
		bool	merge = `False`,
		bool	fail_immediately = `True`,
		*int	depth
	)

Private internal copy tree function implementation.

Parameters

source	path to be copied (must be a directory or a symlink pointing to one if follow_symlinks is set)
destination	path where the copy should be created (must not exist, except with overwrite)
follow_symlinks	flag indicating whether symlink should be followed in source (False by default)
overwrite	flag indicating whether destination should be overwritten if exists (False by default)
merge	flag indicating whether source should be merged into destination if the latter exists (False by default)
fail_immediately	flag indicating whether the function is supposed to fail with an exception immediately on the first error instead of accumulating all exceptions (True by default)
depth	determines how many levels of subdirectories and files should be copied

Exceptions

SAME-DIR-ERROR	If both paths point to the same file.
DIR-STAT-ERROR	If stat call for the source path fails.
PATH-EXISTS-ERROR	If destination path exists and overwrite flag is not set.
COPY-TREE-ERROR	If something goes wrong in the recursive calls. In such case the rest of the tree is copied anyway and this exception's description contains a list of exceptions thrown in the recursive calls unless fail_immediately flag is True.

This is an internal implementation only and is not intended to be called from outside of FsUtil module. Source must be a directory (or a symlink pointing to a directory if follow_symlinks is True). Destination must not exist unless the function is called with the overwrite or the merge flag. The difference between them is that with overwrite (and merge=False) the destination is removed first and then the source is copied (so the result contains just a copy of source) while with merge the original contents of destination is kept and the source is copied into it (so the result is a merge between source and the original destination). If both overwrite and merge are set to True, then the original destination is not removed but if there are files with the same (sub)paths somewhere in the source and destination trees, the file from source tree replaces the original file in the destination tree. Mode (permissions) bits are preserved but UID/GID, access time and modification time are not. As mentioned in description of COPY-TREE-ERROR exception, if only some parts of the tree can't be copied (e.g. due to permissions) and if fail_immediately is False, the tree is partially copied anyway and COPY-TREE-ERROR is thrown and describes what exactly went wrong for each error. If the whole tree is copied correctly, the function returns the path to the new copy.

◆ join_paths() [1/3]

string FsUtil::join_paths ( )

Returns the path resulting from joining the given paths.

Parameters

path1	the first part of the path
...	the remaining parts of the path

Returns: all paths joined into one valid path (i.e. delimiters are added/removed as needed) except for cases when one of the paths (in the list) is an absolute path or if each path is on different drive (Windows only) - in such cases that path is considered a new start of the resulting path. The resulting path is not normalized (i.e. "/path/to/../../file.txt" is a correct result of join("/path/to", "../../file.txt");). Since the second parameter is a softlist, this variant also works for joining two string paths.

◆ join_paths() [2/3]

string FsUtil::join_paths ( list< string > paths )

Returns the path resulting from joining the given paths.

Parameters

paths the parts of the path to be joined into one

Returns: all paths joined into one valid path (i.e. delimiters are added/removed as needed) except for cases when one of the paths is an absolute path or if each path is on different drive (Windows only) - in such cases that path is considered a new start of the resulting path. The resulting path is not normalized (i.e. "/path/to/../../file.txt" is a correct result of join("/path/to", "../../file.txt");).

Exceptions

MISSING-PARAMETER-ERROR if the list is empty

◆ join_paths() [3/3]

string FsUtil::join_paths	(	string	path1,
		list< auto >	paths
	)

Returns the path resulting from joining the given paths.

Parameters

path1	the first part of the path
paths	the other parts of the path

Returns: all paths joined into one valid path (i.e. delimiters are added/removed as needed) except for cases when one of the paths (in the list) is an absolute path or if each path is on different drive (Windows only) - in such cases that path is considered a new start of the resulting path. The resulting path is not normalized (i.e. "/path/to/../../file.txt" is a correct result of join("/path/to", "../../file.txt");). Since the second parameter is a softlist, this variant also works for joining two string paths.

◆ make_tmp_dir()

string FsUtil::make_tmp_dir	(	*string	prefix,
		*string	suffix,
		*string	path
	)

Creates a unique temporary directory and returns its absolute path.

Parameters

prefix	prefix to be used in the newly created directory name
suffix	suffix to be used in the newly created directory name
path	path to a dir in which the caller wants to create the new directory; if not provided, standard temp location will be used

Returns: absolute path to the newly created directory

Exceptions

DIR-WRITE-ERROR The directory couldn't be created.

The directory is created in a secure way and is readable and writable only by the current user. The caller is responsible for removing the temporary directory once it's needed no more.

◆ make_tmp_file()

hash< TmpFileHash > FsUtil::make_tmp_file	(	*string	prefix,
		*string	suffix,
		*string	path
	)

Creates and opens a unique temporary file and returns its absolute path as well as its File object.

Parameters

prefix	prefix to be used in the newly created file name
suffix	suffix to be used in the newly created file name
path	path to a dir in which the caller wants to create the new file; if not provided, standard temp location will be used

Returns: hash<TmpFileHash> with absolute path to the newly created file and its File object (keys "path" and "file" respectively)

Exceptions

FILE-WRITE-ERROR The file couldn't be created.

The file is created in a secure way and is readable and writable only by the current user. The caller is responsible for removing the temporary file once it's needed no more.

◆ merge_path()

string FsUtil::merge_path	(	string	source,
		string	destination,
		bool	follow_symlinks = `False`,
		bool	overwrite = `False`,
		bool	fail_immediately = `True`,
		*int	depth
	)

Universal merge function.

Parameters

source	path to be copied
destination	path the copy should be merged into
follow_symlinks	flag indicating whether symlink should be followed in source (False by default)
overwrite	flag indicating whether destination should be overwritten if exists (False by default)
fail_immediately	flag indicating whether the function is supposed to fail with an exception immediately on the first error instead of accumulating all exceptions (True by default)
depth	determines how many levels of subdirectories and files should be copied

This wrapper function exists for convenience. Source can be a regular file, symlink or a directory, the respective functions for merging files/links or directories will be called. Destination can either be a path that doesn't exist on the filesystem yet (and then it will be created as a copy of source) or it can be an existing path (and then a copy of the source will be merged into the original contents). If overwrite flag is set, then common parts of the subtree will be replaced by the parts from source, otherwise the original contents will be kept there. Mode (permissions) bits are preserved but UID/GID, access time and modification time are not. If the source is copied correctly, the function returns the path to the new copy.

◆ merge_tree()

string FsUtil::merge_tree	(	string	source,
		string	destination,
		bool	follow_symlinks = `False`,
		bool	overwrite = `False`,
		bool	fail_immediately = `True`,
		*int	depth
	)

Merges a copy of the source directory tree to the destination directory tree.

Parameters

source	path to be copied (must be a directory or a symlink pointing to one if follow_symlinks is set)
destination	path the copy should be merged into (must be a directory or must not exist)
follow_symlinks	flag indicating whether symlink should be followed in source (False by default)
fail_immediately	flag indicating whether the function is supposed to fail with an exception immediately on the first error instead of accumulating all exceptions (True by default)
depth	determines how many levels of subdirectories and files should be copied

Exceptions

SAME-DIR-ERROR	If both paths point to the same file.
DIR-STAT-ERROR	If stat call for the source path fails.
COPY-TREE-ERROR	If something goes wrong in the recursive calls. In such case the rest of the tree is copied anyway and this exception's description contains a list of exceptions thrown in the recursive calls unless fail_immediately flag is True.

Source must be a directory (or a symlink pointing to a directory if follow_symlinks is True). Destination must be a directory or must not exist. Mode (permissions) bits are preserved but UID/GID, access time and modification time are not. As mentioned in description of COPY-TREE-ERROR exception, if only some parts of the tree can't be copied and merged (e.g. due to permissions) and if fail_immediately is False, the tree is partially copied anyway and COPY-TREE-ERROR is thrown and describes what exactly went wrong for each error. If the whole tree is copied correctly, the function returns the path to the new copy.

◆ move_path()

string FsUtil::move_path	(	string	source,
		string	destination,
		bool	overwrite = `False`
	)

Moves a path from source to destination.

Parameters

source	path to the file to be copied
destination	path where the copy should be created
overwrite	flag indicating whether destination should be overwritten if exists (False by default)

Exceptions

SAME-PATH-ERROR	If both paths point to the same location
FILE-STAT-ERROR	If stat call for the source path fails
PATH-EXISTS-ERROR	If destination path exists and overwrite flag is False

The Destination can be a directory, in which case, this function will attempt to move the source to the same filename in the destination directory unless overwrite is True. Symlinks in destination are always followed (even dangling links). Mode (permissions) bits are preserved but UID/GID, access time and modification time are not. If the file is copied correctly, the function returns the path to the new location of the path.

◆ path_exists()

bool FsUtil::path_exists	(	string	path,
		bool	follow_symlinks = `False`
	)

Check whether the given path exists or not.

Parameters

path	the path to be checked
follow_symlinks	flag indicating whether target of a symlink should be checked instead

Returns: True if the given path exists, False otherwise. If follow_symlinks is True and path points to a symlink, the link's target is checked instead of the link itself

◆ remove_file()

FsUtil::remove_file ( string path )

Removes a regular file or symlink specified by path.

Parameters

path	path to a filesystem tree root which should be removed

Exceptions

REMOVE-FILE-ERROR If something goes wrong with the removal. The description contains error message.

This function doesn't follow symlinks and it's merely a wrapper aroung unlink() call to ensure consistently named remove/copy/move functions in this module.

◆ remove_path()

FsUtil::remove_path ( string path )

Universal remove function.

Parameters

path	path to be removed

This wrapper function exists for convenience. Path can be a regular file, symlink or a directory, the respective functions for removing files/links or directories will be called.

◆ remove_tree()

FsUtil::remove_tree	(	string	path,
		bool	fail_immediately = `True`
	)

Removes the filesystem tree specified by path.

Parameters

path	path to a filesystem tree root which should be removed
fail_immediately	flag indicates if the function is supposed to fail with an exception immediately on the first error instead of accumulating all exceptions (True by default)

Exceptions

REMOVE-TREE-ERROR If something goes wrong in the recursive calls. In such case the rest of the tree is removed anyway and this exception's description contains a list of exceptions thrown in the recursive calls unless fail_immediately flag is True.

This function will only remove a directory (i.e. path can't point to a regular file, symlink, etc.). This doesn't hold true for the path's contents though of course. That will be removed anyway. This function doesn't follow symlinks. As mentioned in description of REMOVE-TREE-ERROR exception, if only some parts of the tree can't be removed (e.g. due to permissions) and if fail_immediately is False, the tree is partially removed anyway and REMOVE-TREE-ERROR is thrown and describes what exactly went wrong for each error.

◆ same_file()

bool FsUtil::same_file	(	string	path1,
		string	path2,
		bool	follow_symlinks = `True`,
		bool	ignore_errors = `True`
	)

Checks whether two paths point to the same file/directory or not.

Parameters

path1	first path
path2	second path
follow_symlinks	flag indicating whether symlinks should be followed (True by default)
ignore_errors	flag indicating that errors should be ignored (True by default)

Returns: True if the two paths point to the same file or directory, False otherwise.

Exceptions

FILE-STAT-ERROR If stat call for a path fails unless errors are ignored.

Stat is retrieved for each of the paths and device and inode IDs are compared. By default if one of the paths is a symlink pointing to the other, this function will return True but this can be changed using the follow_symlinks parameter. If stat can't be retrieved for a path and ignore_errors is True, then the function returns False. This is because the most common error here is that one of the paths doesn't exist (or both). In that case the paths indeed don't point to the same file.

◆ same_file_stat()

bool FsUtil::same_file_stat	(	*hash< StatInfo >	stat1,
		*hash< StatInfo >	stat2,
		bool	ignore_errors = `True`
	)

Checks whether two stat hashes point to the same file or not.

Parameters

stat1	first stat hash
stat2	second stat hash
ignore_errors	flag indicating that errors should be ignored (True by default)

Returns: True if the two stat hashes point to the same file, False otherwise.

Exceptions

STAT-HASH-MISSING If parameters don't both contain stat hashes.

Device and inode IDs are compared. If a stat hash does not exist and ignore_errors is True, then the function returns False. This is for convenience of the caller who thus may just call a stat function to a path and pass the result to this function without taking care of possible NOTHINGs. In that case the paths can probably be considered not pointing to the same file.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ basename_ext()

◆ copy_dir_structure()

◆ copy_file()

◆ copy_file_obj()

◆ copy_path()

◆ copy_tree()

◆ copy_tree_internal()

◆ join_paths() [1/3]

◆ join_paths() [2/3]

◆ join_paths() [3/3]

◆ make_tmp_dir()

◆ make_tmp_file()

◆ merge_path()

◆ merge_tree()

◆ move_path()

◆ path_exists()

◆ remove_file()

◆ remove_path()

◆ remove_tree()

◆ same_file()

◆ same_file_stat()