Term reading and writing

This section describes the basic term reading and writing predicates. The predicates term_to_atom2, atom_to_term3 and sformat3 provide means for translating atoms and strings to terms. The predicates format[1,2] and writef2 provide formatted output.

There are two ways to manipulate the output format. The predicate print[1,2] may be programmed using portray1. The format of floating point numbers may be manipulated using the prolog_flag (see current_prolog_flag2) float_format.

Reading is sensitive to the prolog_flag character_escapes, which controls the interpretation of the character in quoted atoms and strings.

write_term2+Term, +Options The predicate write_term2 is the generic form of all Prolog term-write predicates. Valid options are:

quotedtrue or false If true, atoms and functors that needs quotes will be quoted. The default is false. character_escapestrue or false If true, and quotedtrue is active, special characters in quoted atoms and strings are emitted as ISO escape-sequences. Default is taken from the reference module (see below). ignore_opstrue 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. moduleModule 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 op3. numbervarstrue 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. portraytrue or false If true, the hook portray1 is called before printing a term that is not a variable. If portray1 succeeds, the term is considered printed. See also print1. The default is false. This option is an extension to the ISO write_term options. max_depthInteger If the term is nested deaper than Integer, print the remainder as eclipse (...). A 0 (zero) value (default) imposes no depth limit. This option also delimits the number of printed for a list. Example:

Used by the toplevel and debugger to limit screen output. See also the prolog-flags toplevel_print_options and debugger_print_options.

write_term3+Stream, +Term, +Options As write_term2, but output is sent to Stream rather than the current output. write_canonical1+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_term2 using the options ignore_ops and quoted. write_canonical2+Stream, +Term Write Term in canonical form on Stream. write1+Term Write Term to the current output, using brackets and operators where appropriate. See current_prolog_flag2 for controlling floating point output format. write2+Stream, +Term Write Term to Stream. writeq1+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 read1 provided the currently active operator declarations are identical. writeq2+Stream, +Term Write Term to Stream, inserting quotes. print1+Term Prints Term on the current output stream similar to write1, but for each (sub)term of Term first the dynamic predicate portray1 is called. If this predicate succeeds print assumes the (sub)term has been written. This allows for user defined term writing. print2+Stream, +Term Print Term to Stream. portray1+Term A dynamic predicate, which can be defined by the user to change the behaviour of print1 on (sub)terms. For each subterm encountered that is not a variable print1 first calls portray1 using the term as argument. For lists only the list as a whole is given to portray1. If portray succeeds print1 assumes the term has been written. read1-Term Read the next Prolog term from the current input stream and unify it with Term. On a syntax error read1 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. read2+Stream, -Term Read Term from Stream. read_clause1-Term Equivalent to read1, 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 consult1). New code should use read_term2 with the option singletons(warning). read_clause2+Stream, -Term Read a clause from Stream. See read_clause1. read_term2-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 read1. The options are upward compatible to Quintus Prolog. The argument order is according to the ISO standard. Syntax-errors are always reported using exception-handling (see catch3). Options:

variablesVars Unify Vars with a list of variables in the term. The variables appear in the order they have been read. See also free_variables2. (ISO).

variable_namesVars 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).

singletonsVars 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).

syntex_errorsAtom If error (default), throw and exception on a syntax error. Other values are fail, which causes a message to be printed using print_message2, 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).

moduleModule Specify Module for operators, character_escapes flag and double_quotes flag. The value of the latter two is overruled if the corresponding read_term3 option is provided. If no module is specified, the current `source-module' is used. (SWI-Prolog).

character_escapesBool Defines how to read \ escape-sequences in quoted atoms. See the prolog-flags character_escapes, current_prolog_flag2. (SWI-Prolog).

double_quotesBool Defines how to read "..." strings. See the prolog-flags double_quotes, current_prolog_flag2. (SWI-Prolog).

term_positionPos Unifies Pos with the starting position of the term read. Pos if of the same format as use by stream_position3.

subterm_positionsTermPos 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_positionFrom, To Used to indicate the position of a string enclosed in double quotes ("). brace_term_positionFrom, To, Arg Term of the form {...}, as used in DCG rules. Arg describes the argument. list_positionFrom, 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_positionFrom, 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_term3+Stream, -Term, +Options Read term with options from Stream. See read_term2. read_history6+Show, +Help, +Special, +Prompt, -Term, -Bindings Similar to read_term2 using the option variable_names, but allows for history substitutions. read_history6 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 prompt2. A %w in the prompt is substituted by the event number. See history for available substitutions.

SWI-Prolog calls read_history6 as follows:

prompt2-Old, +New Set prompt associated with read1 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.

prompt11+Prompt Sets the prompt for the next line to be read. Continuation lines will be read using the prompt defined by prompt2.