[ 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

- 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) 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