std/private/ospaths2 (original) (raw)

proc /(head, tail: string): string {.noSideEffect, inline, ...raises: [], tags: [], forbids: [].}

The same as joinPath(head, tail) proc.

See also:

Example:

when defined(posix): assert "usr" / "" == "usr" assert "" / "lib" == "lib" assert "" / "/lib" == "/lib" assert "usr/" / "/lib/" == "usr/lib/" assert "usr" / "lib" / "../bin" == "usr/bin"

Source Edit

proc /../(head, tail: string): string {.noSideEffect, ...raises: [], tags: [], forbids: [].}

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

See also:

Example:

when defined(posix): assert "a/b/c" /../ "d/e" == "a/b/d/e" assert "a" /../ "d/e" == "a/d/e"

Source Edit

proc absolutePath(path: string; root = when supportedSystem: getCurrentDir() else: ""): string {....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:

Example:

assert absolutePath("a") == getCurrentDir() / "a"

Source Edit

proc addFileExt(filename, ext: string): string {.noSideEffect, ...gcsafe, extern: "nos$1", raises: [], 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:

Example:

assert addFileExt("foo.bar", "baz") == "foo.bar" assert addFileExt("foo.bar", "") == "foo.bar" assert addFileExt("foo", "baz") == "foo.baz"

Source Edit

proc changeFileExt(filename, ext: string): string {.noSideEffect, ...gcsafe, extern: "nos$1", raises: [], 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:

Example:

assert changeFileExt("foo.bar", "baz") == "foo.baz" assert changeFileExt("foo.bar", "") == "foo" assert changeFileExt("foo", "baz") == "foo.baz"

Source Edit

proc cmpPaths(pathA, pathB: string): int {.noSideEffect, ...gcsafe, extern: "nos$1", raises: [], tags: [], forbids: [].}

Compares two paths.

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

0 if pathA == pathB
< 0 if pathA < pathB
> 0 if pathA > pathB

Example:

when defined(macosx): assert cmpPaths("foo", "Foo") == 0 elif defined(posix): assert cmpPaths("foo", "Foo") > 0

Source Edit

proc isAbsolute(path: string): bool {....gcsafe, noSideEffect, ...extern: "nos$1", raises: [], tags: [], forbids: [].}

Checks whether a given path is absolute.

On Windows, network paths are considered absolute too.

Example:

assert not "".isAbsolute assert not ".".isAbsolute when defined(posix): assert "/".isAbsolute assert not "a/".isAbsolute assert "/a/".isAbsolute

Source Edit

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

Returns true if path is relative to base.

Example:

doAssert isRelativeTo("./foo//bar", "foo") doAssert isRelativeTo("foo/bar", ".") doAssert isRelativeTo("/foo/bar.nim", "/foo/bar.nim") doAssert not isRelativeTo("foo/bar.nims", "foo/bar.nim")

Source Edit

proc isRootDir(path: string): bool {.noSideEffect, ...gcsafe, extern: "nos$1", raises: [], tags: [], forbids: [].}

Checks whether a given path is a root directory.

Example:

assert isRootDir("") assert isRootDir(".") assert isRootDir("/") assert isRootDir("a") assert not isRootDir("/a") assert not isRootDir("a/b/c")

Source Edit

proc joinPath(head, tail: string): string {.noSideEffect, ...gcsafe, extern: "nos$1", 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:

Example:

when defined(posix): assert joinPath("usr", "lib") == "usr/lib" assert joinPath("usr", "lib/") == "usr/lib/" assert joinPath("usr", "") == "usr" assert joinPath("usr/", "") == "usr/" assert joinPath("", "") == "" assert joinPath("", "lib") == "lib" assert joinPath("", "/lib") == "/lib" assert joinPath("usr/", "/lib") == "usr/lib" assert joinPath("usr/lib", "../bin") == "usr/bin"

Source Edit

proc joinPath(parts: varargs[string]): string {.noSideEffect, ...gcsafe, extern: "nos$1OpenArray", raises: [], tags: [], forbids: [].}

The same as joinPath(head, tail) proc, but works with any number of directory parts.

You need to pass at least one element or the proc will assert in debug builds and crash on release builds.

See also:

Example:

when defined(posix): assert joinPath("a") == "a" assert joinPath("a", "b", "c") == "a/b/c" assert joinPath("usr/lib", "../../var", "log") == "var/log"

Source Edit

proc lastPathPart(path: string): string {.noSideEffect, ...gcsafe, extern: "nos$1", raises: [], tags: [], forbids: [].}

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

See also:

Example:

assert lastPathPart("foo/bar/") == "bar" assert lastPathPart("foo/bar") == "bar"

Source Edit

proc normalizedPath(path: string): string {....gcsafe, extern: "nos$1", tags: [], raises: [], forbids: [].}

Returns a normalized path for the current OS.

See also:

Example:

when defined(posix): assert normalizedPath("a///b//..//c///d") == "a/c/d"

Source Edit

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

on posix, prepends ./ if file doesn't contain / and is not "", ".", "..".

Example:

import std/sugar when defined(posix): doAssert "foo".dup(normalizeExe) == "./foo" doAssert "foo/../bar".dup(normalizeExe) == "foo/../bar" doAssert "".dup(normalizeExe) == ""

Source Edit

proc normalizePath(path: var string) {....gcsafe, extern: "nos$1", tags: [], raises: [], forbids: [].}

Normalize a path.

Consecutive directory separators are collapsed, including an initial double slash.

On relative paths, double dot (..) sequences are collapsed if possible. On absolute paths they are always collapsed.

**Warning:**URL-encoded and Unicode attempts at directory traversal are not detected. Triple dot is not handled.

See also:

Example:

when defined(posix): var a = "a///b//..//c///d" a.normalizePath() assert a == "a/c/d"

Source Edit

proc normalizePathEnd(path: string; trailingSep = false): string {....raises: [], tags: [], forbids: [].}

outplace overload

Example:

when defined(posix): assert normalizePathEnd("/lib//.//", trailingSep = true) == "/lib/" assert normalizePathEnd("lib/./.", trailingSep = false) == "lib" assert normalizePathEnd(".//./.", trailingSep = false) == "." assert normalizePathEnd("", trailingSep = true) == "" assert normalizePathEnd("/", trailingSep = false) == "/"

Source Edit

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

Ensures path has exactly 0 or 1 trailing DirSep, depending on trailingSep, and taking care of edge cases: it preservers whether a path is absolute or relative, and makes sure trailing sep is DirSep, not AltSep. Trailing /. are compressed, see examples.Source Edit

proc parentDir(path: string): string {.noSideEffect, ...gcsafe, extern: "nos$1", 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:

Example:

assert parentDir("") == "" when defined(posix): assert parentDir("/usr/local/bin") == "/usr/local" assert parentDir("foo/bar//") == "foo" assert parentDir("//foo//bar//.") == "/foo" assert parentDir("./foo") == "." assert parentDir("/./foo//./") == "/" assert parentDir("a//./") == "." assert parentDir("a/b/c/..") == "a"

Source Edit

proc relativePath(path, base: string; sep = DirSep): string {....gcsafe, extern: "nos$1", raises: [Exception], tags: [RootEffect], forbids: [].}

Converts path to a path relative to base.

The sep (default: osseps: 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:

Example:

assert relativePath("/Users/me/bar/z.nim", "/Users/other/bad", '/') == "../../me/bar/z.nim" assert relativePath("/Users/me/bar/z.nim", "/Users/other", '/') == "../me/bar/z.nim" when not doslikeFileSystem: assert relativePath("/Users///me/bar//z.nim", "//Users/", '/') == "me/bar/z.nim" assert relativePath("/Users/me/bar/z.nim", "/Users/me", '/') == "bar/z.nim" assert relativePath("", "/users/moo", '/') == "" assert relativePath("foo", ".", '/') == "foo" assert relativePath("foo", "foo", '/') == "."

Source Edit

proc sameFile(path1, path2: string): bool {....gcsafe, extern: "nos$1", tags: [ReadDirEffect], raises: [OSError], forbids: [].}

Returns true if both pathname arguments refer to the same physical file or directory.

Raises OSError if any of the files does not exist or information about it can not be obtained.

This proc will return true if given two alternative hard-linked or sym-linked paths to the same file or directory.

See also:

proc searchExtPos(path: string): int {....raises: [], tags: [], forbids: [].}

Returns index of the '.' char in path if it signifies the beginning of the file extension. Returns -1 otherwise.

See also:

Example:

assert searchExtPos("a/b/c") == -1 assert searchExtPos("c.nim") == 1 assert searchExtPos("a/b/c.nim") == 5 assert searchExtPos("a.b.c.nim") == 5 assert searchExtPos(".nim") == -1 assert searchExtPos("..nim") == -1 assert searchExtPos("a..nim") == 2

Source Edit

proc splitFile(path: string): tuple[dir, name, ext: string] {.noSideEffect, ...gcsafe, extern: "nos$1", raises: [], tags: [], forbids: [].}

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

dir does not end in osseps: 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:

Example:

var (dir, name, ext) = splitFile("usr/local/nimc.html") assert dir == "usr/local" assert name == "nimc" assert ext == ".html" (dir, name, ext) = splitFile("/usr/local/os") assert dir == "/usr/local" assert name == "os" assert ext == "" (dir, name, ext) = splitFile("/usr/local/") assert dir == "/usr/local" assert name == "" assert ext == "" (dir, name, ext) = splitFile("/tmp.txt") assert dir == "/" assert name == "tmp" assert ext == ".txt"

Source Edit

proc splitPath(path: string): tuple[head, tail: string] {.noSideEffect, ...gcsafe, extern: "nos$1", raises: [], tags: [], forbids: [].}

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

See also:

Example:

assert splitPath("usr/local/bin") == ("usr/local", "bin") assert splitPath("usr/local/bin/") == ("usr/local/bin", "") assert splitPath("/bin/") == ("/bin", "") when (NimMajor, NimMinor) <= (1, 0): assert splitPath("/bin") == ("", "bin") else: assert splitPath("/bin") == ("/", "bin") assert splitPath("bin") == ("", "bin") assert splitPath("") == ("", "")

Source Edit

proc tailDir(path: string): string {.noSideEffect, ...gcsafe, extern: "nos$1", raises: [], tags: [], forbids: [].}

Returns the tail part of path.

See also:

Example:

assert tailDir("/bin") == "bin" assert tailDir("bin") == "" assert tailDir("bin/") == "" assert tailDir("/usr/local/bin") == "usr/local/bin" assert tailDir("//usr//local//bin//") == "usr//local//bin//" assert tailDir("./usr/local/bin") == "usr/local/bin" assert tailDir("usr/local/bin") == "local/bin"

Source Edit

proc unixToNativePath(path: string; drive = ""): string {.noSideEffect, ...gcsafe, extern: "nos$1", raises: [], 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