MODULE IO @public

summary

Classes, Interfaces and methods for Input/Output. Operations on files and directories.

Stdin, stdout and stderr can be used for normal input and output. The most common methods on these are also available directly.

INTERFACE	I_ByteWriter @public	An interface for any class that can write a byte.
INTERFACE	I_CharWriter @public	An interface for any class that can write a character.
INTERFACE	I_Writer @public	An interface for any class that can write a string.
CLASS	Writer @public	Abstract class that implements I_Writer while only requiring subclasses to implement write(string) by providing the writeByte(), writeChar() and print() implementations.
CLASS	File @public	File for reading and writing.
CLASS	Socket @public	Socket for reading and writing.
CLASS	Url @public	Uniform Resource Locator
INTERFACE	I_ByteReader @public	An interface for any class that can read a byte.
INTERFACE	I_CharReader @public	An interface for any class that can read a UTF-8 character.
INTERFACE	I_CharOrByteReader @public	An interface for any class that can read a byte or a UTF-8 character.
CLASS	ByteReader @public	A ByteReader that reads from a byteString.
CLASS	ByteReaderStack @public	A wrapper around a ByteReader that supports push().
CLASS	StringReader @public	A Reader that reads characters from a string.
CLASS	CharReaderStack @public	A wrapper around a CharReader that supports push().

Methods for creating an IO.Socket object.
ENUM	SocketProtocol @public	Protocol to use for a socket.
CLASS	StringWriter @public	A Writer that stores the text in a string. Use ToString() to get the result.
CLASS	ByteWriter @public	A Writer that stores a sequence of bytes. Call toByteString() to get the result.
CLASS	FileInfo @public	Used for the return value of IO.fileInfo().

int	eof @public	End Of File
IO.File	stdin @public	Standard input.
IO.File	stdout @public	Standard output.
IO.File	stderr @public	Standard error output.

	readAllBytes(reader) byteString @public	Read all bytes from reader and return a byteString with them.
	readAllChars(reader) string @public	Read all chars from reader and return a string with them.

Methods for creating an IO.File object.
	fileReader(fileName) IO.File @public	Opens file fileName for reading.
	fileWriter(fileName, truncate) IO.File @public	Opens file fileName for writing.
	clientSocket(server, port, protocol) IO.Socket @public	Open a client socket to port on server.

Methods for reading and writing stdin and stdout
	readByte() int @public	Reads and returns one byte from stdin.
	readChar() int @public	Reads and returns one UTF-8 character from stdin.
	readFile(fileName) string @public	Reads file fileName and returns its contents as a string.
	write(text) status @public	Writes text to stdout and returns FAIL or OK.
	write(number) status @public	Writes number to stdout and returns FAIL or OK.
	write(number) status @public	Writes number to stdout and returns FAIL or OK.
	write(number) status @public	Writes number to stdout and returns FAIL or OK.
	write(flag) status @public	Writes flag as "TRUE" or "FALSE" to stdout and returns FAIL or OK.
	write(ok) status @public	Writes ok as "FAIL" or "OK" to stdout and returns FAIL or OK.
	write(arg) status @public	Writes arg depending on its actual type to stdout.
	print(text) status @public	Writes text to stdout and appends a newline.
	print(text) status @public	Writes text to stdout and appends a newline.
	print(nr) status @public	Writes nr to stdout and appends a newline.
	print(nr) status @public	Writes nr to stdout and appends a newline.
	print(nr) status @public	Writes nr to stdout and appends a newline.
	print(flag) status @public	Writes flag to stdout as "FALSE" or "TRUE" and appends a newline.
	print(ok) status @public	Writes ok to stdout as "FAIL" or "OK" and appends a newline.
	print(arg) status @public	Writes arg to stdout depending on its actual type.
	print() status @public	Writes a newline to stdout.
	format(fmt, arguments) status @public	Formats the string and writes it to stdout with a newline.
	writeByte(byte) status @public	Writes byte byte to stdout.
	writeChar(char) status @public	Writes character char to stdout as an UTF-8 byte sequence.
	flush() status @public	Flushes buffered output on stdout.

Methods for file properties
	fileInfo(name) IO.FileInfo @public	Return statistics for name.
	isDirectory(name) bool @public	Returns TRUE if name exists and is a directory.
	isReadable(name) bool @public	Returns TRUE if the file name exists and is readable.
	isWritable(name) bool @public	Returns TRUE if the file name exists and is writable.
	isExecutable(name) bool @public	Returns TRUE if the file name exists and is executable.

Operations involving directories.
	chdir(dirName) status @public	Change the current directory to dirName.
	getdir() string @public	Return the current directory.
	mkdir(dirName) status @public	Create directory dirName.
	rmdir(dirName) status @public	Delete directory dirName. Only works when it is empty.
	dirList(dirName) list<string> @public	Returns a list with all entries of directory dirName.

Operations on files
	delete(fileName) status @public	Delete file fileName.
	rename(fromName, toName) status @public	Rename file fromName to toName.
	move(fromName, toName) status @public	Move file fromName to toName by making a copy and deleting fromName. Not implemented yet.
	copy(fromName, toName) status @public	Copy file from to to. Not implemented yet.
	equalFiles(name1, name2) bool @public	Compare two files and return TRUE if both exist, can be read and contain the same bytes.

Operations on file names and paths.
	findExe(exeName) string @public	Finds exeName in $PATH and returns the actual location.
	findExeInDirList(exeName, dirs) string @public	Searches for exeName in each directory in dirs and returns the first one that exists and is executable.
	findFirstExe(alternatives) string @public	Find the first executable in alternatives that exists.
	modifyExeName(exeName, newName) string @public	Given an executable name returns a different executable name in the same directory.
	concatPath(first, second) string @public	Returns first and second concatenated as path parts.
	isFullPath(fname) bool @public	Returns TRUE if fname is a full (absolute) path name, the meaning
	fullPath(fname) string @public	Returns the full path of fname.
	resolve(fname) string @public	Returns fname with all symbolic links resolved.
	tailIndex(fname) int @public	Returns index of last path component in fname.
	tail(fname) string @public	Returns the last path component in fname.
	root(fname) string @public	Returns fname with the last extension removed.
	rootAll(fname) string @public	Returns fname with all extensions removed.
	directory(fname) string @public	Returns the directory name of fname.
	tailSepIndex(fname) int @public	Returns index of last path component of fname, including separator(s) before it that are not part of the head.
	pastHeadIndex(fname) int @public	Returns index of first char after leading "c:/", "/", etc. Returns 0 when no head found.
	isPathSep(c) bool @public	Returns TRUE if c is a path separator.
	nextPartIndex(fname, idx) int @public	Returns the index of the next path component, after the next separator.

members (alphabetically)

int eof @public

End Of File

Returned by readByte() and readChar() when there is no more to read.

IO.File stderr @public

Standard error output.

IO.File stdin @public

Standard input.

IO.File stdout @public

Standard output.

FUNC chdir(string dirName) status @public

Change the current directory to dirName.

Returns FAIL or OK.

FUNC clientSocket(string server, int port, IO.SocketProtocol protocol) IO.Socket @public

Open a client socket to port on server.

Returns NIL if the socket cannot be opened. Error messages are written to stderr. TODO: Add a similar method that returns an error message.

protocol specifies the protocol used. The default is TCP.

Example:

 IO.Socket socket = IO.clientSocket("freedb.org", 8880)
 IF socket == NIL
   THROW "can't open socket"
 }
 IO.print(socket.readLine())
 socket.print("cddb hello bram zimbu.org Zimbu 0.1")
 IO.print(socket.readLine())
 socket.close()

FUNC concatPath(string first, string second) string @public

Returns first and second concatenated as path parts.

Inserts a path separator when first doesn't end in one and second doesn't start with one. When first ends in a path separator and second starts with one only one of these will remain.

The path separator is always /.

FUNC copy(string fromName, string toName) status @public

Copy file from to to. Not implemented yet.

Return FAIL or OK.

FUNC delete(string fileName) status @public

Delete file fileName.

FUNC dirList(string dirName) list<string> @public

Returns a list with all entries of directory dirName.

When dirName is empty the current directory "." is listed.

The entries "." and ".." are not included. Other entries starting with "." are included.

Returns NIL if dirName could not be opened.

FUNC directory(string fname) string @public

Returns the directory name of fname.

E.g.: for "dir/foo" returns "dir". Returns an empty string when no "/" found.

On MS-Windows checks for '\' as well as '/'.

FUNC equalFiles(string name1, string name2) bool @public

Compare two files and return TRUE if both exist, can be read and contain the same bytes.

FUNC fileInfo(string name) IO.FileInfo @public

Return statistics for name.

When name cannot be inspected (doesn't exist or no permissions) the FileInfo.status field is FAIL.

FUNC fileReader(string fileName) IO.File @public

Opens file fileName for reading.

Returns NIL when the file could not be opened.

FUNC fileWriter(string fileName, bool truncate) IO.File @public

Opens file fileName for writing.

Returns NIL when the file could not be opened.

If the file already exists it is truncated, unless truncate is FALSE. If the file does not exist it is created with default permissions.

FUNC findExe(string exeName) string @public

Finds exeName in $PATH and returns the actual location.

When exeName is an absolute path or relative to the current directory it is returned as-is.

When exeName can't be found in $PATH NIL is returned.

Resolves symbolic links before returning the result.

On MS-Windows backslashes are replaced with forward slashes and ".exe" is appened when appropriate.

FUNC findExeInDirList(string exeName, list<string> dirs) string @public

Searches for exeName in each directory in dirs and returns the first one that exists and is executable.

Does not resolve symbolic links. Returns NIL when not found.

FUNC findFirstExe(list<string> alternatives) string @public

Find the first executable in alternatives that exists.

Returns NIl if none of the alternatives exists.

FUNC flush() status @public

Flushes buffered output on stdout.

Returns FAIL or OK.

FUNC format(string fmt, dyn arguments) status @public

Formats the string and writes it to stdout with a newline.

FUNC fullPath(string fname) string @public

Returns the full path of fname.

fname can be a directory or a file name. It does not have to exist, but its directory must exist. Returns NIL when failed.

FUNC getdir() string @public

Return the current directory.

In the unlikely case that this fails NIL is returned.

FUNC isDirectory(string name) bool @public

Returns TRUE if name exists and is a directory.

This is equal to using IO.fileInfo() and checking for an OK status and the IO.FileInfo.isDir flag.

FUNC isExecutable(string name) bool @public

Returns TRUE if the file name exists and is executable.

This uses the permissions for the current user.

FUNC isFullPath(string fname) bool @public

Returns TRUE if fname is a full (absolute) path name, the meaning

of fname does not depend on the current directory.

FUNC isPathSep(int c) bool @public

Returns TRUE if c is a path separator.

FUNC isReadable(string name) bool @public

Returns TRUE if the file name exists and is readable.

This uses the permissions for the current user.

FUNC isWritable(string name) bool @public

Returns TRUE if the file name exists and is writable.

This uses the permissions for the current user.

FUNC mkdir(string dirName) status @public

Create directory dirName.

Does not create any directory above dirName. Returns FAIL or OK.

FUNC modifyExeName(string exeName, string newName) string @public

Given an executable name returns a different executable name in the same directory.

This is useful to avoid different behavior on Unix and MS-Windows.

exeName is the full path or relative path of an existing executable. Including ".exe" or ".com" for MS-Windows.

newName is the base of the new name, without a path or ".exe".

Example:

 IO.shell(IO.modifyExeName(ARG.exeName, "zimbu2c"))

For Unix changes "path/zimbu" into "path/zimbu2c". For MS-Windows changes "path/zimbu.exe" into "path/zimbu2c.exe"

FUNC move(string fromName, string toName) status @public

Move file fromName to toName by making a copy and deleting fromName. Not implemented yet.

This also works over file systems.

FUNC nextPartIndex(string fname, int idx) int @public

Returns the index of the next path component, after the next separator.

Returns -1 when there is no further separator.

FUNC pastHeadIndex(string fname) int @public

Returns index of first char after leading "c:/", "/", etc. Returns 0 when no head found.

FUNC print(string text) status @public

Writes text to stdout and appends a newline.

Returns FAIL or OK.

Does the same as IO.stdout.print()

FUNC print(varString text) status @public

Writes text to stdout and appends a newline.

Returns FAIL or OK.

Does the same as IO.stdout.print(text)

FUNC print(int nr) status @public

Writes nr to stdout and appends a newline.

Returns FAIL or OK.

Does the same as IO.stdout.print(nr)

FUNC print(nat nr) status @public

Writes nr to stdout and appends a newline.

Returns FAIL or OK.

Does the same as IO.stdout.print(nr)

FUNC print(float nr) status @public

Writes nr to stdout and appends a newline.

Returns FAIL or OK. Does the same as IO.stdout.print(nr)

FUNC print(bool flag) status @public

Writes flag to stdout as "FALSE" or "TRUE" and appends a newline.

Returns FAIL or OK.

Does the same as IO.stdout.print(flag)

FUNC print(status ok) status @public

Writes ok to stdout as "FAIL" or "OK" and appends a newline.

Returns FAIL or OK.

Does the same as IO.stdout.print(ok)

FUNC print(dyn arg) status @public

Writes arg to stdout depending on its actual type.

Returns FAIL or OK.

Does the same as IO.stdout.print(arg)

FUNC print() status @public

Writes a newline to stdout.

Returns FAIL or OK. Does the same as IO.stdout.print()

FUNC readAllBytes(IO.I_ByteReader reader) byteString @public

Read all bytes from reader and return a byteString with them.

FUNC readAllChars(IO.I_CharReader reader) string @public

Read all chars from reader and return a string with them.

FUNC readByte() int @public

Reads and returns one byte from stdin.

When there is nothing to read returns IO.eof.

Equal to IO.stdin.readByte().

FUNC readChar() int @public

Reads and returns one UTF-8 character from stdin.

When there is nothing to read returns IO.eof.

Throws E.IllegalByte when encountering an invalid UTF-8 byte.

Equal to IO.stdin.readChar().

FUNC readFile(string fileName) string @public

Reads file fileName and returns its contents as a string.

Throws an exception when the file can't be opened or read.

TODO: return NIL instead of throwing an exception.

Do not use this method to check if a file exists and can be read, use isReadable() instead.

FUNC rename(string fromName, string toName) status @public

Rename file fromName to toName.

This only works if both are on the same file system.

FUNC resolve(string fname) string @public

Returns fname with all symbolic links resolved.

When anything fails returns fname as-is.

FUNC rmdir(string dirName) status @public

Delete directory dirName. Only works when it is empty.

FUNC root(string fname) string @public

Returns fname with the last extension removed.

E.g.: for "dir/foo.vim" returns "dir/foo", for "foo.vim.gz" returns "foo.vim".

Returns fname when no "." found in the tail of fname.

FUNC rootAll(string fname) string @public

Returns fname with all extensions removed.

E.g.: for "dir/foo.vim.gz" returns "dir/foo".

Returns fname when no "." found in the tail of fname.

FUNC tail(string fname) string @public

Returns the last path component in fname.

E.g.: for "dir/foo" returns "foo". Returns fname when no "/" found. Returns "" when fname ends in "/".

On MS-Windows checks for '\' as well as '/'.

FUNC tailIndex(string fname) int @public

Returns index of last path component in fname.

E.g.: for "dir/foo" returns 4. Returns 0 when no "/" is found. Returns fname.Size() when fname ends in "/".

On MS-Windows checks for '\' as well as '/'.

FUNC tailSepIndex(string fname) int @public

Returns index of last path component of fname, including separator(s) before it that are not part of the head.

E.g.: for "dir/foo" returns 3. For "/foo" returns 1. Returns 0 when no "/" found.

FUNC write(string text) status @public

Writes text to stdout and returns FAIL or OK.