Types
ReadEnvEffect = object of ReadIOEffect
- effect that denotes a read from an environment variable Source Edit
WriteEnvEffect = object of WriteIOEffect
- effect that denotes a write to an environment variable Source Edit
ReadDirEffect = object of ReadIOEffect
- effect that denotes a write operation to the directory structure Source Edit
WriteDirEffect = object of WriteIOEffect
- effect that denotes a write operation to the directory structure Source Edit
OSErrorCode = distinct int32
- Specifies an OS Error Code. Source Edit
Consts
CurDir = '.'
-
The constant string used by the operating system to refer to the current directory.
For example: '.' for POSIX or ':' for the classic Macintosh.
Source Edit ParDir = ".."
-
The constant string used by the operating system to refer to the parent directory.
For example: ".." for POSIX or "::" for the classic Macintosh.
Source Edit DirSep = '/'
- The character used by the operating system to separate pathname components, for example, '/' for POSIX or ':' for the classic Macintosh. Source Edit
AltSep = '/'
- An alternative character used by the operating system to separate pathname components, or the same as DirSep if only one separator character exists. This is set to '/' on Windows systems where DirSep is a backslash. Source Edit
PathSep = ':'
- The character conventionally used by the operating system to separate search patch components (as in PATH), such as ':' for POSIX or ';' for Windows. Source Edit
FileSystemCaseSensitive = true
- true if the file system is case sensitive, false otherwise. Used by cmpPaths to compare filenames properly. Source Edit
ExeExt = ""
- The file extension of native executables. For example: "" for POSIX, "exe" on Windows. Source Edit
ScriptExt = ""
- The file extension of a script file. For example: "" for POSIX, "bat" on Windows. Source Edit
DynlibFormat = "lib$1.so"
- The format string to turn a filename into a DLL file (also called on some operating systems). Source Edit
ExtSep = '.'
- The character which separates the base filename from the extension; for example, the '.' in os.nim. Source Edit
ExeExts = [""]
- platform specific file extension for executables. On Windows ["exe", "cmd", "bat"], on Posix [""]. Source Edit
Procs
proc joinPath(head, tail: string): string {.
noSideEffect, extern: "nos$1", raises: [], tags: [].}-
Joins two directory names to one.
For example on Unix:
joinPath("usr", "lib")
results in:
"usr/lib"
If head is the empty string, tail is returned. If tail is the empty string, head is returned with a trailing path separator. If tail starts with a path separator it will be removed when concatenated to head. Other path separators not located on boundaries won't be modified. More examples on Unix:
assert joinPath("usr", "") == "usr/" assert joinPath("", "lib") == "lib" assert joinPath("", "/lib") == "/lib" assert joinPath("usr/", "/lib") == "usr/lib"
Source Edit proc joinPath(parts: varargs[string]): string {.
noSideEffect, extern: "nos$1OpenArray", raises: [], tags: [].}- The same as joinPath(head, tail), 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. Source Edit
proc `/`(head, tail: string): string {.
noSideEffect, raises: [], tags: [].}-
The same as joinPath(head, tail)
Here are some examples for Unix:
assert "usr" / "" == "usr/" assert "" / "lib" == "lib" assert "" / "/lib" == "/lib" assert "usr/" / "/lib" == "usr/lib"
Source Edit proc splitPath(path: string): tuple[head, tail: string] {.
noSideEffect, extern: "nos$1", raises: [], tags: [].}-
Splits a directory into (head, tail), so that head / tail == path (except for edge cases like "/usr").
Examples:
splitPath("usr/local/bin") -> ("usr/local", "bin") splitPath("usr/local/bin/") -> ("usr/local/bin", "") splitPath("bin") -> ("", "bin") splitPath("/bin") -> ("", "bin") splitPath("") -> ("", "")
Source Edit proc parentDir(path: string): string {.
noSideEffect, extern: "nos$1", raises: [], tags: [].}-
Returns the parent directory of path.
This is often the same as the head result of splitPath. If there is no parent, "" is returned.
Example: parentDir("/usr/local/bin") == "/usr/local".
Source Edit
Example: parentDir("/usr/local/bin/") == "/usr/local". proc tailDir(path: string): string {.
noSideEffect, extern: "nos$1", raises: [], tags: [].}-
Returns the tail part of path..
Example: tailDir("/usr/local/bin") == "local/bin".
Source Edit
Example: tailDir("usr/local/bin/") == "local/bin".
Example: tailDir("bin") == "". proc isRootDir(path: string): bool {.
noSideEffect, extern: "nos$1", raises: [], tags: [].}- Checks whether a given path is a root directory Source Edit
proc `/../`(head, tail: string): string {.
noSideEffect, raises: [], tags: [].}- The same as parentDir(head) / tail unless there is no parent directory. Then head / tail is performed instead. Source Edit
proc splitFile(path: string): tuple[dir, name, ext: string] {.
noSideEffect, extern: "nos$1", raises: [], tags: [].}-
Splits a filename into (dir, filename, extension). dir does not end in DirSep. extension includes the leading dot.
Example:
var (dir, name, ext) = splitFile("usr/local/nimc.html") assert dir == "usr/local" assert name == "nimc" assert ext == ".html"
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.
Source Edit proc extractFilename(path: string): string {.
noSideEffect, extern: "nos$1", raises: [], tags: [].}- Extracts the filename of a given path. This is the same as name & ext from splitFile(path). Source Edit
proc changeFileExt(filename, ext: string): string {.
noSideEffect, extern: "nos$1", raises: [], tags: [].}-
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.)
Source Edit proc addFileExt(filename, ext: string): string {.
noSideEffect, extern: "nos$1", raises: [], tags: [].}-
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.)
Source Edit proc cmpPaths(pathA, pathB: string): int {.
noSideEffect, extern: "nos$1", raises: [], tags: [].}-
Compares two paths.
On a case-sensitive filesystem this is done case-sensitively otherwise case-insensitively. Returns:
0 iff pathA == pathB
Source Edit
< 0 iff pathA < pathB
> 0 iff pathA > pathB proc isAbsolute(path: string): bool {.
noSideEffect, extern: "nos$1", raises: [], tags: [].}-
Checks whether a given path is absolute.
On Windows, network paths are considered absolute too.
Source Edit proc unixToNativePath(path: string; drive = ""): string {.
noSideEffect, extern: "nos$1", raises: [], tags: [].}-
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 proc getHomeDir(): string {.
extern: "nos$1", tags: [ReadEnvEffect, ReadIOEffect], raises: [].}-
Returns the home directory of the current user.
This proc is wrapped by the expandTilde proc for the convenience of processing paths coming from user configuration files.
Source Edit proc getConfigDir(): string {.
extern: "nos$1", tags: [ReadEnvEffect, ReadIOEffect], raises: [].}- Returns the config directory of the current user for applications. Source Edit
proc getTempDir(): string {.
extern: "nos$1", tags: [ReadEnvEffect, ReadIOEffect], raises: [].}- Returns the temporary directory of the current user for applications to save temporary files in. Source Edit
proc expandTilde(path: string): string {.
tags: [ReadEnvEffect, ReadIOEffect], raises: [].}-
Expands a path starting with ~/ to a full path.
If path starts with the tilde character and is followed by / or \ this proc will return the reminder of the path appended to the result of the getHomeDir() proc, otherwise the input path will be returned without modification.
The behaviour of this proc is the same on the Windows platform despite not having this convention. Example:
let configFile = expandTilde("~" / "appname.cfg") echo configFile # --> C:\Users\amber\appname.cfg
Source Edit proc findExe(exe: string; followSymlinks: bool = true; extensions = ExeExts): string {.
tags: [ReadDirEffect, ReadEnvEffect, ReadIOEffect], raises: [].}- Searches for exe in the current working directory and then in directories listed in the PATH environment variable. Returns "" if the exe cannot be found. exe is added the ExeExts file extensions if it has none. If the system supports symlinks it also resolves them until it meets the actual file. This behavior can be disabled if desired. Source Edit
Iterators
iterator parentDirs(path: string; fromRoot = false; inclusive = true): string {.
raises: [], tags: [].}-
Walks over all parent directories of a given path
If fromRoot is set, the traversal will start from the file system root diretory. If inclusive is set, the original argument will be included in the traversal.
Relative paths won't be expanded by this proc. Instead, it will traverse only the directories appearing in the relative path.
Source Edit