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; the directory and all its contents are removed in the destructor. 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 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

  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 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 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

  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)
  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 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

  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)
  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.

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

  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 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

  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.

## join_paths() [2/2]

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

Returns 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

## 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 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 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

  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 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-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.