open/[3,4] [ISO]open(+FileSpec, +Mode, -Stream)
open(+FileSpec, +Mode, -Stream, +Options)
Creates a Prolog stream by opening the file FileSpec in mode Mode with options Options.
A file specification.
[read,write,append], must be nonvar
An atom specifying the open mode of the target file. One of:
readwriteappendA list of zero or more of the following.
type(+T)text or binary
stream. Default is text.
reposition(+Boolean)true), or not (false). The latter is the default.
For text streams reposition(true) affects the default
eol/1 and encoding_signature/1 options, see below. Also, not all encodings supports this
option (see ref-iou-sfh-enc).
alias(+A)eof_action(+Action)end_of_file), and a
further attempt to input is made. Action can have the following
values:
erroreof_codeend_of_file) is returned
again.
resetencoding(Encoding)Specifies the encoding to use if the stream is opened in text mode, as
an atom. The default is 'ISO-8859-1', the 8 bit subset of
UNICODE, i.e. “ISO-8859-1” (Latin 1) (see ref-iou-sfh-enc).
Overridden by the encoding_signature/1 option, see below.
encoding_signature(+Boolean)true),
or not (false). An encoding signature is a special byte
sequence that identifies the encoding used in the file. The most
common case is one of the Unicode signatures, often called “byte
order mark” (BOM).
A Unicode signature is a special byte sequence that can be used to distinguish between several UTF encoding variants, such as “UTF-8”, “UTF-16-BE” and “UTF-16-LE”.
If reposition(true) is specified, then
encoding_signature/1 defaults to false for both streams
opened in write mode and streams opened in read mode.
If reposition(true) is not specified,
if the file is opened in mode read then encoding_signature/1
defaults to true.
When encoding_signature/1 option is
true additional heuristics will be used if no Unicode signature
is detected. Only if neither a Unicode signature nor these heuristics
specifies a character encoding will the encoding/1 option, if
any, be used.
The method used for selecting character encoding when a text file is
opened in mode read is the first applicable item in the
following list:
encoding_signature/1 option is true:
If a byte order mark is detected it will be used to select
between the encodings “UTF-8”, “UTF-16” or “UTF-32” with
suitable endianess.
encoding_signature/1 option is true:
If an Emacs style ‘-*- coding: coding-system-*-’ is present on the first non-empty line of the
file then it will be used.
encoding(ENCODING) Is supplied, the specified encoding will be used.
the character encoding selected in this way will be used if it is recognized, otherwise an error exception is raised.
If reposition(true) is not specified,
if the file is opened in mode write then it depends on the character
encoding whether an encoding signature will be output by default or not. If you want
to force an encoding signature to be output for those encodings that supports it you
can specify encoding_signature(true). Conversely, if you want to prevent an
encoding signature from being output you can explicitly specify encoding_signature(false).
All UTF encodings supports an encoding signature in the form of a BOM. “UTF-8” does not write a BOM unless
you explicitly specify encoding_signature(true), the 16 and 32 bit UTF
encodings, e.g. “UTF-16 BE”, “UTF-32 LE” writes a BOM unless
explicitly requested not to with encoding_signature(false).
If the file is opened in mode append then encoding_signature/1 defaults to
false.
eol(Eol)In Prolog code, end of line is always represented by the character
'\n', which has character code 10, i.e. the same as ASCII Line
Feed (<LFD>). The representation in the file may be different, however.
Eol can have the following values:
lfLF, character code 10) is used to specify a end of line.
This can be used for both read mode and write mode streams.
crlfCR, character code 13) followed
by Line Feed (LF, character code 10) is used to specify a end of
line.
This can be used for both read mode and write mode streams.
autoCR LF and single
CR or LF into an end of line character.
This can be used only for read mode streams.
defaultIf reposition(true) is specified, then this uses lf for
both streams opened in write mode and streams opened in read mode, on
all platforms.
If reposition(true) is not specified, then under
UNIX, this uses lf for streams opened in write mode and
auto for streams opened in read mode. Under Windows, this uses
crlf for streams opened in write mode and auto for
streams opened in read mode.
This can be used for both read mode and write mode streams.
if_exists(+Action)write or append. Action can have the
following values:
defaulterrorgenerate_unique_namestream_property(Stream, file_name(RealName)) on the
resulting stream. See the example below.
With this option open/4 will never open an existing file but it
may still fail to find a unique name. open/4 may fail to find a
unique name if there are thousands of files with similar names. In
that case open/4 behaves as if if_exists(error) had been
passed.
If FileSpec is a valid file specification, the file that it denotes is opened in mode Mode.
The resulting stream is unified with Stream.
Stream is used as an argument to Prolog input and output predicates.
Stream can also be converted to the corresponding foreign
representation through stream_code/2 and used in foreign code to
perform input/output operations.
instantiation_errortype_errordomain_errorread, write or append.
Options has an undefined option or an element in Options
is out of the domain of the option.
existence_errorpermission_errorresource_errorThe following example creates two log files, both based on the the base name my.log. The files will be written to a directory suitable for temporary files (see ref-fdi-fsp-pre).
| ?- open(temp('my.log'), write, S1, [if_exists(generate_unique_name)]),
open(temp('my.log'), write, S2, [if_exists(generate_unique_name)]),
stream_property(S1, file_name(N1)),
stream_property(S2, file_name(N2)),
format('Logging to ~a and ~a~n', [N1, N2]),
...
Under UNIX this would produce something like:
Logging to /tmp/my.log and /tmp/my1886415233.log