4 The COMMON-LISP Package

open

Function

Summary

Creates, opens, and returns a file stream that is connected to a specified file.

Package

common-lisp

Signature

open filespec &key direction element-type external-format if-exists if-does-not-exist => stream

Arguments

filespec: An external format spec, where the name can be:default.
direction: If direction is:probe, external-format is ignored. The element type and external format of the returned stream are undefined.
element-type: By default, the value oflw:*default-character-element-type* (the ANSI standard default ischaracter).
external-format: An external file format designator. By default, this is:default.
if-exists: What to do if the file stream already exists. The possible values for this are as in the ANSI standard.
if-does-not-exist: What to do if the file stream does not already exist. The possible values for this are as in the ANSI standard.

Values

stream: A file stream, ornil.

Description

If external-format has a name which is not:default and the parameters include:eol-style, it is used as is.

Otherwise, the system decides which external format to use viaguess-external-format. By default, this finds a match based on the filename; or (if that fails), looks in the EMACS-style (-*-) attribute line for an option calledencoding orexternal-format; or (if that fails), chooses from among likely encodings by analyzing the bytes near the start of the file. By default, it then also analyses the start of the file for byte patterns indicating the end-of-line style, and uses a default end-of-line style if no such pattern is found. This behavior is configurable.

After the external-format has been determined, it is verified usingvalid-external-format-p; an error is signalled if this check fails.

Ifopen gets:default as its element-type arg, it chooses the type on the basis of the external format. Ifopen gets an element-type other than:default and the direction is:input or:io, the argument must be a supertype of the type of characters produced by the external format; if the direction is:output or:io, it must be a subtype of the type of characters accepted by the external format; if it does not satisfy these requirements, an error is signalled.