mpg-ref-read_term - SICStus Prolog

11.3.180 `read_term/[2,3]` [ISO]

Synopsis

read_term(-Term, +Options)

read_term(+Stream, -Term, +Options)

Read a term from Stream, optionally returning extra information about the term.

Arguments

Stream

stream_object, must be ground

A valid Prolog input stream, defaults to the current input stream.

Term

term

The term that is read.

Options

list of term, must be ground, except Vars, Names, and Layout as described below.

A list of zero or more of the following:

syntax_errors(Val): Controls what action to take on syntax errors. Val must be one of the values allowed for the syntax_errors Prolog flag. The default is set by that flag. See ref-lps-flg.
variables(Vars): Vars is bound to the list of variables in the term input, in left-to-right traversal order.
variable_names(Names): Names is bound to a list of Name=Var pairs, where each Name is an atom indicating the name of a non-anonymous variable in the term, and Var is the corresponding variable.
singletons(Names): Names is bound to a list of Name=Var pairs, one for each variable appearing only once in the term and whose name does not begin with ‘_’.
The prolog flag legacy_char_classification (see Prolog Flags) changes the criteria for which variables are included in Names. When legacy_char_classification is in effect the list also includes variables that occur only once in the term and whose name begin with ‘_’ followed by a character that is not an uppercase Latin 1 character.
cycles(Boolean): Boolean must be true or false. If selected, any occurrences of @/2 in the term read in are replaced by the potentially cyclic terms they denote as described above. Otherwise (the default), Term is just unified with the term read in.
layout(Layout): Layout is bound to a layout term corresponding to Term (see Glossary).
consume_layout(Boolean): Boolean must be true or false. If this option is true, read_term/[2,3] will consume the layout-text-item that follows the terminating ‘.’ (this layout-text-item can either be a layout-char or a comment starting with a ‘%’). If the option is false, the layout-text-item will remain in the input stream, so that subsequent character input predicates will see it. The default of the consume_layout option is false.

Description

The characters read are subject to character-conversion.

Exceptions

Stream errors (see ref-iou-sfh-est), plus:

syntax_error: A syntax error was found.
instantiation_error
type_error
domain_error: An illegal option was specified.

Examples

     | ?- read_term(T, [variable_names(L)]).
     |: append([U|X],Y,[U|Z]) :- append(X,Y,Z).
     L = ['U'=_A,'X'=_B,'Y'=_C,'Z'=_D],
     T = (append([_A|_B],_C,[_A|_D]):-append(_B,_C,_D))

     | ?- read_term(T, [layout(L), variable_names(Va), singletons(S)]).
     |: [
          foo(X),
          X = Y
          ].
     
     L = [35,[36,36],[36,[37,37,37],38]],
     S = ['Y'=_A],
     T = [foo(_B),_B=_A],
     Va = ['X'=_B,'Y'=_A]
     
     | ?- read_term(T, [consume_layout(false)]), get_code(C).
     |: 1.
     
     C = 10,
     T = 1
     
     | ?- read_term(T, [consume_layout(true)]), get_code(C).
     |: 1.
     |: a
     
     C = 97,
     T = 1

11.3.180 read_term/[2,3] [ISO]