files

nimony/lib/std/files.nim

This module implements file handling on Path: removing, copying and moving files, and querying or changing their permissions.

See also:

paths module for path manipulation
dirs module for directories
symlinks module for symbolic links

type CopyFlag = enum
  cfSymlinkAsIs = (0, "cfSymlinkAsIs")
  cfSymlinkFollow = (1, "cfSymlinkFollow")
  cfSymlinkIgnore = (2, "cfSymlinkIgnore")

func dollar`.CopyFlag(e: CopyFlag): string
proc tryRemoveFile(file: Path): ErrorCode
Tries to remove the file file. A symlink is removed itself, never its target. On Windows the read-only attribute is ignored, as in Nim.
proc removeFile(file: Path)
Removes the file file. If the file does not exist, no error is raised.
proc getFilePermissions(filename: Path): set[FilePermission]
Retrieves the permissions of filename, following symlinks.
On Windows only the read-only attribute is checked: every other permission is reported as present.
See also:
- setFilePermissions proc_
proc setFilePermissions(filename: Path; permissions: set[FilePermission]; followSymlinks: bool)
Sets the permissions of filename.
If followSymlinks is true (default) and filename is a symlink, the permissions of the file it points to are changed. With followSymlinks set to false a symlink is left alone: symlink permissions are not observed on Linux, and this module binds no lchmod.
On Windows only the read-only attribute is changed, following fpUserWrite.
See also:
- getFilePermissions proc_
proc copyFile(source: Path; dest: Path; options: CopyFlag; bufferSize: int64)
Copies a file from source to dest, where dest.parentDir must exist.
On non-Windows OSes, options specifies the way the file is copied; by default, if source is a symlink, the file it points to is copied. options is ignored on Windows: symlinks are skipped.
If dest already exists, its permissions are kept and its content is overwritten. Otherwise on POSIX dest gets the default permissions of a new file (0o666 less the umask); use copyFileWithPermissions proc_ to carry over those of source. On Windows copyFile already copies the source file's attributes.
bufferSize is the size of the chunks the content is copied in.
See also:
- CopyFlag enum_
- copyFileWithPermissions proc_
- copyFileToDir proc_
proc copyFileToDir(source: Path; dir: Path; options: CopyFlag; bufferSize: int64)
Copies a file source into directory dir, which must exist.
options and bufferSize are as for copyFile proc_. An empty dir raises ValueError rather than meaning the current directory.
See also:
- copyFile proc_
proc copyFileWithPermissions(source: Path; dest: Path; ignorePermissionErrors: bool; options: CopyFlag)
Copies a file from source to dest preserving its permissions.
options is as for copyFile proc_. On Windows this is just copyFile, which already copies the attributes.
On POSIX the permissions are applied after the content is copied, which does not happen atomically. If ignorePermissionErrors is true (default), errors while reading or setting them are ignored; otherwise they are raised. A symlink copied as is, or skipped, gets no permissions applied: chmod would change the file it points to instead.
See also:
- copyFile proc_
- getFilePermissions proc_
- setFilePermissions proc_
proc moveFile(source: Path; dest: Path)
Moves a file from source to dest, where dest.parentDir must exist.
Symlinks are not followed: if source is a symlink, it is itself moved, not its target. If dest already exists, it is overwritten.
Can be used to rename files. Within a filesystem the move is a single atomic rename. Across filesystems (EXDEV) POSIX falls back to copyFileWithPermissions proc_ followed by removing source; if that removal fails, dest is removed again and the error is raised. Windows lets MoveFileExW copy across volumes itself.
See also:
- copyFile proc_
- copyFileWithPermissions proc_
- removeFile proc_