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

   Read a whole term in ECLiPSe syntax from the input stream Stream, according to Options

Arguments
   Stream              Integer (stream number) or Atom (reserved or user-defined symbolic stream name)
   Term                An term, usually a variable
   Options             List of option terms

Type
   Term I/O

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
   read_term(+, -, ++) is semidet

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 --- Stream is not instantiated.
     5 --- Stream is not an atom or an integer.
     5 --- Options is not a list of compound terms.
     6 --- Options list contains a unrecognised option.
   192 --- Stream is not an input stream.
   193 --- 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
