Qore FsUtil Module Reference  1.0
FsUtil Namespace Reference

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 - users don't need to care about removing it. More...
 
class  TmpFile
 Class implementing a user friendly temporary file creation - users don't need to care about removing it. 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 More...
 
string copy_dir_structure (string source, string destination, *int depth)
 Copies a structure of directories, files are ignored. More...
 
string copy_file (string source, string destination, bool follow_symlinks=False, bool overwrite=False)
 Copies a file (regular or symlink) from source to destination. More...
 
 copy_file_obj (File source, File destination, bool close=False, int buf_size=4 *1024)
 Copies a file object data from source to destination. More...
 
string copy_path (string source, string destination, bool follow_symlinks=False, bool overwrite=False, bool fail_immediately=True, *int depth)
 Universal copy function. More...
 
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. More...
 
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. More...
 
string join_paths (string path1, softlist< string > paths)
 Returns path resulting from joining the given paths. More...
 
string join_paths (list< string > paths)
 Returns path resulting from joining the given paths. More...
 
string make_tmp_dir (*string prefix, *string suffix, *string path)
 Creates a unique temporary directory and returns its absolute path. More...
 
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. More...
 
string merge_path (string source, string destination, bool follow_symlinks=False, bool overwrite=False, bool fail_immediately=True, *int depth)
 Universal merge function. More...
 
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. More...
 
bool path_exists (string path, bool follow_symlinks=False)
 Check whether the given path exists or not. More...
 
 remove_file (string path)
 Removes a regular file or symlink specified by path. More...
 
 remove_path (string path)
 Universal remove function. More...
 
 remove_tree (string path, bool fail_immediately=True)
 Removes the filesystem tree specified by path. More...
 
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. More...
 
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. More...
 

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
paththe path to be processed
extensionthe extension to cut from basename
Returns
everything after the last delimiter except for the extension if present
Exceptions
EXTENSION-NOT-FOUNDif 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
sourcepath to be copied (must be a directory or a symlink pointing to one if follow_symlinks is set)
destinationpath where the copy should be created (must be a directory or must not exist)
depthdetermines how many levels of subdirectories should be copied
Exceptions
DIR-STAT-ERRORIf stat call for the source path fails.
PATH-EXISTS-ERRORIf destination path exists
NOT-DIRECTORY-ERRORIf 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 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
sourcepath to the file to be copied
destinationpath where the copy should be created
follow_symlinksflag indicating whether symlink should be followed in source (False by default)
overwriteflag indicating whether destination should be overwritten if exists (False by default)
Exceptions
SAME-FILE-ERRORIf both paths point to the same file.
FILE-STAT-ERRORIf stat call for the source path fails.
PATH-EXISTS-ERRORIf destination path exists and overwrite flag is False
UNSUPPORTED-TYPE-ERRORIf 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 path to the new copy.

◆ copy_file_obj()

FsUtil::copy_file_obj ( File  source,
File  destination,
bool  close = False,
int  buf_size = 4 *1024 
)

Copies a file object data from source to destination.

Parameters
sourcean open file object to be copied from
destinationan open file object to be copied to
closeflag indicating whether the file objects should be closed afterwards
buf_sizesize 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
sourcepath to be copied
destinationpath where the copy should be created
follow_symlinksflag indicating whether symlink should be followed in source (False by default)
overwriteflag indicating whether destination should be overwritten if exists (False by default)
depthdetermines 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 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 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
sourcepath to be copied (must be a directory or a symlink pointing to one if follow_symlinks is set)
destinationpath where the copy should be created (must not exist, except with overwrite)
follow_symlinksflag indicating whether symlink should be followed in source (False by default)
overwriteflag indicating whether destination should be overwritten if exists (False by default)
fail_immediatelyflag indicating whether the function is supposed to fail with an exception immediately on the first error instead of accumulating all exceptions (True by default)
depthdetermines how many levels of subdirectories and files should be copied
Exceptions
SAME-DIR-ERRORIf both paths point to the same file.
DIR-STAT-ERRORIf stat call for the source path fails.
PATH-EXISTS-ERRORIf destination path exists and overwrite flag is not set.
COPY-TREE-ERRORIf 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 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
sourcepath to be copied (must be a directory or a symlink pointing to one if follow_symlinks is set)
destinationpath where the copy should be created (must not exist, except with overwrite)
follow_symlinksflag indicating whether symlink should be followed in source (False by default)
overwriteflag indicating whether destination should be overwritten if exists (False by default)
mergeflag indicating whether source should be merged into destination if the latter exists (False by default)
fail_immediatelyflag indicating whether the function is supposed to fail with an exception immediately on the first error instead of accumulating all exceptions (True by default)
depthdetermines how many levels of subdirectories and files should be copied
Exceptions
SAME-DIR-ERRORIf both paths point to the same file.
DIR-STAT-ERRORIf stat call for the source path fails.
PATH-EXISTS-ERRORIf destination path exists and overwrite flag is not set.
COPY-TREE-ERRORIf 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 path to the new copy.

◆ join_paths() [1/2]

string FsUtil::join_paths ( string  path1,
softlist< string paths 
)

Returns path resulting from joining the given paths.

Parameters
path1the first part of the path
pathsthe 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.

◆ join_paths() [2/2]

string FsUtil::join_paths ( list< string paths)

Returns path resulting from joining the given paths.

Parameters
pathsthe 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-ERRORif the list is empty

◆ 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
prefixprefix to be used in the newly created directory name
suffixsuffix to be used in the newly created directory name
pathpath 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-ERRORThe 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
prefixprefix to be used in the newly created file name
suffixsuffix to be used in the newly created file name
pathpath 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-ERRORThe 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
sourcepath to be copied
destinationpath the copy should be merged into
follow_symlinksflag indicating whether symlink should be followed in source (False by default)
overwriteflag indicating whether destination should be overwritten if exists (False by default)
fail_immediatelyflag indicating whether the function is supposed to fail with an exception immediately on the first error instead of accumulating all exceptions (True by default)
depthdetermines 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 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
sourcepath to be copied (must be a directory or a symlink pointing to one if follow_symlinks is set)
destinationpath the copy should be merged into (must be a directory or must not exist)
follow_symlinksflag indicating whether symlink should be followed in source (False by default)
fail_immediatelyflag indicating whether the function is supposed to fail with an exception immediately on the first error instead of accumulating all exceptions (True by default)
depthdetermines how many levels of subdirectories and files should be copied
Exceptions
SAME-DIR-ERRORIf both paths point to the same file.
DIR-STAT-ERRORIf stat call for the source path fails.
COPY-TREE-ERRORIf 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 path to the new copy.

◆ path_exists()

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

Check whether the given path exists or not.

Parameters
paththe path to be checked
follow_symlinksflag 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
pathpath to a filesystem tree root which should be removed
Exceptions
REMOVE-FILE-ERRORIf 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
pathpath 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
pathpath to a filesystem tree root which should be removed
fail_immediatelyflag 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
REMOVE-TREE-ERRORIf 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
path1first path
path2second path
follow_symlinksflag indicating whether symlinks should be followed (True by default)
ignore_errorsflag 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-ERRORIf 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
stat1first stat hash
stat2second stat hash
ignore_errorsflag 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-MISSINGIf 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.