Classes - iostream
This module defines a single class called iostream
that acts as the base of a hierarchy of related I/O handling classes.
- 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
permission_error(output, stream, Stream)
- Stream is not capable of writing. This error is thrown by the default implementation.
- 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
permission_error(reposition, stream, Stream)
- Stream is not capable of seeking. This error is thrown by the default implementation.
representation_error(seek_position)
- the stream length cannot be represented as a 32-bit integer.
- 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
permission_error(input, stream, Stream)
- Stream is not capable of reading. This error is thrown by the default implementation.
- 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
permission_error(input, stream, Stream)
- Stream is not capable of reading. This error is thrown by the default implementation.
instantiation_error
- MaxLength is a variable.
type_error(integer, MaxLength)
- MaxLength is not an integer.
domain_error(not_less_than_zero, MaxLength)
- MaxLength is an integer that is less than zero.
- 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
permission_error(input, stream, Stream)
- Stream is not capable of reading. This error is thrown by the default implementation.
- 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
permission_error(input, stream, Stream)
- Stream is not capable of reading.
syntax_error(Message)
- a syntax error was encountered while reading the term. Message is set to a string describing the error.
- 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
permission_error(reposition, stream, Stream)
- Stream is not capable of seeking. This error is thrown by the default implementation.
instantiation_error
- Position or Origin is a variable.
type_error(integer, Position)
- Position is not an integer.
type_error(seek_origin, Origin)
- Origin is not one of the atoms start
, current
, or end
.
domain_error(seek_position, Position / Origin)
- Position and Origin do not define a valid seek position, although Stream is otherwise capable of seeking.
- 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
permission_error(reposition, stream, Stream)
- Stream is not capable of seeking. This error is thrown by the default implementation.
representation_error(seek_position)
- the current position cannot be represented as a 32-bit integer.
- 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
permission_error(output, stream, Stream)
- Stream is not capable of writing. This error is thrown by the default implementation.
instantiation_error
- Byte is a variable.
type_error(byte, Byte)
- Byte is not an integer between 0 and 255.
- 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
permission_error(output, stream, Stream)
- Stream is not capable of writing. This error is thrown by the default implementation.
instantiation_error
- String is a variable.
type_error(string, String)
- String is not a string.
- 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
instantiation_error
- Vars is a variable.
type_error(variable_names, Vars)
- Vars is not a valid list of variable names.
permission_error(output, stream, Stream)
- Stream is not capable of writing.
- 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()