[ Term I/O | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

read_term(+Stream, -Term, ++Options)

Read a whole term in ECLiPSe syntax from the input stream Stream, according to Options
Stream
Integer (stream number) or Atom (reserved or user-defined symbolic stream name)
Term
An term, usually a variable
Options
List of option terms

Description

This is a generalisation of the predicates read/2 and readvar/3. Options is a (possibly empty) list of the following options:

variables(Vars)

returns a duplicate-free list of all the variables in the term that has been read (including anonymous variables).

variable_names(VarsNames)

returns a duplicate-free list of structures of the form Name=Var, where Var is a named (non-anonymous) variable which occurs in the term that has been read, and Name is an atom, representing the source name.

singletons(VarsNames)

returns a list of structures of the form Name=Var, where Var is a named (non-anonymous) variable which occurs only once in the term that has been read, and Name is an atom, representing the source name.

Modes and Determinism

Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

Fail Conditions

Fails if a syntax error was detected and no term could be read

Exceptions

(4) instantiation fault
Stream is not instantiated.
(5) type error
Stream is not an atom or an integer.
(5) type error
Options is not a list of compound terms.
(6) out of range
Options list contains a unrecognised option.
(192) illegal stream mode
Stream is not an input stream.
(193) illegal stream specification
Stream is an illegal stream specification.

Examples

	?- read_term(T, []).
	 foo(X,_,bar(X,Y,_Z)).

	T = foo(X, _255, bar(X, Y, _Z))


	?- read_term(T, [variable_names(VN)]).
	 foo(X,_,bar(X,Y,_Z)).

	T = foo(X, _260, bar(X, Y, _Z))
	VN = ['X' = X, 'Y' = Y, '_Z' = _Z]


	?- read_term(T, [variables(V),variable_names(VN),singletons(S)]).
	 foo(X,_,bar(X,Y,_Z)).

	 T = foo(X, _278, bar(X, Y, _Z))
	 V = [X, _278, Y, _Z]
	 VN = ['X' = X, 'Y' = Y, '_Z' = _Z]
	 S = ['_Z' = _Z, 'Y' = Y]

See Also

read_term / 2, readvar / 3, read / 1, read / 2, set_stream_property / 3