read_term/[2,3]

Synopsis

read_term+Options, -Term)]

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

Read a term from the current input stream or from Stream, optionally returning extra information about the term.

Arguments


Stream stream_object
A valid Prolog stream, which is open for input
Term term
the term that is read
Options list of term
a list of zero or more of the following:

syntax_errors(Val)
Val must be bound to one of the following, indicating what should be done when a syntax error is found:

quiet
nothing is printed, and read_term/[2,3] fails
dec10
a syntax error message is printed, and read_term/[2,3] tries to read the next term (this is compatible with DEC-10 Prolog and previous versions of Quintus Prolog)
fail
a syntax error message is printed, and read_term/[2,3] fails
error
an exception is raised.

The default value if this option is not specified is the current value of the syntax_errors prolog flag. The default value for this flag is dec10. See prolog_flag/2 for more information on these flags.

variable_names(Names)
On completion, Names is bound to a list of Name=Var pairs, where each Name is an atom indicating the spelling of the name of a variable in the term just read, and Var is the corresponding variable. Note that anonymous variables, written as _, are not included in this list.
singletons(Singletons)
On completion, Singletons is bound to a list of Name=Var pairs, one for each variable only appearing once in the term. Anonymous variables are not included on this list.
term_position(Position)
On completion, Position is the position of the start of the actual term, as might be returned by stream_position/2. Any white space and comments before the actual term are not reflected by the position. To find the position of the end of the term, you need only call stream_position/2; it will give you the position of the first character after the period ending the term.
subterm_positions(PositionTerm)
On completion, PositionTerm is bound to a position term that describes the position of the term just read and all of its subterms. A position term is of one of the forms listed below. In all these forms, Start and End are the character positions of first character of the term and the character following the last character of the term, respectively. Similarly FStart and FEnd specify the start and end of the principle functor of the term. Note that the positions are character positions, not position terms as returned by stream_position/2.

Start-End
The term corresponding to this position term is either atomic or a variable. Start and End are the character positions of the first character of the term and the character following the last character of the term, respectively.
list_position(Start,End,Elts,Tail)
The term corresponding to this position term is a list, which was written using bracket notation (for example, [a,list]). Elts is a list of position terms for each proper element of the list. Tail is the position of the tail of the list (the part following the |), or the atom none if the list has no tail part.
string_position(Start,End)
The term corresponding to this position term is a list of character codes written as a quoted string (for example, "a string"). The positions specified include the quote characters.
brace_term_position(Start,End,Arg)
The term corresponding to this position term is of the form {X}. Arg is a position term describing the argument of this term.
term_position(Start,End,FStart,FEnd,Args)
The term corresponding to this position term is a compound term not specifically mentioned above. This includes terms written with operators. Args is a list of position terms, one for each argument of the term.

Exceptions


syntax_error
A syntax error is found
permission_error
The input stream cannot be read
domain_error
An illegal option or an invalid stream is specified
instantiation_error
Either Stream or Options, or one of the elements of the option list, or the argument of the syntax_errors option is unbound
type_error
The argument to the syntax_errors option is not an atom

Examples

     | ?- read_term([variable_names(L)], T).
     |: append([U|X],Y,[U|Z]) :- append(X,Y,Z).
     
     L = ['U'=_1988,'X'=_2003,'Y'=_2020,'Z'=_2046],
     T = (append([_1988|_2003],_2020,[_1988|_2046]):-
              append(_2003,_2020,_2046))
     
     | ?- read_term([subterm_positions(P)], T).
     |: foo+bar+baz.
     
     P = term_position(1642,1653,1649,1650,
             [term_position(1642,1649,1645,1646,
                  [1642-1645,1646-1649]),
              1650-1653]),
     T = foo+bar+baz

See Also

read/[1,2], prompt/[2,3] prolog_flag/[2,3] ref-iou