# std/private/osdirs

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

# Imports

oserrors, ospaths2, osfiles, oscommon, staticos, syncio, assertions, widestrs, posix, times

# Procs

    proc copyDir(source, dest: string; skipSpecial = false) {....gcsafe,
        extern: "nos$1", tags: [ReadDirEffect, WriteIOEffect, ReadIOEffect], gcsafe,
        raises: [OSError, IOError], forbids: [].}

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

  If this fails, `OSError` is raised.

  On the Windows platform this proc will copy the attributes from `source` into `dest`.

  On other platforms created files and directories will inherit the default permissions of a newly created file/directory for the user. Use copyDirWithPermissions proc to preserve attributes recursively on these platforms.

  See also:

  - copyDirWithPermissions proc
  - osfiles: copyFile proc
  - osfiles: copyFileWithPermissions proc
  - removeDir proc
  - existsOrCreateDir proc
  - createDir proc
  - moveDir proc
  Source Edit

    proc copyDirWithPermissions(source, dest: string; ignorePermissionErrors = true;
                                skipSpecial = false) {....gcsafe, extern: "nos$1",
        tags: [ReadDirEffect, WriteIOEffect, ReadIOEffect], gcsafe,
        raises: [OSError, IOError, Exception], forbids: [].}

  Copies a directory from `source` to `dest` preserving file permissions.

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

  If this fails, `OSError` is raised. This is a wrapper proc around copyDir and osfiles: copyFileWithPermissions procs on non-Windows platforms.

  On Windows this proc is just a wrapper for copyDir proc since that proc already copies attributes.

  On non-Windows systems permissions are copied after the file or directory itself has been copied, which won't happen atomically and could lead to a race condition. If `ignorePermissionErrors` is true (default), errors while reading/setting file attributes will be ignored, otherwise will raise `OSError`.

  See also:

  - copyDir proc
  - osfiles: copyFile proc
  - osfiles: copyFileWithPermissions proc
  - removeDir proc
  - moveDir proc
  - existsOrCreateDir proc
  - createDir proc
  Source Edit

    proc createDir(dir: string) {....gcsafe, extern: "nos$1",
                                  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
  - copyDir proc
  - copyDirWithPermissions proc
  - moveDir proc
  Source Edit

    proc existsOrCreateDir(dir: string): bool {....gcsafe, extern: "nos$1",
        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
  - copyDir proc
  - copyDirWithPermissions proc
  - moveDir proc
  Source Edit

    proc moveDir(source, dest: string) {....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:

  - osfiles: moveFile proc
  - copyDir proc
  - copyDirWithPermissions proc
  - removeDir proc
  - existsOrCreateDir proc
  - createDir proc
  Source Edit

    proc removeDir(dir: string; checkDir = false) {....gcsafe, extern: "nos$1",
        tags: [WriteDirEffect, ReadDirEffect], gcsafe, 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:

  - osfiles: tryRemoveFile proc
  - osfiles: removeFile proc
  - existsOrCreateDir proc
  - createDir proc
  - copyDir proc
  - copyDirWithPermissions proc
  - moveDir proc
  Source Edit

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

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

  See also:

  - appdirs: getHomeDir proc
  - appdirs: getConfigDir proc
  - appdirs: getTempDir proc
  - paths: getCurrentDir proc
  Source Edit

# Iterators

    iterator walkDir(dir: string; relative = false; checkDir = false;
                     skipSpecial = false): tuple[kind: PathComponent, path: string] {.
        ...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.

  Example:

  This directory structure:

      dirA / dirB / fileB1.txt
           / dirC
           / fileA1.txt
           / fileA2.txt

  and this code:

  Example: cmd: -r:off

      import std/[strutils, sugar]
      # note: order is not guaranteed
      # this also works at compile time
      assert collect(for k in walkDir("dirA"): k.path).join(" ") ==
                            "dirA/dirB dirA/dirC dirA/fileA2.txt dirA/fileA1.txt"

  See also:
  - walkPattern iterator
  - walkFiles iterator
  - walkDirs iterator
  - walkDirRec iterator
  Source Edit

    iterator walkDirRec(dir: string; yieldFilter = {pcFile}; followFilter = {pcDir};
                        relative = false; checkDir = false; skipSpecial = false): string {.
        ...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:

  - walkPattern iterator
  - walkFiles iterator
  - walkDirs iterator
  - walkDir iterator
  Source Edit

    iterator walkDirs(pattern: string): string {....tags: [ReadDirEffect], raises: [],
        forbids: [].}

  Iterate over all the directories that match the `pattern`.

  On POSIX this uses the glob call. `pattern` is OS dependent, but at least the `"*.ext"` notation is supported.

  See also:

  - walkPattern iterator
  - walkFiles iterator
  - walkDir iterator
  - walkDirRec iterator

  Example:

      import std/os
      import std/sequtils
      let paths = toSeq(walkDirs("lib/pure/*")) # works on Windows too
      assert "lib/pure/concurrency".unixToNativePath in paths

  Source Edit

    iterator walkFiles(pattern: string): string {....tags: [ReadDirEffect], raises: [],
        forbids: [].}

  Iterate over all the files that match the `pattern`.

  On POSIX this uses the glob call. `pattern` is OS dependent, but at least the `"*.ext"` notation is supported.

  See also:

  - walkPattern iterator
  - walkDirs iterator
  - walkDir iterator
  - walkDirRec iterator

  Example:

      import std/os
      import std/sequtils
      assert "lib/pure/os.nim".unixToNativePath in toSeq(walkFiles("lib/pure/*.nim")) # works on Windows too

  Source Edit

    iterator walkPattern(pattern: string): string {....tags: [ReadDirEffect],
        raises: [], forbids: [].}

  Iterate over all the files and directories that match the `pattern`.

  On POSIX this uses the glob call. `pattern` is OS dependent, but at least the `"*.ext"` notation is supported.

  See also:

  - walkFiles iterator
  - walkDirs iterator
  - walkDir iterator
  - walkDirRec iterator

  Example:

      import std/os
      import std/sequtils
      let paths = toSeq(walkPattern("lib/pure/*")) # works on Windows too
      assert "lib/pure/concurrency".unixToNativePath in paths
      assert "lib/pure/os.nim".unixToNativePath in paths

  Source Edit

# Exports

dirExists, PathComponent