[ Term I/O | 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
  Stream handle or alias (atom)
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.

syntax_errors(Atom)

  modifies the treatment of syntax errors: if 'quiet', the predicate fails quietly; if 'fail', an error message is printed and then the predicate fails; if 'error', a term of the form error(syntax_error(MessageString),context(...)) is thrown. The default is 'fail' if the per-module syntax_option 'syntax_errors_fail' is set, otherwise 'error'.

### 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 a stream handle.
(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]

            ?- read_term(T, [syntax_errors(quiet)]).
    	a b.
    	No (0.00s cpu)

## See Also

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