read_term/3

read_term(@stream_or_alias, ?term, +read_options_list) [ISO]

This built-in predicate reads a single term from an input stream according to the specified values in the read-options list, the stream is altered. The input stream must be a text stream that was opened for reading. The possible read-options are:

variables(Vars): after inputting a term, Vars is a list of the variables in the term resulting from inputting, in left-to-right traversal order.
variable_names(VN_list): after inputting a term, VN_list is a list of elements where each element is a term A = V such that A is an atom whose name is the characters of V in the original term and V was a non anonymous variable in the original term.
singletons(VN_list): after inputting a term, VN_list is a list of elements where each element is a term A = V such that A is an atom whose name is the characters of V in the original term and V was a non anonymous variable that occurs only once in the original term.

If read_options_list is a valid list of read-options then a term is read according to the following rules:

If the stream position is neither end-of-stream or past-end-of-stream then let Term be the next prolog term to be read from the input stream, the stream position is advanced. If the term read and Term are unifiable then read/3 succeeds else the predicate 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 read/3 fails.

The Prolog flag console_newline may affect read_term/3.

Example
read_term(user_in, A, [variables(V), variable_names(VN), singletons(S)]).	assume the input stream 'user_in' has contents: foo(B, C, B)). test(1). .. after a term was read the values of the variables are: A=foo(__5, __6, __5) V=[_01, _02] VN=[('B' = _01), ('C' = _02)] S=['C' = _02]
read_term(user_in, A, [variables(V), variable_names(VN)]).	assume the current input stream has contents: test1(1). After the term was read the values of the variables are: A=test(1) V=__2 VN=__3

Exceptions
the read_options_list is a variable	an instantiation_error exception is thrown
the read_options_list is list with an element E which is a variable	an instantiation_error exception is thrown
read_options_list is neither a variable nor a list	a type_error(list, Read_options_list) exception is thrown
an element E of the read_options_list is neither a variable nor a list	a domain_error(read_option, E) exception 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, IS) exception is thrown, the variable IS is assigned the incorrect stream_or_alias term
stream_or_alias is not associated with an open stream	an existence_error(stream, IS) exception is thrown
stream_or_alias is an output stream	a permission_error(input, stream, IS) exception is thrown
stream_or_alias is a binary stream	a permission_error(input, binary_stream, IS) is thrown, the variable IS is assigned the stream which was used as the input stream
the input stream IS has stream properties end_of_stream(past) and eof_action(error)	a permission_error(input, past_end_of_stream, IS) is thrown and IS is substituted by the stream which was used for reading the term
the sequence of tokens cannot be parsed as a term using the current operator table	a syntax_error(A) exception is thrown, the variable A is replaced by an error message of Trinc-Prolog which describes the error

info@trinc-prolog.com