dirs

nimony/lib/std/dirs.nim

• proc tryCreateFinalDir(dir: Path): ErrorCode

  Tries to create the final directory in a path. In other words, it tries to create a single new directory, not a nested one. It returns the OS's error code making it easy to distinguish between "could not create" and "already exists".

• proc createDir(dir: Path)

  Creates a new directory dir. If the directory already exists, no error is raised. This can be used to create a nested directory structure directly.

• proc tryRemoveFinalDir(dir: Path): ErrorCode

  Tries to remove the final directory in a path. In other words, it tries to remove a single directory, not a nested one. It returns the OS's error code making it easy to distinguish between "could not remove" and "does not exist".

• type DirEntry = object
    kind: PathComponent
    path: Path

• type DirWalker = object
    stream: DirStream
    dir: Path
    status: ErrorCode

• proc tryOpenDir(dir: sink Path): DirWalker

  Tries to open the directory dir for iteration over its entries.

• proc tryNextDir(w: var DirWalker; e: var DirEntry; skipSpecial: bool): bool

  Advances w to its next entry and stores it in e. Returns false at the end of the directory or on an error, which w then keeps.

  If skipSpecial is true, special "file" objects (FIFOs, sockets, device files) are skipped on POSIX; otherwise they are reported as pcFile. Windows has none.

• proc tryCloseDir(w: var DirWalker): ErrorCode

  Closes w. A walker whose tryOpenDir failed holds no handle, so there is nothing to close.

• iterator walkDir(dir: Path; relative: bool; checkDir: bool; skipSpecial: bool): tuple[kind: PathComponent, path: Path]

  Walks over all entries in the directory dir.

  Yields tuples of (kind, path) where kind is one of:

  • pcFile - regular file
  • pcDir - directory
  • pcLinkToFile - symbolic link to a file
  • pcLinkToDir - symbolic link to a directory

  If relative is true, yields relative paths (just the filename/dirname), otherwise yields full paths.

  If checkDir is true, raises an error if dir doesn't exist or isn't a directory.

  Special directories "." and ".." are skipped. Special "file" objects (FIFOs, sockets, device files) are yielded as pcFile, unless skipSpecial is true: then they are skipped on POSIX.

• iterator walkDirRec(dir: Path; yieldFilter: set[PathComponent]; followFilter: set[PathComponent]; relative: bool; checkDir: bool; skipSpecial: bool): Path

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

  Options relative, checkDir and skipSpecial are explained in the walkDir iterator_ description; checkDir only applies to dir itself, so a subdirectory that cannot be opened is silently skipped.

  .. 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_
• proc removeDir(dir: Path; checkDir: bool)

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

  Symlinks inside dir are removed as links; their targets are never followed. This does not fail if the directory never existed in the first place, unless checkDir is true.

  Use tryRemoveFinalDir to remove a single directory only if it is empty.

  See also:

  • tryRemoveFinalDir proc_
  • removeFile proc_
  • createDir proc_
  • moveDir proc_
• proc copyDir(source: Path; dest: Path; skipSpecial: bool)

  Copies a directory from source to dest.

  On non-Windows OSes, symlinks are copied as symlinks. On Windows, symlinks are skipped.

  If skipSpecial is true, then (besides all directories) only regular files (without special "file" objects like FIFOs, device files, etc) will be copied on POSIX.

  On Windows this proc copies the attributes from source into dest. On other platforms created files and directories get the default permissions of a newly created file/directory for the user. Use copyDirWithPermissions proc_ to preserve them recursively.

  See also:

  • copyDirWithPermissions proc_
  • copyFile proc
  • removeDir proc_
  • createDir proc_
  • moveDir proc_
• proc copyDirWithPermissions(source: Path; dest: Path; ignorePermissionErrors: bool; skipSpecial: bool)

  Copies a directory from source to dest preserving file permissions.

  On non-Windows OSes, symlinks are copied as symlinks. On Windows, symlinks are skipped. skipSpecial is as for copyDir proc_.

  On Windows this is just copyDir proc_, which already copies the attributes. On other systems the permissions of each file and directory are applied after it has been copied, which does not happen atomically. If ignorePermissionErrors is true (default), errors while reading or setting them are ignored; otherwise they are raised.

  See also:

  • copyDir proc_
  • copyFileWithPermissions proc
  • removeDir proc_
  • moveDir proc_
• proc moveDir(source: Path; dest: Path)

  Moves a directory from source to dest.

  Symlinks are not followed: if source contains symlinks, they themselves are moved, not their targets. As with rename, an existing dest must be an empty directory, which is replaced.

  Within one filesystem the move is a single rename. Across filesystems (EXDEV on POSIX, an access error on Windows) it falls back to copyDir proc followed by removeDir proc on source, as Nim does.

  See also:

  • moveFile proc
  • copyDir proc_
  • createDir proc_
  • removeDir proc_
• proc getCurrentDir(): Path

  Returns the current working directory as a Path.

  Raises an error if unable to retrieve the current directory.

  See also:

  • setCurrentDir proc_
• proc setCurrentDir(dir: Path)

  Sets the current working directory to dir.

  Raises errors if the directory doesn't exist or lacks permissions.

  See also:

  • getCurrentDir proc_