nim/file_extras

Some File utility functions

Procs

current_directory

proc current_directory(): Path {.....}

Return current directory

Alias for getCurrentDir()

del_dir_tree

proc del_dir_tree(dname: Path): QTValid {.....}

Remove directory and children

Parameters:
dname path of directory to be removed.

In order for this function to work the directory must exist, and must be owned by the current user, and the current user must have read and write permissions to the directory, and it may not be the users home directory..

delete_file

proc delete_file(path: Path): bool {.....}

Delete file

Returns true if successful or false if fails

file_is_creatable

proc file_is_creatable(path: Path): QTValid {.....}

Test if we might be able to create file

file_is_empty

proc file_is_empty(fname: Path): bool {.....}

Test that path is a file but contains no data

Returns false if not a valid file or true if zero length file

get_file_extension

proc get_file_extension(path: Path): string {.....}

Return extension from filename

File does not need to exist

get_file_size

proc get_file_size(fname: Path): BiggestInt {.....}

Return size of file, or -1 if failed

get_user_temp_dir

proc get_user_temp_dir(): Path {.....}

Return temp directory for current user

The return from this function is memoised, so will not change even if the context changes during the run.

home_directory

proc home_directory(): Path {.....}

Return home directory

Alias for getHomeDir()

make_dir

proc make_dir(dirnam: Path; fail_if_exists = true): QTValid {.
    ....}

Create new directory

make_temp_dir

proc make_temp_dir(): QTResult[Path] {.....}

Create new directory with temporary name

Returns:

Uses make_temp_filename() to generate path name and then creates a unique directory name.

Created directory will have full user rights (i.e. the path is owned by the current user and the current user has read and write permissions to the directory).

make_temp_filename

proc make_temp_filename(): Path {.....}

Create fully pathed file name of temporary file.without suffix

Alias for make_temp_filename(none)

make_temp_filename

proc make_temp_filename(suff: QOption[string]): Path {.
    ....}

Create fully pathed file name of temporary file with optional suffix.

Returns new unique filename.

Warning: The file is guaranteed not to exist when the function returns but there can be no guarantee that some other process does not create the file between when the function returns and the calling function seeks to use the file name.

make_temp_filename

proc make_temp_filename(suff: string): Path {.....}

Create fully pathed file name of temporary file.with specified suffix

Alias for make_temp_filename(some(suff))

match_file_extension

proc match_file_extension(path: Path; extension: string;
                          ignore_case: bool = false): bool {.....}

Return true if file extension matches expected file extension

If ignore_case is true then match will be true even if they differ in case (note that case is only ASCII and does not check for non-ASCII character case mismatch).

The extension supplied may be with or without a dot.

match_file_extension

proc match_file_extension(path: Path; extensions: openArray[string];
                          ignore_case: bool = false): bool {.....}

Return true if file extension matches any of the expected file extensions

If ignore_case is true then match will be true even if they differ in case (note that case is only ASCII and does not check for non-ASCII character case mismatch).

The extension supplied may be with or without a dot.

normalise_path

proc normalise_path(path: Path; root: Path = paths.getCurrentDir()): QTResult[
    Path] {.....}

Normalise file path

Create absolute path and collapse '..' terms

Parameters:

Returns:

normalised path or error for invalid path.

read_file

proc read_file(filnam: Path): QTResult[string] {.....}

Read entire file

Return text read from file or error message

read_first_line

proc read_first_line(filnam: Path; max_size: uint = 4096): QTResult[string] {.
    ....}

Read first line from input file.

Return line read from file or error message

set_current_directory

proc set_current_directory(path: Path) {.....}

Set current directory

Alias for setCurrentDir()

splitable

proc splitable(path: Path): bool {.....}

Return true if path contains a path separator.

which

proc which(cmd: string): string {.....}

Return path to command

Alias for findExe

write_output_file

proc write_output_file(fname: Path; data: string = ""): QTValid {.
    ....}

Create and write to named output file.

Parameters:

If data is empty then the file will be left with read and write
permissions, but if data is not empty the the file will be left with
read but not write permissions.

Returns:

write_temp_file

proc write_temp_file(data: string = ""): QTResult[Path] {.
    ....}

Create temporary file with specified data content

If data is empty then the file will be left with read and write permissions, but if data is not empty the the file will be left with read but not write permissions.

Return name of file

Iterators

splitDirs

iterator splitDirs(path: Path; root: Path = paths.getCurrentDir()): Path {.
    ....}

Iterates through each directory in the path

The path is converted an absolute path, so is the given path is a relative path then it will also climb the tree above the start point of the path.

Split will always start from the base of the path and move up through the tree. The final item returned will be a "/" for a POSIX system. On a Windows system it will either finish with a slash or a drive letter with a colon, depending on whether a drive letter was specified for the path.

Templates

/

template `/`(l: Path; r: string): Path

template `/`(l: string; r: Path): Path

==

template `==`(l: Path; r: string): bool

template `==`(l: string; r: Path): bool

cstring

template cstring(path: Path): cstring

Convert from Path to cstring

Useful for interface to external C functions

found_exe

template found_exe(cmd: string): bool

Return true if command found in execution paths

This is a convenience method for findExe(cmd) != ""