This module contains basic operating system facilities like retrieving environment variables, reading command line arguments, working with directories, running shell commands, etc.
Types
ReadEnvEffect = object of ReadIOEffect
- effect that denotes a read from an environment variable Source
WriteEnvEffect = object of WriteIOEffect
- effect that denotes a write to an environment variable Source
ReadDirEffect = object of ReadIOEffect
- effect that denotes a write operation to the directory structure Source
WriteDirEffect = object of WriteIOEffect
- effect that denotes a write operation to the directory structure Source
OSErrorCode = distinct int32
- Specifies an OS Error Code. Source
FilePermission = enum fpUserExec, ## execute access for the file owner fpUserWrite, ## write access for the file owner fpUserRead, ## read access for the file owner fpGroupExec, ## execute access for the group fpGroupWrite, ## write access for the group fpGroupRead, ## read access for the group fpOthersExec, ## execute access for others fpOthersWrite, ## write access for others fpOthersRead ## read access for others
- file access permission; modelled after UNIX Source
PathComponent = enum pcFile, ## path refers to a file pcLinkToFile, ## path refers to a symbolic link to a file pcDir, ## path refers to a directory pcLinkToDir ## path refers to a symbolic link to a directory
- Enumeration specifying a path component. Source
DeviceId = Dev
- Source
FileId = Ino
- Source
FileInfo = object id*: tuple[device: DeviceId, file: FileId] kind*: PathComponent size*: BiggestInt permissions*: set[FilePermission] linkCount*: BiggestInt lastAccessTime*: Time lastWriteTime*: Time creationTime*: Time
- Contains information associated with a file object. Source
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 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 DirSep = '/'
- The character used by the operating system to separate pathname components, for example, '/' for POSIX or ':' for the classic Macintosh. Source
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
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
FileSystemCaseSensitive = true
- true if the file system is case sensitive, false otherwise. Used by cmpPaths to compare filenames properly. Source
ExeExt = ""
- The file extension of native executables. For example: "" for POSIX, "exe" on Windows. Source
ScriptExt = ""
- The file extension of a script file. For example: "" for POSIX, "bat" on Windows. Source
DynlibFormat = "lib$1.so"
- The format string to turn a filename into a DLL file (also called on some operating systems). Source
ExtSep = '.'
- The character which separates the base filename from the extension; for example, the '.' in os.nim. Source
Procs
proc joinPath(head, tail: string): string {.noSideEffect, gcsafe, 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 proc joinPath(parts: varargs[string]): string {.noSideEffect, gcsafe, 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
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 proc splitPath(path: string): tuple[head, tail: string] {.noSideEffect, gcsafe, 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 proc parentDir(path: string): string {.noSideEffect, gcsafe, 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
Example: parentDir("/usr/local/bin/") == "/usr/local". proc tailDir(path: string): string {.noSideEffect, gcsafe, extern: "nos$1", raises: [], tags: [].}
-
Returns the tail part of path..
Example: tailDir("/usr/local/bin") == "local/bin".
Source
Example: tailDir("usr/local/bin/") == "local/bin".
Example: tailDir("bin") == "". proc isRootDir(path: string): bool {.noSideEffect, gcsafe, extern: "nos$1", raises: [], tags: [].}
- Checks whether a given path is a root directory Source
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
proc splitFile(path: string): tuple[dir, name, ext: string] {.noSideEffect, gcsafe, 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 proc extractFilename(path: string): string {.noSideEffect, gcsafe, extern: "nos$1", raises: [], tags: [].}
- Extracts the filename of a given path. This is the same as name & ext from splitFile(path). Source
proc changeFileExt(filename, ext: string): string {.noSideEffect, gcsafe, 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 proc addFileExt(filename, ext: string): string {.noSideEffect, gcsafe, 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 proc cmpPaths(pathA, pathB: string): int {.noSideEffect, gcsafe, 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
< 0 iff pathA < pathB
> 0 iff pathA > pathB proc isAbsolute(path: string): bool {.gcsafe, noSideEffect, extern: "nos$1", raises: [], tags: [].}
-
Checks whether a given path is absolute.
On Windows, network paths are considered absolute too.
Source proc unixToNativePath(path: string; drive = ""): string {.noSideEffect, gcsafe, 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 proc osErrorMsg(): string {.gcsafe, extern: "nos$1", deprecated, raises: [], tags: [].}
-
Retrieves the operating system's error flag, errno. On Windows GetLastError is checked before errno. Returns "" if no error occurred.
Deprecated since version 0.9.4: use the other osErrorMsg proc.
Source proc raiseOSError(msg: string = "") {.noinline, gcsafe, extern: "nos$1", deprecated, raises: [OSError], tags: [].}
-
raises an OSError exception with the given message msg. If msg == "", the operating system's error flag (errno) is converted to a readable error message. On Windows GetLastError is checked before errno. If no error flag is set, the message unknown OS error is used.
Deprecated since version 0.9.4: use the other raiseOSError proc.
Source proc `==`(err1, err2: OSErrorCode): bool {.borrow.}
- Source
proc `$`(err: OSErrorCode): string {.borrow.}
- Source
proc osErrorMsg(errorCode: OSErrorCode): string {.raises: [], tags: [].}
-
Converts an OS error code into a human readable string.
The error code can be retrieved using the osLastError proc.
If conversion fails, or errorCode is 0 then "" will be returned.
On Windows, the -d:useWinAnsi compilation flag can be used to make this procedure use the non-unicode Win API calls to retrieve the message.
Source proc raiseOSError(errorCode: OSErrorCode; additionalInfo = "") {.noinline, raises: [OSError], tags: [].}
-
Raises an OSError exception. The errorCode will determine the message, osErrorMsg will be used to get this message.
The error code can be retrieved using the osLastError proc.
If the error code is 0 or an error message could not be retrieved, the message unknown OS error will be used.
Source proc osLastError(): OSErrorCode {.raises: [], tags: [].}
-
Retrieves the last operating system error code.
This procedure is useful in the event when an OS call fails. In that case this procedure will return the error code describing the reason why the OS call failed. The OSErrorMsg procedure can then be used to convert this code into a string.
Warning: The behaviour of this procedure varies between Windows and POSIX systems. On Windows some OS calls can reset the error code to 0 causing this procedure to return 0. It is therefore advised to call this procedure immediately after an OS call fails. On POSIX systems this is not a problem.
Source proc existsFile(filename: string): bool {.gcsafe, extern: "nos$1", tags: [ReadDirEffect], raises: [].}
- Returns true if the file exists, false otherwise. Source
proc existsDir(dir: string): bool {.gcsafe, extern: "nos$1", tags: [ReadDirEffect], raises: [].}
- Returns true iff the directory dir exists. If dir is a file, false is returned. Source
proc symlinkExists(link: string): bool {.gcsafe, extern: "nos$1", tags: [ReadDirEffect], raises: [].}
- Returns true iff the symlink link exists. Will return true regardless of whether the link points to a directory or file. Source
proc fileExists(filename: string): bool {.inline, raises: [], tags: [ReadDirEffect].}
- Synonym for existsFile Source
proc dirExists(dir: string): bool {.inline, raises: [], tags: [ReadDirEffect].}
- Synonym for existsDir Source
proc getLastModificationTime(file: string): Time {.gcsafe, extern: "nos$1", raises: [OSError], tags: [].}
- Returns the file's last modification time. Source
proc getLastAccessTime(file: string): Time {.gcsafe, extern: "nos$1", raises: [OSError], tags: [].}
- Returns the file's last read or write access time. Source
proc getCreationTime(file: string): Time {.gcsafe, extern: "nos$1", raises: [OSError], tags: [].}
-
Returns the file's creation time.
Note: Under POSIX OS's, the returned time may actually be the time at which the file's attribute's were last modified. See here for details.
Source proc fileNewer(a, b: string): bool {.gcsafe, extern: "nos$1", raises: [OSError], tags: [].}
- Returns true if the file a is newer than file b, i.e. if a's modification time is later than b's. Source
proc getCurrentDir(): string {.gcsafe, extern: "nos$1", tags: [], raises: [OSError].}
- Returns the current working directory. Source
proc setCurrentDir(newDir: string) {.inline, tags: [], raises: [OSError].}
- Sets the current working directory; OSError is raised if newDir cannot been set. Source
proc expandFilename(filename: string): string {.gcsafe, extern: "nos$1", tags: [ReadDirEffect], raises: [OSError].}
- Returns the full path of filename, raises OSError in case of an error. Source
proc sameFile(path1, path2: string): bool {.gcsafe, extern: "nos$1", tags: [ReadDirEffect], raises: [OSError].}
-
Returns true if both pathname arguments refer to the same physical file or directory. Raises an exception 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.
Source proc sameFileContent(path1, path2: string): bool {.gcsafe, extern: "nos$1", tags: [ReadIOEffect], raises: [Exception].}
- Returns true if both pathname arguments refer to files with identical binary content. Source
proc getFilePermissions(filename: string): set[FilePermission] {.gcsafe, extern: "nos$1", tags: [ReadDirEffect], raises: [OSError].}
- retrieves file permissions for filename. OSError is raised in case of an error. On Windows, only the readonly flag is checked, every other permission is available in any case. Source
proc setFilePermissions(filename: string; permissions: set[FilePermission]) {. gcsafe, extern: "nos$1", tags: [WriteDirEffect], raises: [OSError].}
- sets the file permissions for filename. OSError is raised in case of an error. On Windows, only the readonly flag is changed, depending on fpUserWrite. Source
proc copyFile(source, dest: string) {.gcsafe, extern: "nos$1", tags: [ReadIOEffect, WriteIOEffect], raises: [OSError, Exception].}
-
Copies a file from source to dest.
If this fails, OSError is raised. On the Windows platform this proc will copy the source file's attributes into dest. On other platforms you need to use getFilePermissions() and setFilePermissions() to copy them by hand (or use the convenience copyFileWithPermissions() proc), otherwise dest will inherit the default permissions of a newly created file for the user. If dest already exists, the file attributes will be preserved and the content overwritten.
Source proc moveFile(source, dest: string) {.gcsafe, extern: "nos$1", tags: [ReadIOEffect, WriteIOEffect], raises: [OSError].}
- Moves a file from source to dest. If this fails, OSError is raised. Source
proc removeFile(file: string) {.gcsafe, extern: "nos$1", tags: [WriteDirEffect], raises: [OSError].}
- Removes the file. If this fails, OSError is raised. This does not fail if the file never existed in the first place. On Windows, ignores the read-only attribute. Source
proc execShellCmd(command: string): int {.gcsafe, extern: "nos$1", tags: [ExecIOEffect], raises: [].}
-
Executes a shell command.
Command has the form 'program args' where args are the command line arguments given to program. The proc returns the error code of the shell when it has finished. The proc does not return until the process has finished. To execute a program without having a shell involved, use the execProcess proc of the osproc module.
Source proc getEnv(key: string): TaintedString {.tags: [ReadEnvEffect], raises: [].}
-
Returns the value of the environment variable named key.
If the variable does not exist, "" is returned. To distinguish whether a variable exists or it's value is just "", call existsEnv(key).
Source proc existsEnv(key: string): bool {.tags: [ReadEnvEffect], raises: [].}
- Checks whether the environment variable named key exists. Returns true if it exists, false otherwise. Source
proc putEnv(key, val: string) {.tags: [WriteEnvEffect], raises: [OSError].}
- Sets the value of the environment variable named key to val. If an error occurs, EInvalidEnvVar is raised. Source
proc removeDir(dir: string) {.gcsafe, extern: "nos$1", tags: [WriteDirEffect, ReadDirEffect], gcsafe, locks: 0, raises: [OSError].}
-
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.
Source proc createDir(dir: string) {.gcsafe, extern: "nos$1", tags: [WriteDirEffect], raises: [OSError].}
-
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 path already exists because for most usages this does not indicate an error.
Source proc copyDir(source, dest: string) {.gcsafe, extern: "nos$1", tags: [WriteIOEffect, ReadIOEffect], gcsafe, locks: 0, raises: [OSError, Exception].}
-
Copies a directory from source to dest.
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. To preserve attributes recursively on these platforms use copyDirWithPermissions().
Source proc createSymlink(src, dest: string) {.raises: [OSError], tags: [].}
-
Create a symbolic link at dest which points to the item specified by src. On most operating systems, will fail if a lonk
Warning: Some OS's (such as Microsoft Windows) restrict the creation of symlinks to root users (administrators).
Source proc createHardlink(src, dest: string) {.raises: [OSError], tags: [].}
-
Create a hard link at dest which points to the item specified by src.
Warning: Most OS's restrict the creation of hard links to root users (administrators) .
Source proc parseCmdLine(c: string): seq[string] {.noSideEffect, gcsafe, extern: "nos$1", raises: [], tags: [].}
-
Splits a command line into several components; This proc is only occasionally useful, better use the parseopt module.
On Windows, it uses the following parsing rules (see http://msdn.microsoft.com/en-us/library/17w5ykft.aspx ):
- Arguments are delimited by white space, which is either a space or a tab.
- The caret character (^) is not recognized as an escape character or delimiter. The character is handled completely by the command-line parser in the operating system before being passed to the argv array in the program.
- A string surrounded by double quotation marks ("string") is interpreted as a single argument, regardless of white space contained within. A quoted string can be embedded in an argument.
- A double quotation mark preceded by a backslash (") is interpreted as a literal double quotation mark character (").
- Backslashes are interpreted literally, unless they immediately precede a double quotation mark.
- If an even number of backslashes is followed by a double quotation mark, one backslash is placed in the argv array for every pair of backslashes, and the double quotation mark is interpreted as a string delimiter.
- If an odd number of backslashes is followed by a double quotation mark, one backslash is placed in the argv array for every pair of backslashes, and the double quotation mark is "escaped" by the remaining backslash, causing a literal double quotation mark (") to be placed in argv.
On Posix systems, it uses the following parsing rules: Components are separated by whitespace unless the whitespace occurs within " or ' quotes.
Source proc copyFileWithPermissions(source, dest: string; ignorePermissionErrors = true) {. raises: [OSError, Exception, ], tags: [ReadIOEffect, WriteIOEffect, WriteDirEffect, ReadDirEffect].}
-
Copies a file from source to dest preserving file permissions.
This is a wrapper proc around copyFile(), getFilePermissions() and setFilePermissions() on non Windows platform. On Windows this proc is just a wrapper for copyFile() since that proc already copies attributes.
On non Windows systems permissions are copied after the file itself has been copied, which won't happen atomically and could lead to a race condition. If ignorePermissionErrors is true, errors while reading/setting file attributes will be ignored, otherwise will raise OSError.
Source proc copyDirWithPermissions(source, dest: string; ignorePermissionErrors = true) {. gcsafe, extern: "nos$1", tags: [WriteIOEffect, ReadIOEffect], gcsafe, locks: 0, raises: [OSError, ].}
-
Copies a directory from source to dest preserving file permissions.
If this fails, OSError is raised. This is a wrapper proc around copyDir() and copyFileWithPermissions() on non Windows platforms. On Windows this proc is just a wrapper for copyDir() 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, errors while reading/setting file attributes will be ignored, otherwise will raise OSError.
Source proc inclFilePermissions(filename: string; permissions: set[FilePermission]) {. gcsafe, extern: "nos$1", tags: [ReadDirEffect, WriteDirEffect], raises: [OSError].}
-
a convenience procedure for:
setFilePermissions(filename, getFilePermissions(filename)+permissions)
Source proc exclFilePermissions(filename: string; permissions: set[FilePermission]) {. gcsafe, extern: "nos$1", tags: [ReadDirEffect, WriteDirEffect], raises: [OSError].}
-
a convenience procedure for:
setFilePermissions(filename, getFilePermissions(filename)-permissions)
Source proc getHomeDir(): string {.gcsafe, 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 proc getConfigDir(): string {.gcsafe, extern: "nos$1", tags: [ReadEnvEffect, ReadIOEffect], raises: [].}
- Returns the config directory of the current user for applications. Source
proc getTempDir(): string {.gcsafe, extern: "nos$1", tags: [ReadEnvEffect, ReadIOEffect], raises: [].}
- Returns the temporary directory of the current user for applications to save temporary files in. Source
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 proc findExe(exe: string): 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. On DOS-like platforms, exe is added the ExeExt file extension if it has none. Source
proc expandSymlink(symlinkPath: string): string {.raises: [OSError], tags: [].}
-
Returns a string representing the path to which the symbolic link points.
On Windows this is a noop, symlinkPath is simply returned.
Source proc paramCount(): int {.tags: [ReadIOEffect], raises: [].}
-
Returns the number of command line arguments given to the application.
If your binary was called without parameters this will return zero. You can later query each individual paramater with paramStr() or retrieve all of them in one go with commandLineParams().
Availability: On Posix there is no portable way to get the command line from a DLL and thus the proc isn't defined in this environment. You can test for its availability with declared(). Example:
when declared(paramCount): # Use paramCount() here else: # Do something else!
Source proc paramStr(i: int): TaintedString {.tags: [ReadIOEffect], raises: [].}
-
Returns the i-th command line argument given to the application.
i should be in the range 1..paramCount(), the EInvalidIndex exception will be raised for invalid values. Instead of iterating over paramCount() with this proc you can call the convenience commandLineParams().
It is possible to call paramStr(0) but this will return OS specific contents (usually the name of the invoked executable). You should avoid this and call getAppFilename() instead.
Availability: On Posix there is no portable way to get the command line from a DLL and thus the proc isn't defined in this environment. You can test for its availability with declared(). Example:
when declared(paramStr): # Use paramStr() here else: # Do something else!
Source proc commandLineParams(): seq[TaintedString] {.raises: [], tags: [ReadIOEffect].}
-
Convenience proc which returns the command line parameters.
This returns only the parameters. If you want to get the application executable filename, call getAppFilename().
Availability: On Posix there is no portable way to get the command line from a DLL and thus the proc isn't defined in this environment. You can test for its availability with declared(). Example:
when declared(commandLineParams): # Use commandLineParams() here else: # Do something else!
Source proc getAppFilename(): string {.gcsafe, extern: "nos$1", tags: [ReadIOEffect], raises: [].}
-
Returns the filename of the application's executable.
This procedure will resolve symlinks.
Note: This does not work reliably on BSD.
Source proc getApplicationFilename(): string {.gcsafe, extern: "nos$1", deprecated, raises: [], tags: [ReadIOEffect].}
- Returns the filename of the application's executable. Deprecated since version 0.8.12: use getAppFilename instead. Source
proc getApplicationDir(): string {.gcsafe, extern: "nos$1", deprecated, raises: [], tags: [ReadIOEffect].}
- Returns the directory of the application's executable. Deprecated since version 0.8.12: use getAppDir instead. Source
proc getAppDir(): string {.gcsafe, extern: "nos$1", tags: [ReadIOEffect], raises: [].}
- Returns the directory of the application's executable. Note: This does not work reliably on BSD. Source
proc sleep(milsecs: int) {.gcsafe, extern: "nos$1", tags: [TimeEffect], raises: [].}
- sleeps milsecs milliseconds. Source
proc getFileSize(file: string): BiggestInt {.gcsafe, extern: "nos$1", tags: [ReadIOEffect], raises: [IOError, OSError].}
- returns the file size of file. Can raise OSError. Source
proc getFileInfo(handle: FileHandle): FileInfo {.raises: [OSError], tags: [].}
-
Retrieves file information for the file object represented by the given handle.
If the information cannot be retrieved, such as when the file handle is invalid, an error will be thrown.
Source proc getFileInfo(file: File): FileInfo {.raises: [IOError, OSError], tags: [].}
- Source
proc getFileInfo(path: string; followSymlink = true): FileInfo {.raises: [OSError], tags: [].}
-
Retrieves file information for the file object pointed to by path.
Due to intrinsic differences between operating systems, the information contained by the returned FileInfo structure will be slightly different across platforms, and in some cases, incomplete or inaccurate.
When followSymlink is true, symlinks are followed and the information retrieved is information related to the symlink's target. Otherwise, information on the symlink itself is retrieved.
If the information cannot be retrieved, such as when the path doesn't exist, or when permission restrictions prevent the program from retrieving file information, an error will be thrown.
Source proc isHidden(path: string): bool {.raises: [], tags: [ReadDirEffect].}
-
Determines whether a given path is hidden or not. Returns false if the file doesn't exist. The given path must be accessible from the current working directory of the program.
On Windows, a file is hidden if the file's 'hidden' attribute is set. On Unix-like systems, a file is hidden if it starts with a '.' (period) and is not just '.' or '..' ' ."
Source
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 iterator envPairs(): tuple[key, value: TaintedString] {.tags: [ReadEnvEffect], raises: [].}
- Iterate over all environments variables. In the first component of the tuple is the name of the current variable stored, in the second its value. Source
iterator walkFiles(pattern: string): string {.tags: [ReadDirEffect], raises: [].}
-
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.
Source iterator walkDir(dir: string; relative = false): tuple[kind: PathComponent, path: string] {. tags: [ReadDirEffect], raises: [].}
-
walks over the directory dir and yields for each directory or file in dir. The component type and full path for each item is returned. Walking is not recursive. If relative is true the resulting path is shortened to be relative to dir. Example: This directory structure:
dirA / dirB / fileB1.txt / dirC / fileA1.txt / fileA2.txt
and this code:
for kind, path in walkDir("dirA"): echo(path)
produces this output (but not necessarily in this order!):
dirA/dirB dirA/dirC dirA/fileA1.txt dirA/fileA2.txt
Source iterator walkDirRec(dir: string; filter = {pcFile, pcDir}): string {. tags: [ReadDirEffect], raises: [].}
-
walks over the directory dir and yields for each file in dir. The full path for each file is returned. Warning: Modifying the directory structure while the iterator is traversing may result in undefined behavior!
Walking is recursive. filter controls the behaviour of the iterator:
Sourcefilter meaning pcFile yield real files pcLinkToFile yield symbolic links to files pcDir follow real directories pcLinkToDir follow symbolic links to directories