Source Edit

This module implements path handling.

See also:

Imports

osseps, envvars, osappdirs, pathnorm, ospaths2

Types

  1. Path = distinct string

Source Edit

Procs

  1. func `/`(head, tail: Path): Path {.inline, ...raises: [], tags: [], forbids: [].}

Joins two directory names to one.

returns normalized path concatenation of head and tail, preserving whether or not tail has a trailing slash (or, if tail if empty, whether head has one).

See also:

Source Edit

  1. func `/../`(head, tail: Path): Path {.inline, ...raises: [], tags: [], forbids: [].}

The same as parentDir(head) / tail, unless there is no parent directory. Then head / tail is performed instead.

See also:

Source Edit

  1. func `==`(x, y: Path): bool {.inline, ...raises: [], tags: [], forbids: [].}

Compares two paths.

On a case-sensitive filesystem this is done case-sensitively otherwise case-insensitively.

Source Edit

  1. proc absolutePath(path: Path; root = getCurrentDir()): Path {.
  2. ...raises: [ValueError], tags: [], forbids: [].}

Returns the absolute path of path, rooted at root (which must be absolute; default: current directory). If path is absolute, return it, ignoring root.

See also:

Source Edit

  1. func add(x: var Path; y: Path) {.borrow, ...raises: [], tags: [], forbids: [].}

Source Edit

  1. func addFileExt(filename: Path; ext: string): Path {.inline, ...raises: [],
  2. tags: [], forbids: [].}

Adds the file extension ext to filename, unless filename already has an extension.

Ext should be given without the leading ‘.’, because some filesystems may use a different character. (Although I know of none such beast.)

See also:

Source Edit

  1. func changeFileExt(filename: Path; ext: string): Path {.inline, ...raises: [],
  2. tags: [], forbids: [].}

Changes the file extension to ext.

If the filename has no extension, ext will be added. If ext == “” then any extension is removed.

Ext should be given without the leading ‘.’, because some filesystems may use a different character. (Although I know of none such beast.)

See also:

Source Edit

  1. proc expandTilde(path: Path): Path {.inline,
  2. ...tags: [ReadEnvEffect, ReadIOEffect],
  3. raises: [], forbids: [].}

Expands ~ or a path starting with ~/ to a full path, replacing ~ with getHomeDir() (otherwise returns path unmodified).

Windows: this is still supported despite the Windows platform not having this convention; also, both ~/ and ~\ are handled.

Example:

  1. import std/appdirs
  2. assert expandTilde(Path("~") / Path("appname.cfg")) == getHomeDir() / Path("appname.cfg")
  3. assert expandTilde(Path("~/foo/bar")) == getHomeDir() / Path("foo/bar")
  4. assert expandTilde(Path("/foo/bar")) == Path("/foo/bar")

Source Edit

  1. func extractFilename(path: Path): Path {.inline, ...raises: [], tags: [],
  2. forbids: [].}

Extracts the filename of a given path.

This is the same as name & ext from splitFile(path) proc.

See also:

Source Edit

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

Returns the current working directory i.e. where the built binary is run.

So the path returned by this proc is determined at run time.

See also:

Source Edit

  1. func isAbsolute(path: Path): bool {.inline, ...raises: [], tags: [], forbids: [].}

Checks whether a given path is absolute.

On Windows, network paths are considered absolute too.

Source Edit

  1. proc isRelativeTo(path: Path; base: Path): bool {.inline, ...raises: [Exception],
  2. tags: [RootEffect], forbids: [].}

Returns true if path is relative to base. Source Edit

  1. func isRootDir(path: Path): bool {.inline, ...raises: [], tags: [], forbids: [].}

Checks whether a given path is a root directory. Source Edit

  1. func lastPathPart(path: Path): Path {.inline, ...raises: [], tags: [], forbids: [].}

Like extractFilename proc, but ignores trailing dir separator; aka: baseName in some other languages.

See also:

Source Edit

  1. proc normalizeExe(file: var Path) {.borrow, ...raises: [], tags: [], forbids: [].}

Source Edit

  1. proc normalizePath(path: var Path) {.borrow, ...raises: [], tags: [], forbids: [].}

Source Edit

  1. proc normalizePathEnd(path: var Path; trailingSep = false) {.borrow, ...raises: [],
  2. tags: [], forbids: [].}

Source Edit

  1. func parentDir(path: Path): Path {.inline, ...raises: [], tags: [], forbids: [].}

Returns the parent directory of path.

This is similar to splitPath(path).head when path doesn’t end in a dir separator, but also takes care of path normalizations. The remainder can be obtained with lastPathPart(path) proc.

See also:

Source Edit

  1. proc relativePath(path, base: Path; sep = DirSep): Path {.inline,
  2. ...raises: [Exception], tags: [RootEffect], forbids: [].}

Converts path to a path relative to base.

The sep (default: DirSep) is used for the path normalizations, this can be useful to ensure the relative path only contains ‘/‘ so that it can be used for URL constructions.

On Windows, if a root of path and a root of base are different, returns path as is because it is impossible to make a relative path. That means an absolute path can be returned.

See also:

Source Edit

  1. func splitFile(path: Path): tuple[dir, name: Path, ext: string] {.inline,
  2. ...raises: [], tags: [], forbids: [].}

Splits a filename into (dir, name, extension) tuple.

dir does not end in DirSep unless it’s /. extension includes the leading dot.

If path has no extension, ext is the empty string. If path has no directory component, dir is the empty string. If path has no filename component, name and ext are empty strings.

See also:

Source Edit

  1. func splitPath(path: Path): tuple[head, tail: Path] {.inline, ...raises: [],
  2. tags: [], forbids: [].}

Splits a directory into (head, tail) tuple, so that head / tail == path (except for edge cases like “/usr”).

See also:

Source Edit

  1. func tailDir(path: Path): Path {.inline, ...raises: [], tags: [], forbids: [].}

Returns the tail part of path.

See also:

Source Edit

  1. func unixToNativePath(path: Path; drive = Path("")): Path {.inline, ...raises: [],
  2. tags: [], forbids: [].}

Converts an UNIX-like path to a native one.

On an UNIX system this does nothing. Else it converts ‘/‘, ‘.’, ‘..’ to the appropriate things.

On systems with a concept of “drives”, drive is used to determine which drive label to use during absolute path conversion. drive defaults to the drive of the current working directory, and is ignored on systems that do not have a concept of “drives”.

Source Edit

Iterators

  1. iterator parentDirs(path: Path; fromRoot = false; inclusive = true): Path {.
  2. ...raises: [], tags: [], forbids: [].}

Walks over all parent directories of a given path.

If fromRoot is true (default: false), the traversal will start from the file system root directory. If inclusive is true (default), the original argument will be included in the traversal.

Relative paths won’t be expanded by this iterator. Instead, it will traverse only the directories appearing in the relative path.

See also:

Source Edit

Exports

ExtSep, FileSystemCaseSensitive, DynlibFormat, DirSep, AltSep, PathSep, ScriptExt, doslikeFileSystem, ExeExt, CurDir, ParDir, ReadDirEffect, WriteDirEffect