open/4

open(@source_sink, @io_mode, -stream, @open_options) [ISO]

This predicate opens a source/sink which is a stream with specified open-options. The open-options is a list of stream options with no variables as an element.

The first parameter is the location of the source/sink, if the location contains backslash characters then be sure to replace each single backslash character with two backslash characters, for instance: if the file to open is 'c:\temp\test.txt' then the value of the first parameter must be 'c:\\temp\\test.txt' (see also escape sequences).

The second parameter must be one of the following predefined atoms:

read: the source/sink is a source, if it is a file then the file must already exist and the input starts at the beginning of the file.
write: the source/sink is a sink. If the sink already exists then it is emptied (initial content is lost) and output starts at the beginning. If the sink does not exist then it is created.
append: the source/sink is a sink. If the sink already exists then output starts at the end of that sink, else an empty sink is created.

If a stream is successfully opened then the third parameter '-stream' is assigned a non atomic ground term.

The open-options list supports the following stream-options:

type(T): specifies whether the stream is a text stream or a binary stream. T can be one of the values
- text: the stream is a text stream (default).
- binary: the stream is a binary stream.
reposition(bool): 'bool' will be true or false. The console stream cannot be repositioned but file streams can be repositioned if this parameters is set to true.
- true: it is possible to reposition the stream.
- false: it is not possible to reposition the stream (false).
alias(name): 'name' will be an atom used as an alias to denote the stream. The standard input stream has the default alias 'user_input' and the standard output stream has the default alias 'user_output'.
eof_action(action): the effect of attempting to input from a stream whose position is past-end-of-stream will be specified by the value of the atom 'action':
- error: a permission-error exception is thrown to indicate that there is no more input (default).
- eof_code: the result of input is the end-of-stream code.
- reset: the stream position is reset so that it is not past-end-of-stream anymore and an attempt is made to read input from the stream again.

Example
open('c:\\temp\\new3.txt', write, Stream, [alias(str)]).	a file 'c:\temp\new3.txt' is created (or overwritten) and the alias 'str' is associated with the text output stream
open('c:\\temp\\new3.txt', read, Stream, [type(binary), reposition(true), alias(newfile), eof_action(eof_code)]).	if there is a file at the location 'c:\temp\new3.txt' then it was successfully opened and Stream was assigned the value '$stream(3)', if there are no other streams except the standard streams, the stream is a binary stream which can be repositioned and it has the alias 'newfile' and if input is read past-end-of-stream then the end-of-file code is returned

Exceptions
source_sink is a variable	an instantiation_error exception is thrown
source_sink is neither a variable nor a source/sink term	a domain_error(source_sink, SourceSink) exception is thrown, variable SourceSink is substituted by the incorrect source/sink term
the source/sink specified by SourceSink does not exist	an existence_error(source_sink, SourceSink) exception is thrown
the source/sink specified by SourceSink cannot be opened	a permission_error(open, source_sink, SourceSink) exception is thrown
io_mode is a variable	an instantiation_error exception is thrown
io_mode is neither a variable nor an atom	a type_error(atom, IOMode) exception is thrown
io_mode is an atom but not an I/O mode	a domain_error(io_mode, IOMode) exception is thrown
Stream is not a variable	a type_error(variable, Stream) exception is thrown
Options is a variable	an instantiation_error exception is thrown
Options is a list with an element E which is a variable	an instantiation_error exception is thrown
Options is neither a variable nor a list	a type_error(list, Options) exception is thrown
an element E of the options list is neither a variable nor a valid stream-option	a domain_error(stream_option, E) exception is thrown
an element E of the options list is alias(A) and A is already associated with an open stream	a permission_error(open, source_sink, alias(A)) exception is thrown
an element E of the options list is reposition(true) and it is not possible to reposition this stream	a permission_error(open, source_sink, reposition(true)) exception is thrown

info@trinc-prolog.com