SICStus Prolog

Node:Input Output, Next:Arithmetic, Previous:Built Intro, Up:Built Intro

Input / Output

There are two sets of file manipulation predicates in SICStus Prolog. One set is inherited from DEC-10 Prolog. These predicates always refer to a file by specification. The other set of predicates is modeled after Quintus Prolog and refer to files as streams. Streams correspond to the file pointers used at the operating system level.

This second set of file manipulation predicates, the one involving streams, is supported by the ISO Prolog standard. Note that the notion of file is used here in a generalized sense; it may refer to a named file, the user's terminal, or some other device. The ISO Prolog standard refers to this generalized notion of file using the term source/sink.

A stream can be opened and connected to a file specification or file descriptor for input or output by calling the predicates open/[3,4]. These predicates will return a reference to a stream which may then be passed as an argument to various I/O predicates. Alternatively, a stream can be assigned an alias at the time of opening, and referred to by this alias afterwards. The predicate close/1 is used for closing a stream.

There are two types of streams, binary or text. Binary streams are seen as a sequence of bytes, i.e. integers in the range 0-255. Text streams, on the other hand, are considered a sequence of characters, represented by their character codes. SICStus Prolog handles wide characters, i.e. characters with codes larger than 255. The WCX (Wide Character eXtension) component of SICStus Prolog allows selecting various encoding schemes via environment variables or hook procedures; see Handling Wide Characters.

The predicates current_stream/3 and stream_property/2 are used for retrieving information about a stream, and for finding the currently existing streams.

Prolog streams can be accessed from C functions as well. See SICStus Streams, for details.

The possible formats of a stream are:

'$stream'(X)

A stream connected to some file. X is an integer.

Atom

A stream alias. Aliases can be associated with streams using the alias(Atom) option of open/4. There are also three predefined aliases:

user_input: An alias initially referring to the UNIX stdin stream. The alias can be changed with prolog_flag/3 and accessed by the C variable SP_stdin.
user_output: An alias initially referring to the UNIX stdout stream. The alias can be changed with prolog_flag/3 and accessed by the C variable SP_stdout.
user_error: An alias initially referring to the UNIX stderr stream. The alias can be changed with prolog_flag/3 and accessed by the C variable SP_stderr.
This stream is used by the Prolog top-level and debugger, and for system messages.

Certain I/O predicates manipulate streams implicitly, by maintaining the notion of a current input stream and a current output stream. The current input and output streams are set to the user_input and user_output initially and for every new break (see Nested). The predicate see/1 (tell/1) can be used for setting the current input (output) stream to newly opened streams for particular files. The predicate seen/0 (told/0) closes the current input (output) stream, and resets it to the standard input (output) stream. The predicate seeing/1 (telling/1) is used for retrieving the file name associated with the current input (output) streams.

The file specification user stands for the standard input or output stream, depending on context. Terminal output is only guaranteed to be displayed if the output stream is explicitly flushed.

A file specification FileSpec other than user must be an atom or a compound term. It is subject to syntactic rewriting. Depending on the operation, the resulting absolute filename is subject to further processing. Syntactic rewriting is performed wrt. a context directory Context, in the follows steps:

If FileSpec has the form PathAlias(File), it is rewritten by first looking up a clause of the hook predicate user:file_search_path(PathAlias,Expansion). If such a clause is found, and Expansion can be rewritten to the atomic file name FirstPart, and File can be rewritten to the atomic file name SecondPart, then FileSpec is rewritten to FirstPart/SecondPart.
On Windows, all \ characters are converted to /.
If FileSpec is a relative file name, Context is prepended to it.
FileSpec is normalized by dividing it into components and processing these components. A component is defined to be those characters:
1. Between the beginning of the file name and the end of the file name if there are no /s in the file name.
2. Between the beginning of the file name and the first /.
3. Between any two successive /-groups (where a /-group is defined to be a sequence of one or more /s with no non-/ character interspersed.) Each /-group is replaced by a single /. On Windows, however, a // prefix is not replaced by a single /.
4. Between the last / and the end of the file name.
To give the absolute file name, the following rules are applied to each component of FileSpec.
1. The component ~user, if encountered as the first component of FileSpec, is replaced by the absolute path of the home directory of user. If user doesn't exist, a permission error is raised. Not yet applicable on Windows.
2. The component ~, if encountered as the first component of FileSpec, is replaced by the absolute path of the home directory of the current user. On Windows, ~ is replaced by the user's home directory using the environment variables HOMEDRIVE and HOMEPATH.
3. The component $var, if encountered as the first component of FileSpec, is replaced by the value of the environment variable var. If var doesn't exist, a permission error is raised.
4. The component . is deleted.
5. The component .. is deleted together with the directory name syntactically preceding it. For example, a/b/../c is rewritten as a/c.
6. Any trailing / is deleted.
7. On Windows, the normalization process ensures that the absolute file name is either a network path //hostname/sharename/... or begins with a drive letter followed by :.

For example, asssuming the user's home directory is /users/clyde and given the clauses

     file_search_path(home, '$HOME').
     file_search_path(demo, home(prolog(demo))).
     file_search_path(prolog, prolog).

the file specification demo(mydemo) would be rewritten to '/users/clyde/prolog/demo/mydemo', since $HOME is interpreted as an environment variable (On UNIX, this is the user's home directory).

Failure to open a file normally causes an exception to be raised. This behavior can be turned off and on by of the built-in predicates nofileerrors/0 and fileerrors/0 described below.