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

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

Arguments
   Stream              Stream handle or alias (atom)
   Term                An term, usually a variable
   Options             List of option terms

Type
   Term I/O

Description

    This is a generalisation of the read/2 predicate (and deprecated
    predicates read_annotated/2,3, readvar/3).
    It reads one term in ECLiPSe syntax from the input stream Stream,
    and returns it as Term.
    Options is a (possibly empty) list of the following options:


    annotated(-AnnTerm)
        returns AnnTerm, which is a compound annotated_term{} that
        is structurally similar to Term and contains all information
        about Term, plus additional type information, variable names,
        and source position annotations for all subterms.
        For details see read_annotated/3.
        

    line(-Line)
        returns the Stream line number where Term starts.
        

    variables(-Vars)
        returns a duplicate-free list of all the variables in Term
        (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 Term, 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
        Term, 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 --- Stream is not instantiated.
     5 --- Stream is not an atom or a stream handle.
     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]

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

        ?- read_term(T, [annotated(AT)]).
        foo(3,X).

        T = foo(3, X)
        AT = annotated_term(foo(
                     annotated_term(3, integer, user, 1, 4, 5),
                     annotated_term(X, var('X'), user, 1, 6, 7)),
                 compound, user, 1, 0, 4)



See Also
   read_term / 2, read / 1, read / 2, read_annotated / 2, read_annotated / 3, set_stream_property / 3
