Quintus Prolog Manual Quintus Prolog Manual
Prolog provides two classes of predicates for input and output: those which handle individual characters, and those which handle complete Prolog terms.
The following predicates have been added for I/O at the Prolog level:
at_end_of_file/[0,1] at_end_of_line/[0,1] open/4 seek/4 peek_char/[1,2] skip_line/[0,1] prompt/3 write_term/[1,2] read_term/[2,3]
Input and output happen with respect to streams. Therefore, this chapter discusses predicates which handle files and streams in addition to those which handle input and output of characters and terms.
In Quintus Prolog Release 3, the I/O system has been redesigned. Streams are now record based by default, for an increase in efficiency and portability. This leads to increased efficiency in opening streams, putting characters, flushing output, and in character I/O operations involving lines (end of line, new line, skipping lines). For a description of the new model, see section I-5-2. Combining Prolog and C I/O operations on the same stream is facilitated by a more complete set of functions.
A Prolog stream can refer to a file or to the user's terminal
.)
Footnote: At the C level, you can define more general streams, e.g., referring to pipes or to encrypted files (see section I-5-7-2
Initially, the current input and output streams both refer to the user's terminal. Each input and output built-in predicate refers implicitly or explicitly to a stream. The predicates which perform character and term I/O operations come in pairs such that (A) refers to the current stream, and (B) specifies a stream.
'predicate_name'/n (A)
'predicate_name'/n+1 (B)
Tip: Deciding which version to use involves a trade-off between speed and readability of code: In general, version (B), which specifies a stream, runs slower than (A). So it may be desirable to write code which changes the current stream and uses version (A). However, the use of (B) avoids the use of global variables and results in more readable programs.
Quintus Prolog streams are divided into two categories, those opened by see/1 or tell/1 and those opened by open/[3,4]. A stream in the former group is referred to by its file specification, while a stream in the latter group is referred to by its stream object (see Figure G-7-1). For further information about file specifications, see Chapter G-6. Stream objects are discussed in section G-7-6-1. Reading the state of open streams is discussed in section G-7-7.
Each operating system permits a different number of streams to be open. For more information on this, refer to Chapter B-4.
Term input operations include:
The 'Read' predicates are
read_term/[2,3] offers many options to return extra information about the term.
When Prolog reads a term from the current input stream the following conditions hold:
| ?- read(X)
you will keep getting prompts (first '|: ', and five spaces thereafter) every time you type the return key, but nothing else will happen, whatever you type, until you type a full-stop.
To query or change the sequence of characters (prompt) that indicates that the system is waiting for user input, call prompt/[2,3].
This predicate affects only the prompt given when a user's program is trying to read from the terminal (for example, by calling read/1 or get0/1). Note also that the prompt is reset to the default "|: " on return to the top level.
Term output operations include:
G-7-3-1: Writing Terms: the 'Write' Predicates
write_term/[2,3] is a generalization of the others and provides a number of options.
G-7-3-2: Common Characteristics
The output of the 'Write' predicates is not terminated by a full-stop; therefore, if you want the term to be acceptable as input to read/[1,2], you must send the terminating full-stop to the output stream yourself. For example,
|?- write(a),
put(0'.),
nl.
If Term is uninstantiated, it is written as an anonymous variable (an underscore followed by a non-negative integer).
write_canonical[1,2] is provided so that Term, if written to a file, can be read back by read/[1,2] regardless of special characters in Term or prevailing operator declarations.
G-7-3-3: Distinctions Among the 'write' Predicates
<predicate name>(<arg1>, ..., <argn>)
| ?- write('a b').
a b
If you want to be sure that the atom can be read back by read/[1,2], you should use writeq/[1,2], or write_canonical/[1,2] which put quotes around atoms when necessary, or use write_term/[2,3]
with the 'quoted' option set to 'yes'.
| ?- writeq(a('$VAR'(0),'$VAR'('Test'))).
a(A,Test)
write_canonical/1 does not treat terms of the form '$VAR'(N) specially. It writes square bracket lists using '.'/2 and '[]' (that is, [a,b] is written as .(a,.(b,[])) ). If the
character_escapes flag is 'on' then write_canonical/1 tries to write layout characters (except ASCII 9 and ASCII 32) in the form \<lower-case-letter>, if possible; otherwise, write_canonical/1
writes the \^<control-char> form. If the character_escapes flag is 'off' then it writes the actual character, without using an escape sequence (see section G-1-3).
Like write_canonical, display/1 ignores operator declarations and shows all compound terms in standard prefix form. For example, the command
| ?- display(a+b).
produces the following:
+(a,b)
Calling display/1 is a good way of finding out how Prolog parses a term with several operators. Unlike write_canonical/[1,2], display/1 does not put quotes around atoms and functors.
G-7-3-5: Using the 'portray' hook
print/1 is called from within the system in two places:
By default, the effect of print/1 is the same as that of write/1, but you can change its effect by providing clauses for the hook predicate portray/1.
If X is a variable, then it is printed using write(X). Otherwise the user-definable procedure portray(X) is called. If this succeeds, then it is assumed that X has been printed and print/1 exits (succeeds). Note that print/1 always calls portray/1 in module 'user'. Therefore, to be visible to print/1, portray/1 must either be defined in or imported into module 'user'.
If the call to portray/1 fails, and if X is a compound term, then write/1 is used to write the principal functor of X and print/1 is called recursively on its arguments. If X is atomic, it is written using write/1.
When print/1 has to print a list, say [X1,X2,...,Xn], it passes the whole list to portray/1. As usual, if portray/1 succeeds, it is assumed to have printed the entire list, and print/1 does nothing further with this term. Otherwise print/1 writes the list using bracket notation, calling print/1 on each element of the list in turn.
Since [X1,X2,...,Xn] is simply a different way of writing .(X1,[X2,...,Xn]), one might expect print/1 to be called recursively on the two arguments X1 and [X2,...,Xn], giving portray/1 a second chance at [X2,...,Xn]. This does not happen; lists are a special case in which print/1 is called separately for each of X1,X2,...Xn.
If you would like lists of character codes printed by print/1 using double-quote notation, you should include library(printchars) (described in Part K) as part of your version of portray/1.
Often it is desirable to define clauses for portray/1 in different files. This can be achieved either by declaring it multifile in each of the files, or by using library(add_portray).
If you want to print a clause, portray_clause/1 is almost certainly the command you want. None of the other term output commands puts a full-stop after the written term. If you are writing a file of facts to be loaded by compile/1, use portray_clause/1, which attempts to ensure that the clauses it writes out can be read in again as clauses.
The output format used by portray_clause/1 and listing/1 has been carefully designed to be clear. We recommend that you use a similar style. In particular, never put a semicolon (disjunction symbol) at the end of a line in Prolog.
NOTE: For compatibility with DEC-10 Character I/O a set of predicates are provided which are similar to the primary ones except that they always use the standard input and output streams, which normally refer to the user's terminal rather than to the current input stream or current output stream. They are easily recognizable as they all begin with "tty". Given stream-based input/output, these predicates are actually redundant. For example, you could write get0(user, C) instead of ttyget0(C). This note applies to the character output as well (section G-7-5).
The operations in this category are:
get0(N) unifies N with the ASCII code of the next character from the current input stream. Cf. ttyget0/1.
get(N) unifies N with the ASCII code of the next non-layout character from the current input stream. Layout characters are all outside the inclusive range 33..126; this includes space, tab, linefeed, DEL, and all control characters. Cf. ttyget/1.
Peeking at the next character without consuming it is useful when the interpretation of "this character" depends on what the next one is. Use peek_char/[1,2].
There are two ways of skipping over characters in the current input stream: skip to a given character, or skip to the end of a line (or record).
G-7-4-4: Finding the End of Line and End of File
To test whether the end of a line on the end of the file has been reached on the current or specified input stream, use at_end_of_line/[0,1] or at_end_of_file/[0,1].
The character output operations are:
Note: The note about "tty-" predicates at the beginning of section G-7-4 applies here as well.
put(N) writes N to the current output stream or put(Stream, N) writes N to a specified one, Stream. N should be a legal ASCII character code or an integer expression.
If N evaluates to an integer, the least significant 8 bits are written.
The character is not necessarily printed immediately; they may be flushed if the buffer is full. See section G-7-6-9.
Cf. ttyput/1.
nl and nl(Stream) terminates the current output record on the current output stream or on a specified one, Stream. If the stream format is delimited (lf) or delimited (tty) (default format on Unix platform), a linefeed character (ASCII) is printed.
Cf. ttynl/0.
tab(N) writes N spaces to the current output stream. N may be an integer expression.
The spaces are not necessarily printed immediately; see section G-7-6-9.
Cf. ttytab/1
format(Control, Arguments) interprets the Arguments according to the Control string and prints the result on the current output stream. A stream can be specified using format/3.
This is used to produce output like this, either on the current output or on a specified stream:
| ?- toc(1.5).
Table of Contents i
Table of Contents
1. Documentation supplement for Quintus Prolog Release 1.5 ........... 2
1-1 Definition of the term "loaded" ............................... 2
1-2 Finding all solutions ......................................... 3
1-3 Searching for a file in a library ............................. 4
1-4 New Built-in Predicates ....................................... 5
1-4-1 write_canonical (?Term) ................................. 5
.
.
.
1-7 File Specifications .......................................... 17
1-7-1 multifile(+PredSpec) ................................... 18
yes
For details, including the code to produce this example, see the example program in the reference page for format/[2,3]. The character escaping facility is also used.
G-7-6: Stream and File Handling
The operations implemented are opening, closing, querying status, flushing, error handling, setting.
The predicates in the 'see' and 'tell' families are supplied for DEC-10 Prolog compatibility. They take either file specifications or stream objects as arguments (see section L-1) and they specify an alternative, less powerful, mechanism for dealing with files and streams than the similar predicates (open/[3,4], etc.) which take stream objects (see Figure G-7-1).
Figure G-7-1: Categorization of Stream Handling Predicates
Each input and output stream is represented by a unique Prolog term, a stream_object. In general, this term is of the form
'$stream'(X).
where X is an integer. In addition, the following terms are used to identify the standard I/O streams:
user_input
user_output
user_error
Stream objects are created by the predicate open/[3,4] and passed as arguments to those predicates which need them. Representation for stream objects to be used in C code is different. Use stream_code/2 to convert from one to the other when appropriate.
G-7-6-2: Exceptions related to Streams
All predicates which take a stream argument will raise the following exceptions:
The reference page for each stream predicate will simply refer to these as "Stream errors" and will go on to detail other exceptions that may be raised for a particular predicate.
G-7-6-3: Suppressing Error Messages
nofileerrors/0 resets the 'fileerrors' flag, so that the built-in predicates which open files simply fail, instead of raising an exception if the specified file cannot be opened.
To cancel the effect of fileerrors/0, call nofileerrors/0. It sets the 'fileerrors' flag to its default state in which an error message is produced by see/1, tell/1, and open/3 if the specified file cannot be opened. The error message is followed by an abort/0; that is, execution of the program is abandoned and the system returns to top level.
The 'fileerrors' flag is only enabled or disabled by an explicit call to fileerrors/0 or nofileerrors/0, or via prolog_flag/[2,3] which can also be used to obtain the current value of the fileerrors flag. See section G-10, for more information on the fileerrors flag.
Before I/O operations can take place on a stream, the stream must be opened, and it must be set to be current input or current output. As illustrated in Figure G-7-1, the operations of opening and setting are separate with respect to the stream predicates, and combined in the File Specification Predicates.
Opening a stream and making it current are combined in see and tell:
It is important to remember to close streams when you have finished with them. Use seen/0 or close/1 for input files, and told/0 or close/1 for output files.
G-7-6-5: Finding the Current Input Stream
/* nonvar(FileNameOrStream), */
see(FileNameOrStream),
...
seeing(FileNameOrStream)
If the current input stream has not been changed (or if changed, then restored), the above sequence will succeed for all file names and all stream objects opened by open/[3,4]. However, it will
fail for all stream objects opened by see/1 (since only file name access to streams opened by see/1 is supported). This includes the stream object 'user_input' (since the standard input stream
is assumed to be opened by see/1, and so seeing/1 would return 'user' in this case).
seeing/1 can be followed by see/1 to ensure that a section of code leaves the current input unchanged
G-7-6-6: Finding the current output stream
tell('Some File Name')
...
telling('Some File Name')
telling/1 should succeed if the current input stream was not changed (or if changed, restored). It succeeds for any file name (including 'user') and any stream object opened by open/3 (section
G-7-6-4), but fails for 'user_output' and any stream object opened by tell/1 (section G-7-6-4). Passing file names to tell/1 is the only DEC-10 Prolog usage of telling/1, so Quintus Prolog is
compatible with this usage.
WARNING: The sequencetelling(File), ... set_output(File),will signal an error if the current output stream was opened by tell/1. The only sequences that are guaranteed to succeed aretelling(FileOrStream), ... tell(FileOrStream)andcurrent_output(Stream), ... set_output(Stream)
G-7-6-7: Backtracking through Open Streams
current_stream(*File, *Mode, *Stream) succeeds if Stream is a stream which is currently open on file File in mode Mode, where Mode is either 'read', 'write', or 'append'. None of the arguments need be initially instantiated. This predicate is non-determinate and can be used to backtrack through all open streams. It fails when there are no (further) matching open streams.
current_stream/3 ignores the three special streams for the standard input, output, and error channels.
see(foo),
...
close(foo)
'foo' will be closed. However, in the example
open(foo, read, S),
...
close(foo)
an exception will be raised and 'foo' will not be closed.
Output to a stream is not necessarily sent immediately; it is buffered. The predicate flush_output/1 flushes the output buffer for the specified stream and thus ensures that everything that has been written to the stream is actually sent at that point.
G-7-7: Reading the State of Opened Streams
Character count, line count and line position for a specified stream are obtained as follows:
G-7-7-1: Stream Position Information for Terminal I/O
Input from Prolog streams which have opened the user's terminal for reading is echoed back as output to the same terminal. This is interleaved with output from other Prolog streams which have opened the user's terminal for writing. Therefore, all streams connected to the user's terminal share the same set of position counts and thus return the same values for each of the predicates character_count/2, line_count/2, and line_position/2. The following example assumes that 'user_input', 'user_output', and 'user_error' are all connected to the user's terminal (which may not always be true if I/O is being redirected),
| ?- line_count(user, X1),
line_count(user_input, X2),
line_count(user_output, X3),
line_count(user_error, X4).
X1 = X2 = X3 = X4 = 36 ;
no
| ?- line_position(user, X1),
line_position(user_input, X2),
line_position(user_output, X3),
line_position(user_error, X4).
X1 = X2 = X3 = X4 = 0 ;
no
| ?- character_count(user, X1),
character_count(user_input, X2),
character_count(user_output, X3),
character_count(user_error, X4).
X1 = X2 = X3 = X4 = 1304 ;
no
There are two methods of finding and setting the stream position, stream positioning and seeking. The current position of the read/write pointer in a specified stream can be obtained by using stream_position/2. It may be changed by using stream_position/3. Alternatively, seek/4 may be used.
Seeking is more general, and stream positioning is more portable. The differences between them are:
G-7-9: Summary of Predicates and Functions
Reference pages for the following provide further detail on the material in this chapter.
at_end_of_file/[0,1] read_term/[2,3] at_end_of_line/[0,1] see/1 character_count/2 seeing/1 close/1 seek/4 current_input/1 seen/0 current_output/1 set_input/1 current_stream/3 set_output/1 display/1 skip/[1,2] fileerrors/0 skip_line/[0,1] flush_output/1 stream_position/[2,3] format/[2,3] tab/[1,2] get0/[1,2] tell/1 get/[1,2] telling/1 line_count/2 told/0 line_position/2 ttyflush/0 nl/[0,1] ttyget0/1 nofileerrors/0 ttyget/1 open/[3,4] ttynl/0 open_null_stream/1 ttyput/1 peek_char/[1,2] ttyskip/1 portray/1 ttytab/1 portray_clause/1 write/[1,2] print/[1,2] write_canonical/[1,2] prompt/[2,3] writeq/[1,2] put/[1,2] write_term/[2,3] read/[1,2]
Also, see Chapter I-5.
add_portray printchars plint
contact:
product support
sales information