This section describes the basic term reading and writing predicates.
The predicates term_to_atom/2
and atom_to_term/3
provide means for translating atoms and strings to terms. The predicates format/[1,2]
and writef/2
provide formatted output.
There are two ways to manipulate the output format. The predicate
print/[1,2]
may be programmed using portray/1.
The format of floating point numbers may be manipulated using the
feature (see feature/2)
float_format.
Reading is sensitive to the feature character_escapes,
which controls the interpretation of the \
- write_term(+Term,
+Options)
-
The predicate write_term/2
is the generic form of all Prolog term-write predicates. Valid options
are:
- quoted(
true or false) -
If
true, atoms and functors that needs quotes will be
quoted. The default is false.
- ignore_ops(
true or false) -
If
true, the generic term-representation (<functor>(<args>
... )) will be used for all terms, Otherwise (default), operators,
list-notation and {}/1 will be written using their special
syntax.
- numbervars(
true or false) -
If
true, terms of the format $VAR(N), where <N>
is a positive integer, will be written as a variable name. The default
is
false.
- portray(
true or false) -
If
true, the hook portray/1
is called before printing a term that is not a variable. If portray/1
succeeds, the term is considered printed. See also print/1.
The default is false. This option is an extension to the
ISO write_term options.
- write_term(+Stream,
+Term, +Options)
-
As write_term/2,
but output is sent to Stream rather than the current output.
- write_canonical(+Term)
-
Write Term on the current output stream using standard
parenthesised prefix notation (i.e. ignoring operator declarations).
Atoms that need quotes are quoted. Terms written with this predicate can
always be read back, regardless of current operator declarations.
Equivalent to write_term/2
using the options
ignore_ops and
quoted.
- write_canonical(+Stream,
+Term)
-
Write Term in canonical form on Stream.
- write(+Term)
-
Write Term to the current output, using brackets and
operators where appropriate. See feature/2
for controlling floating point output format.
- write(+Stream, +Term)
-
Write Term to Stream.
- writeq(+Term)
-
Write Term to the current output, using brackets and
operators where appropriate. Atoms that need quotes are quoted. Terms
written with this predicate can be read back with read/1
provided the currently active operator declarations are identical.
- writeq(+Stream, +Term)
-
Write Term to Stream, inserting quotes.
- print(+Term)
-
Prints Term on the current output stream similar to write/1,
but for each (sub)term of Term first the dynamic predicate
portray/1
is called. If this predicate succeeds print assumes the
(sub)term has been written. This allows for user defined term writing.
- print(+Stream, +Term)
-
Print Term to Stream.
- portray(+Term)
-
A dynamic predicate, which can be defined by the user to change the
behaviour of print/1
on (sub)terms. For each subterm encountered that is not a variable print/1
first calls portray/1
using the term as argument. For lists only the list as a whole is given
to portray/1.
If portray succeeds print/1
assumes the term has been written.
- read(-Term)
-
Read the next Prolog term from the current input stream and unify it
with Term. On a syntax error read/1
displays an error message, attempts to skip the erroneous term and
fails. On reaching end-of-file
Term is unified with the atom
end_of_file.
- read(+Stream, -Term)
-
Read Term from Stream.
- read_clause(-Term)
-
Equivalent to read/1,
but warns the user for variables only occurring once in a term
(singleton variables) which do not start with an underscore if
style_check(singleton)
is active (default). Used to read Prolog source files (see consult/1).
New code should use read_term/2
with the option singletons(warning).
- read_clause(+Stream,
-Term)
-
Read a clause from Stream. See read_clause/1.
- read_variables(-Term,
-Bindings)
-
Similar to read/1,
but Bindings is unified with a list of `Name
= Var' tuples, thus providing access to the actual
variable names. New code should use read_term/2
using the option
variables(X).
- read_variables(+Stream,
-Term, -Bindings)
-
Read, returning term and bindings from Stream. See
read_variables/2.
- 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 to Quintus Prolog. The argument order
is according to the ISO standard. Options:
- syntax_errors(atom or variable)
-
Define the behaviour for when a syntax error occurs. The possible values
are:
- fail
-
Default behaviour. The error is reported as a warning and the predicate
fails.
- quiet
-
Quietly fails if a syntax error has occurred.
- Variable
-
If no error occurs, the variable is unified with
none,
otherwise
Variable is unified with a term of the form
'$stream_position'(CharNo, LineNo, LinePos):Message
|
This behaviour is a SWI-Prolog extension.
- 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.
- singletons(Vars)
-
As
variable_names, but only reports the variables occurring
only once in the Term read. Variables starting with an
underscore (`_') are not included in this list.
- term_position(Pos)
-
Unifies Pos with the starting position of the term read. Pos
if of the same format as use by stream_position/3.
- subterm_positions(TermPos)
-
Describes the detailed layout of the term. The formats for the various
types of terms if 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.
- read_term(+Stream,
-Term, +Options)
-
Read term with options from Stream. See read_term/2.
- read_history(+Show,
+Help, +Special, +Prompt, -Term, -Bindings)
-
Similar to read_variables/2,
but allows for history substitutions.
read_history/6
is used by the top level to read the user's actions.
Show is the command the user should type to show the saved
events.
Help is the command to get an overview of the capabilities.
Special is a list of commands that are not saved in the
history.
Prompt is the first prompt given. Continuation prompts for
more lines are determined by prompt/2.
A
%w in the prompt is substituted by the event number. See section
2.7 for available substitutions.
SWI-Prolog calls read_history/6
as follows:
read_history(h, '!h', [trace], '%w ?- ', Goal, Bindings)
|
- prompt(-Old, +New)
-
Set prompt associated with read/1
and its derivatives. Old is first unified with the current
prompt. On success the prompt will be set to New if this is
an atom. Otherwise an error message is displayed. A prompt is printed if
one of the read predicates is called and the cursor is at the left
margin. It is also printed whenever a newline is given and the term has
not been terminated. Prompts are only printed when the current input
stream is user.
- prompt1(+Prompt)
-
Sets the prompt for the next line to be read. Continuation lines will be
read using the prompt defined by prompt/2.