@head @module os @title 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 @ref{std::IoError} on error conditions. @see File input/output is included in the @ref{io} module. @end
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.
@end
@fun WalkDir(path as Str[, mask as Str]) as Array 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
@example
WalkDir("/home/mary", "*.doc")
@end
may produce the result
@example
["essay.doc", "work/study plan.doc"]
@end
@end
@fun MakeSymLink(sourcepath as Str, linkpath as Str)
@desc Create a symbolic link at the target path that points to the source.
@end
@fun ReadSymLink(path as Str) as Str
@desc Return the path to which a symbolic link points.
@end
@note Symbolic links are not supported in Windows; the above two functions
just raise @ref{RuntimeError}.
@end
Stat has the following constant members:
@var size as Int
@desc Size of the file, in bytes. If the path refers to a directory or a
special file, the value is undefined.
@end
@var isFile as Boolean
@desc Boolean indicating whether the path refers to an ordinary file or a
symbolic link to an ordinary file.
@end
@var isDir as Boolean
@desc Boolean indicating whether the path refers to a directory or a symbolic
link to a directory.
@end
@var isLink as Boolean
@desc Boolean indicating whether the path refers to a symbolic link.
@end
@var isSpecial as Boolean
@desc 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.
@end
@var modificationTime as Str
@desc 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 @ref{time::DateTime} constructor.
Example:
@example
var s = Stat("file.ext")
var t = DateTime(s.modificationTime)
@end
@end
@var accessTime as Str
@desc 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 @ref{time::DateTime} constructor.
@end
@var isReadable as Boolean
@desc Boolean indicating whether the path target is readable by the current
user.
@end
@var isWritable as Boolean
@desc Boolean indicating whether the path target is writable by the
current user.
@end
@var owner as Str
@desc User name of the path target owner. The value is an empty string if
there is no owner.
@end
@var ownerPerm as Str
@desc 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.
@end
@var otherPerm as Str
@desc Access permissions for other users. The format is the same as for
ownerPerm.
@end
@var groupPerm as Str
@desc Access permissions for the group of the file. The format is the same
as for ownerPerm.
@end
@end-class
Path operations
@fun Join(component as Str, ...) as Str
@desc Join one or more path components with the directory separator character
("/" or "\"). Examples:
@example
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)
@end
@end
@fun DirName(path as Str) as Str
@desc 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:
@example
DirName("/usr/bin") -- Result: "/usr"
@end
@end
@fun BaseName(path as Str) as Str
@desc Return the last component in a path. Example:
@example
BaseName("/usr/bin") -- Result: "bin"
@end
@end
@fun FileExt(path as Str) as Str
@desc 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:
@example
FileExt("/usr/bin") -- Result: ""
FileExt("/home/mary/essay.doc") -- Result: ".doc"
FileExt("archive.tar.gz") -- Result: ".gz"
@end
@end
@fun FileBase(path as Str) as Str
@desc 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:
@example
FileBase("work/essay.doc") -- Result: "work/essay"
@end
@end
@fun IsAbs(path as Str) as Boolean
@desc Return a boolean indicating whether the path is absolute (i.e. not
relative to the current working directory).
@end
@fun NormPath(path as Str) as Str
@desc Normalize a path. Convert all directory separators to the canonical
ones. Remove extra directory separators and unnecessary
. and .. path components. Example:
@example
NormPath("./foo//bar/../x") -- Result: "foo/x" (Posix)
@end
@note The returned path may refer to a different location if some
path components are symbolic links, as
symbolic links receive no special processing.
@end
@end
@fun AbsPath(path as Str) as Str
@desc Convert the path to a normalized absolute path.
@note Symbolic links are not recognized, as with @ref{NormPath}.
@end
@end
@fun ExpandUser(path as Str) as Str
@desc 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.
@end
Path constants
@var Separator as Str
@desc The path name component separator of the operating system ("/"
for Posix and "\" for Windows).
@end
@var AltSeparator as Str
@desc The alternate path name component separator, or nil if only
one separator exists ("/" for Windows and nil
for other operating systems).
@end
@var PathSeparator as Str
@desc The separator used in the PATH environment variable (":" for
Posix and ";" for Windows).
@end
Class Stat
@class Stat(path as Str)
@desc Construct an object containing information on the path target. Raise an
@ref{std::IoError} if the path target does not exist.
@end
Stat members
File status change operations
@fun SetPerm(path as Str, owner as Str[, other as Str[, group as Str]])
@desc 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.
@example
SetPerm("essay.txt", "rw", "") -- Owner will receive read and write
-- access, others cannot access at all.
@end
@end
@fun SetModificationTime(path as Str, datetime)
@desc Change the modification time of a directory entry. The datetime
parameter must be compatible with the @ref{time::DateTime} class.
@end
@fun SetAccessTime(path as Str, datetime)
@desc Change the access time of a directory entry. The datetime
parameter must be compatible with the @ref{time::DateTime} class.
@end
Miscellaneous operations
@fun GetEnv(variable as Str[, default as Str]) as Str
@desc 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.
@end
@fun SetEnv(variable as Str, value as Str)
@desc 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.
@end
@fun ListEnv() as Array