std/private/ospaths2

Импорты

since, strutils, pathnorm, oserrors, oscommon, winlean, osseps, ntpath

Процедуры

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

То же самое, что и процедура joinPath(head, tail).

См. также:

• процедура `/../`
• процедура joinPath(head, tail)
• процедура joinPath(parts: varargs[string])
• процедура splitPath
• процедура uri.combine
• процедура uri./

Пример:

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

Исходный код Редактировать

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

То же самое, что и parentDir(head) / tail, если нет родительской директории. В противном случае выполняется head / tail.

См. также:

• процедура `/`
• процедура parentDir

Пример:

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

Исходный код Редактировать

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

Возвращает абсолютный путь к path, с корнем в root (который должен быть абсолютным; по умолчанию - текущая директория). Если path является абсолютным, возвращает его, игнорируя root.

См. также:

• процедура normalizedPath
• процедура normalizePath

Пример:

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

Исходный код Редактировать

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

Добавляет расширение файла ext к filename, если у filename ещё нет расширения.

Ext должно быть указано без ведущего '.', так как некоторые файловые системы могут использовать другой символ. (Хотя мне не известно ни одной такой системы.)

См. также:

• процедура searchExtPos
• процедура splitFile
• процедура extractFilename
• процедура lastPathPart
• процедура changeFileExt

Пример:

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

Исходный код Редактировать

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

Изменяет расширение файла на ext.

Если у filename нет расширения, будет добавлено ext. Если ext == "" то любое расширение удаляется.

Ext должно быть указано без ведущего '.', так как некоторые файловые системы могут использовать другой символ. (Хотя мне не известно ни одной такой системы.)

См. также:

• процедура searchExtPos
• процедура splitFile
• процедура extractFilename
• процедура lastPathPart
• процедура addFileExt

Пример:

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

Исходный код Редактировать

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

Сравнивает два пути.

В случае чувствительной к регистру файловой системы сравнение проводится чувствительно к регистру, иначе - без учёта регистра. Возвращает:

0 если pathA == pathB
< 0 если pathA < pathB
> 0 если pathA > pathB

Пример:

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

Исходный код Редактировать

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

Извлекает имя файла из заданного path.

Это то же самое, что и name & ext из процедуры splitFile(path).

См. также:

• процедура searchExtPos
• процедура splitFile
• процедура lastPathPart
• процедура changeFileExt
• процедура addFileExt

Пример:

assert extractFilename("foo/bar/") == ""
assert extractFilename("foo/bar") == "bar"
assert extractFilename("foo/bar.baz") == "bar.baz"

Исходный код Редактировать

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

Возвращает текущую рабочую директорию, т.е. директорию, в которой запущена исполняемая программа.

Таким образом, путь, возвращаемый этой процедурой, определяется во время выполнения.

См. также:

• osappdirs: процедура getHomeDir
• osappdirs: процедура getConfigDir
• osappdirs: процедура getTempDir
• osdirs: процедура setCurrentDir
• шаблон currentSourcePath
• процедура getProjectPath

Исходный код Редактировать

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

Проверяет, является ли заданный path абсолютным.

В Windows сетевые пути также считаются абсолютными.

Пример:

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

Исходный код Редактировать

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

Возвращает true, если path является относительным к base.

Пример:

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")

Исходный код Редактировать

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

Проверяет, является ли заданный path корневой директорией.

Пример:

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

Исходный код Редактировать

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

Объединяет два имени каталога в одно.

Возвращает нормализованное объединение путей head и tail, сохраняя наличие или отсутствие конечного слэша у tail (или, если tail пусто, наличие слэша у head).

См. также:

• joinPath(parts: varargs[string]) proc
• / proc
• splitPath proc
• uri.combine proc
• uri./ proc

Пример:

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"

Исходный код Редактировать

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

Аналогично joinPath(head, tail) proc, но работает с любым количеством частей пути.

Необходимо передать как минимум один элемент, иначе в отладочных сборках произойдет утверждение, а в релизных – аварийное завершение.

См. также:

• joinPath(head, tail) proc
• / proc
• /../ proc
• splitPath proc

Пример:

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

Исходный код Редактировать

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

Подобно extractFilename proc, но игнорирует конечный разделитель каталога; также известен как baseName на некоторых других языках.

См. также:

• searchExtPos proc
• splitFile proc
• extractFilename proc
• changeFileExt proc
• addFileExt proc

Пример:

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

Исходный код Редактировать

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

Возвращает нормализованный путь для текущей ОС.

См. также:

• absolutePath proc
• normalizePath proc для версии, изменяющей объект напрямую

Пример:

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

Исходный код Редактировать

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

в POSIX, добавляет ./ в начало, если file не содержит / и не является "", ".", "..".

Пример:

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

Исходный код Редактировать

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

Нормализует путь.

Последовательные разделители каталогов сворачиваются, включая начальный двойной слэш.

Для относительных путей последовательности двойной точки (..) сворачиваются при возможности. Для абсолютных путей они всегда сворачиваются.

Предупреждение: URL-кодированные и Unicode-попытки обхода защиты каталога не обнаруживаются. Тройная точка не обрабатывается.

См. также:

• absolutePath proc
• normalizedPath proc для версии, не изменяющей исходный объект
• normalizeExe proc

Пример:

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

Исходный код Редактировать

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

перегрузка, возвращающая новый объект

Пример:

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

Исходный код Редактировать

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

Обеспечивает, что path имеет ровно 0 или 1 конечный DirSep, в зависимости от trailingSep, и учитывает крайние случаи: сохраняет, является ли путь абсолютным или относительным, и гарантирует, что конечный разделитель – это DirSep, а не AltSep. Конечные /. сжимаются, см. примеры. Исходный код Редактировать

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

Возвращает родительский каталог path.

Это аналогично splitPath(path).head, когда path не заканчивается на разделителе каталога, но также обрабатывает нормализацию пути. Остаток можно получить с помощью lastPathPart(path) proc.

См. также:

• relativePath proc
• splitPath proc
• tailDir proc
• parentDirs iterator

Пример:

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"

Исходный код Редактировать

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

Преобразует path в путь, относительный к base.

Разделитель каталогов sep (по умолчанию: osseps: DirSep) используется для нормализации путей, это может быть полезно для обеспечения того, что относительный путь содержит только '/', чтобы его можно было использовать для построения URL.

В Windows, если корень path и корень base разные, возвращает path без изменений, так как невозможно создать относительный путь. Это означает, что может быть возвращен абсолютный путь.

См. также:

• splitPath proc
• parentDir proc
• tailDir proc

Пример:

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: # On Windows, UNC-paths start with `//`
  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", '/') == "."

Исходный код Редактировать

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

Возвращает true, если оба аргумента пути указывают на один и тот же физический файл или каталог.

Вызывает OSError если любой из файлов не существует или информация о нём недоступна.

Эта процедура вернет true, если ей переданы два альтернативных жестких ссылки или символических ссылки на один и тот же файл или каталог.

См. также:

• os: sameFileContent proc

Исходный код Редактировать

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

Возвращает индекс символа '.' в path, если он обозначает начало расширения файла. В противном случае возвращает -1.

См. также:

• процедура splitFile
• процедура extractFilename
• процедура lastPathPart
• процедура changeFileExt
• процедура addFileExt

Пример:

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

Исходный код Редактировать

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

Разделяет имя файла на кортеж (dir, name, extension).

dir не заканчивается на osseps: DirSep, если это не /. extension включает ведущую точку.

Если у path нет расширения, ext — пустая строка. Если у path нет компоненты каталога, dir — пустая строка. Если у path нет компоненты имени файла, name и ext — пустые строки.

См. также:

• процедура searchExtPos
• процедура extractFilename
• процедура lastPathPart
• процедура changeFileExt
• процедура addFileExt

Пример:

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"

Исходный код Редактировать

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

Разделяет каталог на (head, tail) кортеж, так что head / tail == path (кроме крайних случаев, таких как "/usr").

См. также:

• процедура joinPath(head, tail)
• процедура joinPath(parts)
• / процедура
• /../ процедура
• процедура relativePath

Пример:

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("") == ("", "")

Исходный код Редактировать

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

Возвращает хвостовую часть path.

См. также:

• процедура relativePath
• процедура splitPath
• процедура parentDir

Пример:

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"

Исходный код Редактировать

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

Преобразует путь в стиле UNIX в локальный.

В UNIX-системах ничего не делает. В противном случае преобразует '/', '.', '..' в соответствующие значения.

В системах с концепцией «дисков» drive используется для определения метки диска, которую следует использовать при преобразовании абсолютного пути. drive по умолчанию соответствует диску текущего рабочего каталога и игнорируется в системах, не имеющих концепции «дисков».

Исходный код Редактировать

Итераторы

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

Проходит по всем родительским каталогам заданного path.

Если fromRoot равно true (по умолчанию false), обход начнется с корневого каталога файловой системы. Если inclusive равно true (по умолчанию), исходный аргумент будет включён в обход.

Относительные пути не будут расширены этим итератором. Вместо этого он будет перебирать только каталоги, отображающиеся в относительном пути.

См. также:

• процедура parentDir

Пример:

let g = "a/b/c"

for p in g.parentDirs:
  echo p
  # a/b/c
  # a/b
  # a

for p in g.parentDirs(fromRoot=true):
  echo p
  # a/
  # a/b/
  # a/b/c

for p in g.parentDirs(inclusive=false):
  echo p
  # a/b
  # a

Исходный код Редактировать