PLOGHELP I_O Kathryn Seifert, July 1986 Revised by Robert Duncan, May 1987 Overview of input/output operations in Prolog. CONTENTS - (Use g to access required sections) 1 How Prolog I/O Works 2 Naming Streams 3 Opening and Closing Streams 4 Reading-in Programs 5 Term and Character I/O 6 Interfacing to Pop-11 I/O 7 List of I/O Predicates and Help Files 8 Related Documentation ----------------------------------------------------------------------- 1 How Prolog I/O Works ----------------------------------------------------------------------- Prolog provides predicates for both term-based and character-based input and output, together with predicates for the reading in and writing out of programs (i.e. procedure definitions). All input to a Prolog program is derived from a single source known as the current input stream. By default this stream is associated with the terminal so that input is taken interactively, but it's possible to change this source by use of the predicate see/1. The goal ?- see(File). will make File the current input stream, so that subsequent input will be taken from there. Likewise, all output from a Prolog program is directed to a single current output stream, usually associated with the terminal. The predicate tell/1 is available for redirecting this output to an alternative destination. ----------------------------------------------------------------------- 2 Naming Streams ----------------------------------------------------------------------- A stream is denoted in Prolog by an atom. Normally this will just be the name of a file expressed using the conventions of the operating system under which Poplog is running. Under UNIX for example, a stream might be '~/prolog/temp.pl' or under VMS '[prolog]temp.pl' Note the use of quotes around the filenames to allow the inclusion of special characters such as "/" and "[". There are in addition three atoms which represent special streams, namely 'user', 'errchan' and 'inchan'. The stream 'user' can be used either for input or output and in both cases it refers to the user's terminal. This stream is the default for Prolog to use whenever no other has been selected. The stream 'errchan' can be used for output only and refers to a special stream meant for displaying error or debugging messages. This too is normally connected to the user's terminal. The stream 'inchan' can be used for input only and refers to the private input stream of the current invocation of the Prolog compiler. It should not normally be specified explicitly. Finally, you can also use a Pop-11 character repeater (or consumer) as an input (or output) stream; this is discussed in more detail below. The names of the current input and output streams can be obtained by use of the predicates seeing/1 and telling/1. ----------------------------------------------------------------------- 3 Opening and Closing Streams ----------------------------------------------------------------------- There is no need to explicitly open a stream in Prolog. The special streams are always open and can't be closed. For any other file, the first see done on it will open it automatically and start the input stream from the top of the file; subsequent sees will resume reading from the position previously reached. Likewise, the first tell on a file will open the file for writing (thereby deleting its existing contents, if any) and subsequent tells on the same file will cause output to be appended. The predicate seen/0 closes the current input stream and told/0 closes the current output stream. The predicate close/1 takes either an input or output stream as argument and closes the specified stream. After closing a stream, the current input (or output) reverts to 'user'. In the normal case, a file once opened (either for input or output) will remain open until explicitly closed by seen/0, told/0 or close/1. If it is required to access a file from the beginning, it is good practice to assume that the file is already open and explicitly close it before use. For example, to start reading a file from the top use a procedure something like: see_from_beginning(File) :- see(File), ;;; to select it as current seen, ;;; to make sure it's closed see(File). ;;; to re-open it at the top It is also a good idea to close files which have been finished with: there is a limit to the number of files which can be kept open at any time, although the actual number varies from system to system. Abnormal terminations to programs (because of errors or through calling abort/0) won't automatically close files, so don't assume this. ----------------------------------------------------------------------- 4 Reading-in Programs ----------------------------------------------------------------------- The predicate compile/2 is used to read procedure definitions and execute directives from a file. The goal ?- compile(File, CompileMode). invokes the Prolog compiler on the input stream File, and implicitly redirects the current input to that stream for the duration of the compilation. Any input initiated by directives within the compiled file will thus read from File also, regardless of any previous setting of the current input. It is possible to see an alternative input source within a directive, but this has effect only for the duration of the directive: the input stream will be reset to File once the directive has been executed. In particular, a directive consisting only of a redirection, such as :- see(user). has no visible effect. Compilation of a file or part of a file from Ved is the same as a call to compile/2 in reconsult mode. ----------------------------------------------------------------------- 5 Term and Character I/O ----------------------------------------------------------------------- read/1 and write/1 are the basic predicates for the reading and writing of complete Prolog terms; get/1 and put/1 for characters. These all act on the current input and output streams. Character I/O predicates prefixed with tty (such as ttyget/1, ttyput/1) work in the same way as their non-prefixed counterparts but act directly on the terminal, regardless of the current input and output streams. It is generally unwise to mix term and character input on the same stream, as some characters can be lost. ----------------------------------------------------------------------- 6 Interfacing to Pop-11 I/O ----------------------------------------------------------------------- This section will only be of interest to those who wish to do mixed- language programming. It assumes knowledge of the I/O facilities of Pop-11; for a summary of the help files available on this topic see HELP * IO. Prolog's current input stream is associated with the Pop-11 variable cucharin and the output stream with the variable cucharout. When a see is done for the first time on a stream, a character repeater is created for the stream (using the procedure discin if the stream is a file name) and assigned to cucharin; similarly, when an output stream is opened a character consumer is created and assigned to cucharout. Prolog maintains internal tables mapping stream names to their corresponding character procedures, so that when a see or tell is done on a subsequent occasion, the same procedure can be recovered for the stream. The special streams 'user', 'errchan' and 'inchan' correspond to particular character procedures: 'user' refers to the current value of charin or charout (depending on whether it is being used as an input or an output stream); 'errchan' refers to the current value of cucharerr and 'inchan' to the value of cucharin at the time that the current invocation of the Prolog compiler began, i.e it names the stream which is currently being compiled. Pop-11 procedures called from Prolog can access the current input and output streams simply by reading from cucharin and writing to cucharout. It is also possible to make Prolog address arbitrary Pop-11 streams by providing a character procedure directly as an argument to see or tell. As an example, suppose we have defined the following predicate which calls a goal after first redirecting the input to some given source: call_with_input(Input, Goal) :- see(Input), call(Goal). We could invoke this from Prolog, taking the input from a named file: ?- call_with_input('~/prolog/temp.pl', Goal). or we could invoke it from Pop-11, providing a character repeater as the input source: vars input = /* ... some character repeater ... */ vars term = prolog_maketerm(input, Goal, "call_with_input", 2); prolog_invoke(term) => (see PLOGHELP * PROLOG_INVOKE). A similar approach would work for output too. ----------------------------------------------------------------------- 7 List of I/O Predicates and Help Files ----------------------------------------------------------------------- PLOGHELP * CLOSE Closes the specified input or output stream. PLOGHELP * COMPILE Reads procedure definitions and goals from a file. PLOGHELP * DISPLAY Writes a term to the current output in prefix format. PLOGHELP * GET Reads characters from the current input and returns the first printing character. PLOGHELP * GET0 Reads the next character from the current input. PLOGHELP * LISTING Writes clauses from the database to the current output. PLOGHELP * NL Prints newlines on the current output. PLOGHELP * NUMBERVARS Controls the numbering of variables on output. PLOGHELP * PORTRAY Tailors the action of the predicate print/1. PLOGHELP * PRINT Writes a term to the current output. PLOGHELP * PROMPT Changes the prompt used by read/1 and get/1. PLOGHELP * PUT Writes a character to the current output. PLOGHELP * READ Reads a term from the current input. PLOGHELP * SEE Sets the current input stream. PLOGHELP * SEEING Determines the name of the current input stream. PLOGHELP * SEEN Closes the current input stream. PLOGHELP * SKIP Reads characters from the current input until a given character is found. PLOGHELP * TAB Prints spaces on the current output. PLOGHELP * TELL Sets the current output stream. PLOGHELP * TELLING Determines the name of the current output stream. PLOGHELP * TOLD Closes the current output stream. PLOGHELP * TTYFLUSH Flushes the output buffer to the terminal. PLOGHELP * TTYGET Reads characters from the terminal and returns the first printing character. PLOGHELP * TTYGET0 Reads the next character from the terminal. PLOGHELP * TTYNL Prints newlines on the terminal. PLOGHELP * TTYPUT Prints a character on the terminal. PLOGHELP * TTYSKIP Reads characters from the terminal until a given character is found. PLOGHELP * TTYTAB Prints spaces on the terminal. PLOGHELP * WRITE Writes a term to the current output. PLOGHELP * WRITEQ Writes a term to the current output, quoting atoms where necessary. ----------------------------------------------------------------------- 8 Related Documentation ----------------------------------------------------------------------- HELP * OUTPUT Information about printing in Pop-11 programs. HELP * INPUTOUT List of HELP files relating to Poplog's input/output system. HELP * INPUT Information about input procedures in Pop-11 and Ved. REF * SYSIO More detailed account of Poplog's basic I/O facilities. --- C.all/plog/help/i_o --- Copyright University of Sussex 1993. All rights reserved.