get0/2

get0(@stream_or_alias, ?in_integer)

This built-in clause reads a single character from the stream, the stream is altered. The ASCII value of the character is unified with the parameter 'in_integer', if the input stream is empty then the parameter 'in_integer' is unified with the atom 'end_of_file'.

The input stream must be a text stream that was opened for reading. If Char is a variable or an in_integer (an integer or the atom 'end_of_file') then:

If the stream position is neither end-of-stream or past-end-of-stream then let Char be the next character to be read from the input stream, the stream position is advanced one character. If the character read and Char are unifiable then get_char/2 succeeds else fails.
If the stream position is end-of-stream then sets the stream position to past-end-of-stream, if the atom 'end_of_file' and Char are unifiable then get0/2 succeeds else fails.
If the stream position is past-end-of-stream and the stream property is eof_action(error) then a permission_error exception is thrown. If the stream has the property eof_action(reset) then the stream position is reset so that input can be read from it again, else if the stream has the property eof_action(eof_code) then if the atom 'end_of_file' and Char are unifiable then get_char/2 succeeds else fails.

This predicate is not part of the ISO Prolog standard, the built-in predicate char_code/2 can also be used to determine the integer ASCII value of a character. If the parameter @stream_or_alias is 'user' then input is read from the current input stream.

Example
get0(user, A).	Assume the standard input stream has the contents: q, w, e, ... A is assigned the value 113 and the stream is left as: w, e, ...
get0(user, 117).	Assume the standard input stream has the contents: q, w, e, ... get0/2 fails, and a character was removed from the stream, the stream is left as: w, e, ...

Exceptions
Char is neither a variable nor an in_integer	a type_error(in_integer, Char) is thrown
stream_or_alias is a variable	an instantiation_error exception is thrown
stream_or_alias is neither a variable nor a stream term nor an alias	a domain_error(stream_or_alias, Stream) exception is thrown, the variable Stream is assigned the incorrect stream_or_alias term
stream_or_alias is not associated with an open stream	an existence_error(stream, Stream) exception is thrown
stream_or_alias is an output stream	a permission_error(input, stream, Stream) exception is thrown
stream_or_alias is a binary stream	a permission_error(input, binary_stream, InputStream) is thrown, the variable InputStream is assigned the stream which was used as the input stream
current input stream has properties end_of_stream(past) and eof_action(error)	a permission_error(input, past_end_of_stream, InputStream) exception is thrown

info@trinc-prolog.com