Classes - iostream

This module defines a single class called iostream that acts as the base of a hierarchy of related I/O handling classes.

:- import(iostream).
Parent class
None.
Class members
canRead()
canSeek()
canWrite()
close()
flush()
length(Length)
readByte(Byte)
readBytes(Bytes)
readLine(Line)
readTerm(Term)
readTerm(Term, Vars)
seek(Position)
seek(Position, Origin)
tell(Position)
write(Term)
writeByte(Byte)
writeln(Term)
writeln()
writeString(String)
writeTerm(Term)
writeTerm(Term, Vars)
See Also
stderr, stdin, stdout

Stream.canRead()

Description
Succeeds if Stream supports reading; fails otherwise. The default implementation always fails.
If a subclass overrides canRead() and indicates that Stream is capable of reading, then the subclass should also override readByte(), readBytes(), and readLine().
See Also
canSeek(), canWrite(), readByte(), readBytes(), readLine(), readTerm()

Stream.canSeek()

Description
Succeeds if Stream supports seeking; fails otherwise. The default implementation always fails.
If a subclass overrides canSeek() and indicates that Stream is capable of seeking, then the subclass should also override length(), seek(), and tell().
See Also
canRead(), canWrite(), length(), seek(), tell()

Stream.canWrite()

Description
Succeeds if Stream supports writing; fails otherwise. The default implementation always fails.
If a subclass overrides canWrite() and indicates that Stream is capable of writing, then the subclass should also override writeByte() and writeString().
See Also
canRead(), canSeek(), flush(), write(), writeByte(), writeln(), writeString(), writeTerm()

Stream.close()

Description
Closes Stream, releasing all resources associated with it, and then succeeds. The default implementation always succeeds.

Stream.flush()

Description
Flushes all data that has been written so far to Stream, and then succeeds.
Errors
See Also
canWrite(), write(), writeByte(), writeln(), writeString(), writeTerm()

Stream.length(Length)

Description
Unifies Length with the length of Stream. Because Length is represented as a 32-bit integer, this method cannot return the length of streams that are larger than 2 Gb in size.
Errors
See Also
canSeek(), seek(), tell()

Stream.readByte(Byte)

Description
Unifies Byte with the integer value of the next byte of Stream and succeeds; or fails if at the end of Stream.
If Stream is non-blocking and there are no bytes available at present, then the method will succeed and Byte will be unified with -1.
Errors
See Also
canRead(), readBytes(), readLine(), readTerm(), writeByte()

Stream.readBytes(Bytes, MaxLength)

Description
Reads up to MaxLength bytes from Stream and then unifies Bytes with a string containing the bytes that were read. Fails if the end of stream has been reached and no bytes were available for reading.
The number of bytes returned in Bytes may be less than MaxLength if the end of file has almost been reached or Stream is non-blocking and there are insufficient bytes available at present. It is possible for an empty string to be returned in Bytes if MaxLength is zero, or if Stream is non-blocking and there are no bytes available.
Errors
See Also
canRead(), readByte(), readLine(), readTerm(), writeString()

Stream.readLine(Line)

Description
Reads a single UTF-8 text line from Stream, unifies it with Line, and succeeds. End of line CRLF or LF sequences are stripped from Line. Fails if the end of stream has been reached and no bytes are available for reading.
The readLine() method is always blocking, even if Stream is not. On non-blocking streams, this method will force Stream to block until an end of line character or the end of stream is reached.
If the last line of Stream is non-empty and does not end in a CRLF or LF sequence, then readLine() will act as though it does. The following call to readLine() will fail, indicating end of stream.
Errors
See Also
canRead(), readByte(), readBytes(), readTerm(), writeln()

Stream.readTerm(Term)
Stream.readTerm(Term, Vars)

Description
Reads a single term from Stream and unifies it with Term. Fails if the end of stream has been reached.
Internally, the default implementation of readTerm() calls readLine() to fetch the raw textual data. Reading continues until a line is encountered that ends in ".". All of the lines read up until that point are parsed using the Plang source parser to create a term.
If Vars is present, then it is unified with a list of variable names and references within Term. The members of the Vars list have the form Name = Var where Name is a string and Var is the unbound variable that Name refers to in Term. Each Name will appear only once in the list.
Errors
See Also
canRead(), readByte(), readBytes(), readLine(), writeTerm()

Stream.seek(Position)
Stream.seek(Position, Origin)

Description
Seeks to offset Position within Stream. If Origin is present, then it must be one of the atoms start, current, or end, which indicate whether Position should be interepreted relative to the start, current position, or end of Stream respectively.
Because Position is limited to a 32-bit integer, this predicate cannot seek directly to a position within a stream larger than 2 Gb in size. The Origin values of current and end can be used to hop through the file in 2 Gb or smaller steps.
Errors
See Also
canSeek(), length(), tell()

Stream.tell(Position)

Description
Unifies Position with the an integer representing the current seek position within Stream.
Because Position is limited to a 32-bit integer, this predicate cannot return the seek position within files larger than 2 Gb in size.
Errors
See Also
canSeek(), length(), seek()

Stream.write(Term)

Description
If Term is a string, then write it directly to the stream using writeString().
If Term has the form (A + B), then write A and B to the stream without the plus sign. This rule is applied recursively for writing terms such as (A + B + C + ...).
If Term is not a string or of the form (A + B), then write it using writeTerm().
Examples
Answer is 2 + 2;
Stream.write("The answer is: " + Answer);
Stream.writeln();

The answer is: 4
See Also
canWrite(), flush(), readLine(), writeByte(), writeln(), writeString(), writeTerm()

Stream.writeByte(Byte)

Description
Writes Byte to Stream. The Byte must be an integer between 0 and 255.
Errors
See Also
canWrite(), flush(), readByte(), write(), writeln(), writeString(), writeTerm()

Stream.writeln(Term)
Stream.writeln()

Description
If Term is a string, then write it directly to the stream using writeString().
If Term has the form (A + B), then write A and B to the stream without the plus sign. This rule is applied recursively for writing terms such as (A + B + C + ...).
If Term is not a string or of the form (A + B), then write it using writeTerm().
A newline is written after Term. If Term is omitted, then only a newline is written.
Examples
Answer is 2 + 2;
Stream.writeln("The answer is: " + Answer);

The answer is: 4
See Also
canWrite(), flush(), readLine(), write(), writeByte(), writeString(), writeTerm()

Stream.writeString(String)

Description
Writes String to Stream as an unquoted string literal. Use writeTerm() instead to quote the string.
Errors
See Also
canWrite(), flush(), readBytes(), write(), writeByte(), writeln(), writeTerm()

Stream.writeTerm(Term)
Stream.writeTerm(Term, Vars)

Description
Write Term to Stream in a form that is compatible with the Plang source parser for terms. The Term is not terminated with a "." or end of line marker.
If Vars is present, then it must be a list of Name = Var declarations. If Var is encountered as an unbound variable in Term, then it will be written to Stream as Name. Variables not listed in Vars will be written as "_N", where "N" is the variable's pointer value. If Vars is not present, then all unbound variables are written as "_N". Name must be an atom or string.
The default implementation will call writeString() with a succession of string values, each making up a part of Term. It is undefined as to which parts of Term each string corresponds to, other than the requirement that the strings must serialize the Term from left to right.
Errors
Examples
Stream.writeTerm(A - B * 1.5 + pi / 2);
    produces: _1f95460 - _1f95420 * 1.5 + pi / 2

Stream.writeTerm(A - B * 1.5 + pi / 2, ["A" = A, "B" = B]);
    produces: A - B * 1.5 + pi / 2
See Also
canWrite(), flush(), readLine(), write(), writeByte(), writeln(), writeString()

Generated on 26 May 2011 for plang by  doxygen 1.6.1