Reads the next input term (up to the end of file, or up to a fullstop) from from the input stream Stream and returns a descriptor containing all information about the term, plus additional type and source annotations.
The structure of the descriptive terms is as follows:
:- export struct(annotated_term(
term, % var, atomic or compound
type, % term type (see below)
from, to % source position (integers)
...
)).
The type field describes the type of the parsed term and is one of the following:
integer
float
rational
breal
atom
string term is a string or a char_code list
anonymous term is an anonymous variable
var(NameAtom) term is a variable with the given name
compound term is compound (with annotated subterms)
In the case of atomic terms and variables, the term field simply contains the plain parsed term. For compound terms, the term field contains a structure whose functor is the functor of the plain term, but whose arguments are annotated versions of the plain term arguments.
E.g. the source term
3is parsed as
annotated_term(3, integer, ...)
The source term
foo(bar, X, _, 3)is parsed as
annotated_term(foo(
annotated_term(bar, atom, ...),
annotated_term(X, var('X'), ...),
annotated_term(_, anonymous, ...),
annotated_term(3, integer, ...)),
compound, ...)
The source term
[1,2]is parsed as
annotated_term(.( annotated_term(1, integer, ...), annotated_term(.( annotated_term(2, integer, ...), annotated_term([], atom, ...)), compound, ...)), compound, ...)
The from/to fields of an annotated term describe a "source position" of the term. Every term/subterm is represented by one (sometimes two consecutive) tokens in the source, defined as follows:
a proper list [a,b] has subterms
[a,b] represented by the [ token, [b] represented by the , token, [] represented by the ] token, a represented by itself, b represented by itself.a general list [a,b|T] has subterms
[a,b|T] represented by the [ token, [b|T] represented by the , token, T represented by itself, a represented by itself, b represented by itself.Note that the | and ] tokens do not represent any term.
X[Args]
subscript(X, [...]) represented by the [ token, X,Args represented by itself,X{Args}
'with attributes'(X,[Args]) represented by { token,
X,Args represented by themselves
a{Args}
with(a,[Args]) represented by the { token
a,Args represented by themselves
X(Args)
apply(X,[Args]) represented by the ( token X,Args represented by themselvesIn all these cases, the commas represent nothing.
The source position of a term is the union of the source positions of the representing tokens.
No macro expansions are performed by this primitive.
If only end of file is read, the event 190 is raised and the default handler unifies Term with the atom end_of_file.
The default action for syntax errors is to print a warning and fail.
?- read_annotated(input,X). 33. X = annotated_term(33, integer, 0, 2) Yes (0.00s cpu) ?- read_annotated(input,X). foo(bar). X = annotated_term(foo(annotated_term(bar, atom, 8, 11)), compound, 4, 8) Yes (0.00s cpu) ?- read_annotated(input,X). a + 3. X = annotated_term(annotated_term(a, atom, 14, 15) + annotated_term(3, integer, 18, 19), compound, 16, 17) Yes (0.00s cpu) ?- read_annotated(input,X). [a,b]. X = annotated_term([ annotated_term(a, atom, 22, 23)| annotated_term([ annotated_term(b, atom, 24, 25)| annotated_term([], atom, 25, 26) ], compound, 23, 24) ], compound, 21, 22) Yes (0.00s cpu)