[NOTE] You might have found this while looking for a predicate to read input from a file or the user. Quite likely this is not what you need in this case. These predicates read a Prolog term, which may span multiple lines and must end in a full stop (dot character followed by a layout character). The predicates for reading and writing Prolog terms are particularly useful for storing Prolog data in a file or transferring them over a network communication channel (socket) to another Prolog process. The libraries provide a wealth of predicates to read data in other formats. See e.g., library(readutil), library(pure_input) or libraries from the extension packages to read XML, JSON, YAML, etc.

This family of predicates is intended for reading Prolog terms from a stream. The predicate read_clause/3 reads a term the way the compiler does. Use read_term_from_atom/3, term_to_atom/2 or term_string/2 to read a term from text and read_term_with_history/2 to read a term with the history substitutions of the toplevel.

Valid options for read_term/2 and read_term/3 are:

backquoted_string(Bool)

If true, read `...` to a string object (see section 5.2). The default depends on the Prolog flag back_quotes.

blob(Atom)

Defines how to read a non-text blob, which write/1 emits as <Type>(Arg, ... ), e.g. <stream>(0x55c1e0). See section 12.4.10. Values are

error

Raise a syntax error. This is the default: reading such a term cannot reconstruct a variant of the term that was written, so the reader does not silently produce one.

dead

Create a blob that has no foreign object behind it. It is atomic, it writes as it was read and blob/2 reports the type it stands for, but every predicate that expects the real thing rejects it. Use this to parse log files, stack traces or listing output that contains blobs.

resolve

As dead, but first look for a blob that is alive in this process and writes as this text. This is what the toplevel uses, so a blob can be copied from earlier output and pasted back into a goal. Note that this turns text into a live handle and must therefore only be used on trusted input. It is also best effort because the original blob may have been reclaimed and a new blob of the same type may have allocated a new resource at the same address (known as the ABA problem). Considering the toplevel, (small) answers are recorded for reuse as $Var and blobs that are part of small answers are thus referenced as long as the answer binding is not changed.

There is no index from the written form back to the blob. If the first argument is the address of the blob data, which is what the write() function of a blob normally emits, only the blob at this address is written to compare the result. If it is not, every live blob of Type is written. Either way the comparison is on the text, i.e., the blob must write exactly as it was read.

The notation is only unambiguous as long as < is not a prefix operator: if it is, <a>(f) is the legal term >(<(a),f). In a module that declares such an operator the reader therefore leaves the text alone and blobs cannot be read, regardless of Mode.

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.46) 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.15.1.10 for the rules that apply for warning about a singleton variable.^{115As 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 |<TailTerm>, Tail is unified with the term position of the tail, otherwise with the atom 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.^{116The 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(Prefix)

If not false, demand variables to start with the character Prefix. true is an alias for _. See section 2.15.1.8 and the Prolog flag var_prefix.

unicode_atoms(Mode)

Per-call atom-content policy that overrides the policy of the input stream and the Prolog flag unicode_atoms. Mode is one of:

accept

Pass unquoted-atom bytes through verbatim (byte-faithful). This is the default.

nfc

Normalise the text of unquoted atoms (and unquoted functor names) to Unicode NFC before interning, so that two source forms that are canonically equivalent yield the same atom. Requires the kernel normalisation hook; if the hook is not yet registered when this mode is requested (via the option, set_stream/2, the open/4 unicode_atoms option, or the unicode_atoms flag), library(unicode) is loaded automatically. If the library is unavailable the underlying use_module/1 call propagates its existence_error(source_sink, library(unicode)).

error

Raise syntax_error(non_nfc_atom) when an unquoted atom contains text that is not in NFC. Uses the kernel hook for an exact NFC test when library(unicode) is loaded; otherwise falls back to rejecting any code point with wcwidth less than 1 (combining marks, zero-width and non-printable characters), which is conservative but accurate enough for source-code review.

reject

Raise syntax_error(non_ascii_atom) when an unquoted atom contains any non-ASCII code point. Independent of library(unicode).

Quoted atoms and string literals are always byte-faithful, regardless of the mode. This is the canonical description of the four values; the same vocabulary applies to the Prolog flag unicode_atoms, set_stream/2, the unicode_atoms option of open/4, and the unicode_atoms property of stream_property/2.

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.