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 as Str)

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

Rename(sourcepath as Str, targetpath as Str)

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

MakeDir(path as Str)

Create a directory. Raise IoError if the directory already exists.

MakeDirs(path as Str)

Create a directory and any missing parent directories. If the directory already exists or if the argument is an empty string, do nothing. Example:

MakeDirs("dir1/dir2")  -- Create both dir1 and dir1/dir2 (if they don't exist)

ChangeDir(path as Str)

Change the current working directory.

CurrentDir() as Str

Return the current working directory.

Exists(path as Str) as Boolean

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 as Str) as Boolean

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

IsFile(path as Str) as Boolean

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

IsLink(path as Str) as Boolean

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

ListDir(path as Str[, mask as Str]) as Array<Str>

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 as Str[, mask as Str]) as Array<Str>

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

MakeSymLink(sourcepath as Str, linkpath as Str)

Create a symbolic link at the target path that points to the source.

ReadSymLink(path as Str) as Str

Return the path to which a symbolic link points.

Note: Symbolic links are not supported in Windows; the above two functions just raise RuntimeError.

Path operations

Join(component as Str, ...) as Str

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

Join("work", "texts")  -- Result: "work/texts" (Posix) or
                       --         "work\texts" (Windows)
Join("/usr/bin", "ls") -- Result: "/usr/bin/ls" (Posix)
Join("a\", "b\c")      -- Result: "a\b\c" (Windows)

DirName(path as Str) as Str

Return the directory portion of a path, i.e. the last component 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 as Str) as Str

Return the last component in a path. Example:

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

FileExt(path as Str) as Str

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 as Str) as Str

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 as Str) as Boolean

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

NormPath(path as Str) as Str

Normalize a path. Convert all directory separators to the canonical ones. Remove extra directory separators and unnecessary . and .. path components. Example:

NormPath("./foo//bar/../x") -- Result: "foo/x" (Posix)

Note: The returned path may refer to a different location if some path components are symbolic links, as symbolic links receive no special processing.

AbsPath(path as Str) as Str

Convert the path to a normalized absolute path.

Note: Symbolic links are not recognized, as with NormPath.

ExpandUser(path as Str) as Str

Replace a ~ or ~user prefix in the path with the home directory of a user (the current user for ~). Return the path unmodified if there is no prefix or if unsuccessful. On Posix systems consult the HOME environment variable and, failing that, the password database.

Path constants

Separator as Str

The path name component separator of the operating system ("/" for Posix and "\" for Windows).

AltSeparator as Str

The alternate path name component separator, or nil if only one separator exists ("/" for Windows and nil for other operating systems).

PathSeparator as Str

The separator used in the PATH environment variable (":" for Posix and ";" for Windows).

Class Stat

class Stat(path as Str)

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 as Int

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

isFile as Boolean

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

isDir as Boolean

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

isLink as Boolean

Boolean indicating whether the path refers to a symbolic link.

isSpecial as Boolean

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 as Str

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 as Str

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 as Boolean

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

isWritable as Boolean

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

owner as Str

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

ownerPerm as Str

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 as Str

Access permissions for other users. The format is the same as for ownerPerm.

groupPerm as Str

Access permissions for the group of the file. The format is the same as for ownerPerm.

File status change operations

SetPerm(path as Str, owner as Str[, other as Str[, group as Str]])

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. Group permissions default to other user permissions.

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

SetModificationTime(path as Str, datetime)

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

SetAccessTime(path as Str, datetime)

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

Miscellaneous operations

GetEnv(variable as Str[, default as Str]) as Str

Return the value of an environment variable, or default if the environment variable is not defined. If default is not given, it defaults to nil. Both the variable and the value are strings.

SetEnv(variable as Str, value as Str)

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() as Array<Str>

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

System(command as Str) as Int

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 as Int)

Sleep(seconds as Float)

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

User() as Str

Return the login user name of the current user.