std/dirs

This module implements directory handling.

Imports

paths, osdirs

Procs

proc createDir(dir: Path) {.inline, ...tags: [WriteDirEffect, ReadDirEffect],
                            raises: [OSError, IOError], forbids: [].}

Creates the directory dir.

The directory may contain several subdirectories that do not exist yet. The full path is created. If this fails, OSError is raised.

It does not fail if the directory already exists because for most usages this does not indicate an error.

See also:

• removeDir proc
• existsOrCreateDir proc
• moveDir proc

Source Edit

proc dirExists(dir: Path): bool {.inline, ...tags: [ReadDirEffect], sideEffect,
                                  ...raises: [], forbids: [].}

Returns true if the directory dir exists. If dir is a file, false is returned. Follows symlinks. Source Edit

proc existsOrCreateDir(dir: Path): bool {.inline,
    ...tags: [WriteDirEffect, ReadDirEffect], raises: [OSError, IOError],
    forbids: [].}

Checks if a directory dir exists, and creates it otherwise.

Does not create parent directories (raises OSError if parent directories do not exist). Returns true if the directory already exists, and false otherwise.

See also:

• removeDir proc
• createDir proc
• moveDir proc

Source Edit

proc moveDir(source, dest: Path) {.inline, ...tags: [ReadIOEffect, WriteIOEffect],
                                   raises: [OSError, IOError], forbids: [].}

Moves a directory from source to dest.

Symlinks are not followed: if source contains symlinks, they themself are moved, not their target.

If this fails, OSError is raised.

See also:

• moveFile proc
• removeDir proc
• existsOrCreateDir proc
• createDir proc

Source Edit

proc removeDir(dir: Path; checkDir = false) {.inline,
    ...tags: [WriteDirEffect, ReadDirEffect], raises: [OSError], forbids: [].}

Removes the directory dir including all subdirectories and files in dir (recursively).

If this fails, OSError is raised. This does not fail if the directory never existed in the first place, unless checkDir = true.

See also:

• removeFile proc
• existsOrCreateDir proc
• createDir proc
• moveDir proc

Source Edit

proc setCurrentDir(newDir: Path) {.inline, ...tags: [], raises: [OSError],
                                   forbids: [].}

Sets the current working directory; OSError is raised if newDir cannot been set.

See also:

• getCurrentDir proc

Source Edit

Iterators

iterator walkDir(dir: Path; relative = false; checkDir = false;
                 skipSpecial = false): tuple[kind: PathComponent, path: Path] {.
    ...tags: [ReadDirEffect], raises: [OSError], forbids: [].}

Walks over the directory dir and yields for each directory or file in dir. The component type and full path for each item are returned.

Walking is not recursive.

• If relative is true (default: false) the resulting path is shortened to be relative to dir, otherwise the full path is returned.
• If checkDir is true, OSError is raised when dir doesn't exist.
• If skipSpecial is true, then (besides all directories) only regular files (without special "file" objects like FIFOs, device files, etc) will be yielded on Unix.

Source Edit

iterator walkDirRec(dir: Path; yieldFilter = {pcFile}; followFilter = {pcDir};
                    relative = false; checkDir = false; skipSpecial = false): Path {.
    ...tags: [ReadDirEffect], raises: [OSError], forbids: [].}

Recursively walks over the directory dir and yields for each file or directory in dir.

Options relative, checkdir, skipSpecial are explained in walkDir iterator description.

Warning: Modifying the directory structure while the iterator is traversing may result in undefined behavior!

Walking is recursive. followFilter controls the behaviour of the iterator:

yieldFilter	meaning
pcFile	yield real files (default)
pcLinkToFile	yield symbolic links to files
pcDir	yield real directories
pcLinkToDir	yield symbolic links to directories

followFilter	meaning
pcDir	follow real directories (default)
pcLinkToDir	follow symbolic links to directories

See also:

• walkDir iterator

Source Edit

Exports

PathComponent