index Zimbu documentation

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.

Does the same as IO.stdout.write()

FUNC write(int number) status @public

     

Writes number to stdout and returns FAIL or OK.

Does the same as IO.stdout.write()

FUNC write(nat number) status @public

     

Writes number to stdout and returns FAIL or OK.

Does the same as IO.stdout.write()

FUNC write(float number) status @public

     

Writes number to stdout and returns FAIL or OK.

Does the same as IO.stdout.write()

FUNC write(bool flag) status @public

     

Writes flag as "TRUE" or "FALSE" to stdout and returns FAIL or OK.

Does the same as IO.stdout.write()

FUNC write(status ok) status @public

     

Writes ok as "FAIL" or "OK" to stdout and returns FAIL or OK.

Does the same as IO.stdout.write()

FUNC write(dyn arg) status @public

     

Writes arg depending on its actual type to stdout.

Returns FAIL or OK.

Does the same as IO.stdout.write()

If arg is NIL then "NIL" is written.

FUNC writeByte(int byte) status @public

     

Writes byte byte to stdout.

Does the same as IO.stdout.writeByte() Only the lower 8 bits of byte are used, the rest is ignored. Returns FAIL when the byte could not be written.

FUNC writeChar(int char) status @public

     

Writes character char to stdout as an UTF-8 byte sequence.

Does the same as IO.stdout.writeChar() Throws E.OutOfRange when char is < 0 or > 0x10ffff. Returns FAIL when the byte could not be written.

license

      Copyright 2009 Bram Moolenaar All Rights Reserved.

      Licensed under the Apache License, Version 2.0. See the LICENSE file or obtain a copy at: http://www.apache.org/licenses/LICENSE-2.0