`os`: Operating system services

This module provides basic operating system services such as file and directory manipulation. The path arguments expected by many operations must be strings. The functions in this module raise std::IoError on error conditions.

See also: File input/output is included in the io module.

File and directory operations

Remove(path)

Remove a file or a directory. Only an empty directory can be removed.

Rename(sourcepath, targetpath)

Rename a file or a directory. The operation may fail if the source and target directories differ.

MakeDir(path)

Create a directory.

ChangeDir(path)

Change the current working directory.

CurrentDir()

Return the current working directory.

Exists(path)

Return a boolean indicating whether the path target exists. The path target may be a file, a directory, a symbolic link or a special directory entry such as a device.

IsDir(path)

Return a boolean indicating whether the path refers to a directory or a symbolic link to a directory.

IsFile(path)

Return a boolean indicating whether the path refers to an ordinary file or a symbolic link to an ordinary file.

IsLink(path)

Return a boolean indicating whether the path refers to a symbolic link.

ListDir(path[, mask])

Return the names of the directory entries in the directory as an array. The "." and ".." directory entries are omitted. The order of the entries is arbitrary.

If the mask is specified, only entries whose names match the file mask are included. The mask may contain the wild cards * and ?. * matches any substring and ? matches any character in the entry names.

WalkDir(path[, mask])

Return the names of the directory entries in the directory and recursively in all subdirectories as an array. The "." and ".." directory entries are omitted. The entries are ordered so that contents of a directory are directly after the directory entry. Otherwise, the order of the entries is arbitrary. The entries in subdirectories include the relative path from the initial directory.

If the mask is specified, only entries whose names match the file mask are included. The mask may contain the wild cards * and ?. The mask does not affect descending into subdirectories.

As an example, the call

WalkDir("/home/mary", "*.doc")

may produce the result

["essay.doc", "work/study plan.doc"]

Stat class

class Stat(path): Construct an object containing information on the path target. Raise an std::IoError if the path target does not exist.

Stat members

Stat has the following constant members:

size

Size of the file, in bytes. If the path refers to a directory or a special file, the value is undefined.

isFile

Boolean indicating whether the path refers to an ordinary file or a symbolic link to an ordinary file.

isDir

Boolean indicating whether the path refers to a directory or a symbolic link to a directory.

isLink

Boolean indicating whether the path refers to a symbolic link.

isSpecial

Boolean indicating whether the path refers to a special file. Special files are operating system dependent. Typical special files are Unix device files such as /dev/null.

modificationTime

Last modification time of the path target as a string of form "YYYY-MM-DD hh:mm:ss" (optionally followed by a fraction). It is suitable for passing to the time::DateTime constructor. Example:

var s = Stat("file.ext")
var t = DateTime(s.modificationTime)

accessTime

Last access time of the path target as a string of form "YYYY-MM-DD hh:mm:ss" (optionally followed by a fraction). It is suitable for passing to the time::DateTime constructor.

isReadable

Boolean indicating whether the path target is readable by the current user.

isWritable

Boolean indicating whether the path target is writable by the current user.

owner

User name of the path target owner. The value is an empty string if there is no owner.

ownerPerm

Access permissions for the owner of the path target. This is a string that may contain some of these characters: r for read access, w for write access and x for executable access, in that order.

otherPerm

Access permissions for other users. The format of the contents is similar to ownerPerm.

Path operations

DirName(path)

Return the directory portion of a path, i.e. the last element in the path is removed. The return value does not have a trailing directory separator unless the value refers to the root directory. Example:

DirName("/usr/bin") -- Result: "/usr"

BaseName(path)

Return the last element in a path. Example:

BaseName("/usr/bin") -- Result: "bin"

FileExt(path)

Return the file extension of a path. The dot in the extension is included. If there is no extension, return an empty string. If there are multiple extensions, only the last one is returned. Examples:

FileExt("/usr/bin")             -- Result: ""
FileExt("/home/mary/essay.doc") -- Result: ".doc"
FileExt("archive.tar.gz")       -- Result: ".gz"

FileBase(path)

Return the path without the file extension. If there is no extension, return the path unmodified. If there are multiple extensions, only the last one is removed. Example:

FileBase("work/essay.doc") -- Result: "work/essay"

IsAbs(path)

Return a boolean indicating whether the path is absolute (i.e. not relative to the current working directory).

JoinPath(component, ...)

Join one or more path components with the path separator character ("/" or "\"). Examples:

JoinPath("work", "texts")  -- Result: "work/texts" (Posix) or
                           --         "work\texts" (Windows)
JoinPath("/usr/bin", "ls") -- Result: "/usr/bin/ls" (Posix)

Path constants

DirSeparator: The default directory separator ("/" or "\").
PathSeparator: The separator used in the PATH environment variable (":" or ";").

File status change operations

SetPerm(path, owner[, other])

Change the permissions of a directory entry. Permissions are defined using a string which may have any subset of the characters r (read permission), w (write permission) and x (execute permission). If only owner permissions are specified, other users will receive the same permissions minus write permission.

SetPerm("essay.txt", "rw", "")  -- Owner will receive read and write
                                -- access, others cannot access at all.

Note: Under a Posix system, group will receive the same permissions as other users.

SetModificationTime(path, datetime)

Change the modification time of a directory entry. The datetime parameter must be compatible with the time::DateTime class.

SetAccessTime(path, datetime)

Change the access time of a directory entry. The datetime parameter must be compatible with the time::DateTime class.

Miscellaneous operations

GetEnv(variable)

Return the value of an environment variable. Both the variable and the value are strings.

SetEnv(variable, value)

Change the value of an environment variable. Both the variable and the value should be strings. As an exception, if the value is nil, remove the variable from the environment.

ListEnv()

Return an array containing the names of all environment variables in the current environment.

System(command)

Execute a shell command and return the status of the command. The execution of the current thread is paused until the command has finished executing. Example:

System("ls > list.txt")

Note: The syntax of shell commands depends on the current operating system.

Sleep(seconds)

Pause for the specified number of seconds. The seconds may be an integer or a float. Only the current thread is paused.

User()

Return the login user name of the current user.

os: Operating system services