## 4.18 Term reading and writing

This section describes the basic term reading and writing predicates. The predicates format/[1,2] and writef/2 provide formatted output. Writing to Prolog datastructures such as atoms or code-lists is supported by with_output_to/2 and format/3.

Reading is sensitive to the Prolog flag character_escapes, which controls the interpretation of the ``\`` character in quoted atoms and strings.

[ISO]write_term(+Term, +Options)
  The predicate write_term/2 is the generic form of all Prolog term-write predicates. Valid options are:
  attributes(Atom)
    Define how attributed variables (see section 6.1) are written. The default is determined by the Prolog flag write_attributes. Defined values are `ignore` (ignore the attribute), `dots` (write the attributes as `{...}`), `write` (simply hand the attributes recursively to write_term/2) and `portray` (hand the attributes to attr_portray_hook/2).
  backquoted_string(Bool)
    If `true`, write a string object (see section 4.22) as ```...```. The default depends on the Prolog flag backquoted_string.
  blobs(Atom)
    Define how non-text blobs are handled. By default, this is left to the write-handler specified with the blob-type. Using `portray`, portray/1 is called for each blob encountered. See section 9.4.7.
  character_escapes(Bool)
    If `true`, and `quoted(true)` is active, special characters in quoted atoms and strings are emitted as ISO escape-sequences. Default is taken from the reference module (see below).
  cycles(Bool)
    If `true` (default), cyclic terms are written as `@(Template, Subsitutions)`, where Subsitutions is a list Var = Value. If `cycles` is `false`, `max_depth` is not given and Term is cyclic, write_term/2 raises a `domain_error`.50The cycles option and the cyclic term representation using the @-term are copied from SICStus Prolog. However, the default in SICStus is set to `false` and SICStus writes an infinite term if not protected by e.g., the `depth_limit` option. See also the `cycles` option in read_term/2.
  ignore_ops(Bool)
    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.
  max_depth(Integer)
    If the term is nested deeper than Integer, print the remainder as ellipses ( ... ). A 0 (zero) value (default) imposes no depth limit. This option also delimits the number of printed for a list. Example:

        ?- write_term(a(s(s(s(s(0)))), [a,b,c,d,e,f]), [max_depth(3)]).
        a(s(s(...)), [a, b|...])

        Yes

    Used by the top-level and debugger to limit screen output. See also the Prolog flags toplevel_print_options and debugger_print_options.

  module(Module)
    Define the reference module (default `user`). This defines the default value for the character_escapes option as well as the operator definitions to use. See also op/3.
  numbervars(Bool)
    If `true`, terms of the format `$VAR(N)`, where <N> is a positive integer, will be written as a variable name. If N is an atom it is written without quotes. This extension allows for writing variables with user-provided names. The default is `false`. See also numbervars/3.
  partial(Bool)
    If `true` (default `false`), do not reset the logic that inserts extra spaces that separate tokens where needed. This is intended to solve the problems with the code below. Calling `write_value(`.`)` writes `..`, which cannot be read. By adding `partial(true)` to the option, it correctly emits `. .`. Similar problems appear when emitting operators using multiple calls to write_term/3.

        write_value(Value) :-
                write_term(Value, [quoted(true)]),
                write('.'), nl.

  portray(Bool)
    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.
  portray_goal(:Goal)
    Implies `portray(true)`, but calls Goal rather than the predefined hook portray/1. Goal is called through call/3, where the first argument is Goal, the second is the term to be printed and the 3th argument is the current write-option list. The write option list is copied from the write_term call, but the list is guaranteed how hold an option `proprity` that reflects the current priority.
  priority(Integer)
    An integer between 0 and 1200 representing the `context priority'. Default is 1200. Can be used to write partial terms appearing as the argument to an operator. For example:

                format('~w = ', [VarName]),
                write_term(Value, [quoted(true), priority(699)])

  quoted(Bool)
    If `true`, atoms and functors that needs quotes will be quoted. The default is `false`.
  spacing(+Spacing)
    Determines whether and where extra white-space is added to enhance readability. The default is `standard`, adding only space where needed for proper tokenization by read_term/3. Currently, the only other value is `next_argument`, adding a space after a comma used to separate arguments in a term or list.
[ISO]write_term(+Stream, +Term, +Options)
  As write_term/2, but output is sent to Stream rather than the current output.
[ISO]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`, `quoted` and `numbervars` after numbervars/4 using the `singletons` option.

  Note that due to the use of numbervars/4, non-ground terms must be written using a single write_canonical/1 call. This used to be the case anyhow, as garbage collection between multiple calls to one of the write predicates can change the `_G`<NNN> identity of the variables.

[ISO]write_canonical(+Stream, +Term)
  Write Term in canonical form on Stream.
[ISO]write(+Term)
  Write Term to the current output, using brackets and operators where appropriate.
[ISO]write(+Stream, +Term)
  Write Term to Stream.
[ISO]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.
[ISO]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. See also `library(portray_text)`.
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.
[ISO]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`.
[ISO]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, see section 2.15.1.5) 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.
[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 4.22). The default depends on the Prolog flag backquoted_string.
  character_escapes(Bool)
    Defines how to read `\` escape-sequences in quoted atoms. See the Prolog flags character_escapes, 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 mis-interpretation of `@(Template, Substutions)`, 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).
  double_quotes(Bool)
    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. (SWI-Prolog).
  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. (ISO). If Vars is the constant `warning`, singleton variables are reported using print_message/2.
  syntax_errors(Atom)
    If `error` (default), throw and 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 is 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.
  term_position(Pos)
    Unifies Pos with the starting position of the term read. Pos if of the same format as use by 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).
[ISO]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_term/2 using the option `variable_names`, 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.