Availability:built-in
[ISO]read_term(-Term,
+Options)Read a term from the current input stream and unify the term with
Term. The reading is controlled by options from the list of
Options. If this list is empty, the behaviour is the same as
for
read/1.
The options are upward compatible with Quintus Prolog. The argument
order is according to the ISO standard. Syntax errors are always
reported using exception-handling (see catch/3).
Options:
- backquoted_string(Bool)
- If
true, read `...` to a string
object (see
section 5.2). The default
depends on the Prolog flag
back_quotes.
- character_escapes(Bool)
- Defines how to read
\ escape sequences in quoted atoms. See
the Prolog flag character_escapes
in current_prolog_flag/2.
(SWI-Prolog).
- comments(-Comments)
- Unify Comments with a list of Position-Comment,
where
Position is a stream position object (see stream_position_data/3)
indicating the start of a comment and Comment is a string
object containing the text including delimiters of a comment. It returns
all comments from where the read_term/2
call started up to the end of the term read.
- cycles(Bool)
- If
true (default false), re-instantiate
templates as produced by the corresponding write_term/2
option. Note that the default is false to avoid
misinterpretation of @(Template, Substitutions), while the
default of write_term/2
is true because emitting cyclic terms without using the
template construct produces an infinitely large term (read: it will
generate an error after producing a huge amount of output).
- dotlists(Bool)
- If
true (default false), read .(a,[])
as a list, even if lists are internally constructed a different functor
([|](Head,Tail)). This is primarily intended to read the
output from write_canonical/1
from other Prolog systems. See
section 5.1.
- double_quotes(Atom)
- Defines how to read " ... " strings. See the Prolog flag
double_quotes.
(SWI-Prolog).
- module(Module)
- Specify Module for operators, character_escapes
flag and double_quotes
flag. The value of the latter two is overruled if the corresponding read_term/3
option is provided. If no module is specified, the current‘source
module' is used. If the options is provided but the target module does
not exist, module
user is used because new modules by
default inherit from user
- quasi_quotations(-List)
- If present, unify List with the quasi quotations (see
section A.44)
instead of evaluating quasi quotations. Each quasi quotation is a term
quasi_quotation(+Syntax,
+Quotation, +VarDict, -Result), where Syntax is the
term in
{|Syntax||..|}, Quotation is a list of character
codes that represent the quotation, VarDict is a list of
Name=Variable and Result is a variable
that shares with the place where the quotation must be inserted. This
option is intended to support tools that manipulate Prolog source text.
- singletons(Vars)
- As
variable_names, but only reports the variables occurring
only once in the Term read (ISO). If Vars is the
constant
warning, singleton variables are reported using print_message/2.
The variables appear in the order they have been read. The latter option
provides backward compatibility and is used to read terms from source
files. Not all singleton variables are reported as a warning. See
section 2.16.1.10
for the rules that apply for warning about a singleton variable.112As
of version 7.7.17, all variables starting with an underscore
except for the truly anonymous variable are returned in Vars.
Older versions only reported those that would have been reported if warning
is used.
- syntax_errors(Atom)
- If
error (default), throw an exception on a syntax error.
Other values are fail, which causes a message to be printed
using
print_message/2,
after which the predicate fails, quiet which causes the
predicate to fail silently, and dec10 which causes syntax
errors to be printed, after which read_term/[2,3]
continues reading the next term. Using dec10, read_term/[2,3]
never fails. (Quintus, SICStus).
- subterm_positions(TermPos)
- Describes the detailed layout of the term. The formats for the various
types of terms are given below. All positions are character positions.
If the input is related to a normal stream, these positions are relative
to the start of the input; when reading from the terminal, they are
relative to the start of the term.
- From-To
- Used for primitive types (atoms, numbers, variables).
- string_position(From, To)
- Used to indicate the position of a string enclosed in double quotes (
").
- brace_term_position(From, To, Arg)
- Term of the form
{...}, as used in DCG rules. Arg
describes the argument.
- list_position(From, To, Elms, Tail)
- A list. Elms describes the positions of the elements. If the
list specifies the tail as
|none.
- term_position(From, To, FFrom, FTo, SubPos)
- Used for a compound term not matching one of the above. FFrom
and FTo describe the position of the functor. SubPos
is a list, each element of which describes the term position of the
corresponding subterm.
- dict_position(From, To, TagFrom, TagTo, KeyValuePosList)
- Used for a dict (see section
5.4). The position of the key-value pairs is described by KeyValuePosList,
which is a list of
key_value_position/7 terms. The
key_value_position/7 terms appear in the order of the
input. Because maps do not preserve ordering, the key is provided in the
position description.
- key_value_position(From, To, SepFrom, SepTo, Key, KeyPos, ValuePos)
- Used for key-value pairs in a map (see section
5.4). It is similar to the
term_position/5 that would
be created, except that the key and value positions do not need an
intermediate list and the key is provided in Key to enable
synchronisation of the file position data with the data structure.
- parentheses_term_position(From, To, ContentPos)
- Used for terms between parentheses. This is an extension compared to the
original Quintus specification that was considered necessary for secure
refactoring of terms.
- quasi_quotation_position(From, To, SyntaxTerm, SyntaxPos, ContentPos)
- Used for quasi quotations. Given the input
{|Syntax||Content|},
SyntaxTerm is the parsed term representation from Syntax,
e.g., {|string(X)||Hello {{X}}|} produces Syntax
string(X) and SyntaxPos describes the layout of
this term. ContentPos is always a term From-To
describing the character range of Content.113The
layout of the term produced by the quasi quotation parser is not
available. Future versions may provide an interface that allows
contributing a layout term.
- term_position(Pos)
- Unifies Pos with the starting position of the term read. Pos
is of the same format as used by stream_property/2.
- var_prefix(Bool)
- If
true, demand variables to start with an underscore. See
section 2.16.1.8.
- variables(Vars)
- Unify Vars with a list of variables in the term. The
variables appear in the order they have been read. See also term_variables/2.
(ISO).
- variable_names(Vars)
- Unify Vars with a list of‘Name = Var’,
where
Name is an atom describing the variable name and Var
is a variable that shares with the corresponding variable in Term.
(ISO). The variables appear in the order they have been read.