This site is a static rendering of the Trac instance that was used by R7RS-WG1 for its work on R7RS-small (PDF), which was ratified in 2013. For more information, see Home. For a version of this page that may be more recent, see SettingsListsCowan in WG2's repo for R7RS-large.

Settings­Lists­Cowan

cowan
2012-12-03 01:04:39
9history
source

Settings lists

In this proposal, a filename passed to any of open-input-file, open-binary-input-file, open-output-file, open-binary-output-file, with-input-from-file, with-output-from-file, call-with-input-file, and call-with-output-file may be specified either as a string (as in R7RS-small) or as a settings list, which is a list of alternating keys and values where every key is a symbol. Quasiquote syntax is useful in creating settings lists. Specifying a string instead of a list is equivalent to specifying the settings list (path string). The following keys are defined by this proposal:

path
Specifies the filename to be opened. The interpretation of filenames is implementation-dependent. There is no default value, but implementations MAY accept other keys in lieu of this one for opening files or file-like objects that don't have string names. In particular, filenames on Posix are really u8-vectors with some u8 values disallowed, and filenames on Windows are really u16-vectors with some u16 values disallowed, and while most names of actual files are representable as strings, some may not be.
textual
If the value of this key is true, then a call to open-input-file, open-output-file, with-input-from-file, with-output-from-file, call-with-input-file, or call-with-output-file will allow textual operations and respond #t to textual-port?. If binary is specified as #t, binary operations may also be possible. However, textual and binary operations may not be mixed on a port unless the value of the char-buffer key is none. The value #f causes the key to be ignored.
binary
If the value of this key is true, then a call to open-input-file, open-output-file, with-input-from-file, with-output-from-file, call-with-input-file, or call-with-output-file will allow binary operations and respond #t to binary-port?. If textual is specified as #t, textual operations may also be possible. However, textual and binary operations may not be mixed on a port unless the value of the char-buffer key is none. It is an error to specify the value as #f on calls to open-binary-input-file or open-binary-output-file (which would be self-contradictory); otherwise, the value #f causes the key to be ignored.
bidirectional
Specifies that the port will respond #t to both input-port? and output-port?, and both input and output operations are accepted. However, it is an error to perform an input operation immediately followed by an output operation or vice versa; an intervening call to set-port-position! will suffice to separate them. The input and output side of the port may be closed separately using close-input-port and close-output-port; close-port will close both sides.
append
If the value of this key is true, the file pointer is moved to the end of file before every write operation. This is POSIX and Win32 O_APPEND.
create
If the value of this key is true, and the file specified by path does not exist, it will be created. This is POSIX and Win32 O_CREAT.
exclusive
If the value of this key is true, and the file specified by path exists, an error is signalled. This is only effective if the value of the create key is also true. This is POSIX and Win32 O_EXCL.
truncate
If the value of this key is true, and the file specified by 'path' exists, it is truncated to zero length. This is only effective if the file is being opened for output. This is POSIX and Win32 O_TRUNC.
buffer
For an output port, the value of this key defines when an output operation flushes a buffer associated with the output port. For an input port, the value defines how much data will be read to satisfy read operations. The value none means there is no buffering; the value block means there is a buffer of an implementation-dependent size. Buffer sizes are implementation-dependent. The default value is implementation-dependent.
char-buffer
Specifies what kind of character buffering is present on a textual port. Character buffering affects how much translation between characters and bytes is done all at once. The value none means no character buffering is employed; the value block means there is a buffer of an implementation-dependent size for translation. The value line is the same as block, except that on output, the character buffer as well as the binary buffer (if any) is flushed after each newline is output. Other values MAY be supported by an implementation. Buffer sizes are implementation-dependent. The default value is implementation-dependent.
encoding
Specifies what character encoding to use on a textual port. The (case insensitive) value us-ascii MUST be supported. The values iso-8859-1 and utf-8 SHOULD be supported if the implementation contains the appropriate repertoire of characters. Other values MAY be supported; they SHOULD appear in the IANA list of encodings. The default value is implementation-dependent. If a BOM (Byte Order Mark, U+FEFF) is present at the beginning of input on a port encoded as UTF-8, it is skipped. A BOM is not automatically written on output. Implementations MAY provide a way around this.
newline
Specifies how to translate newlines on a textual port. The value none means that no translation is performed. The values cr, lf, and crlf cause #\newline to be translated to CR, LF, or CR+LF respectively on output; all of them cause all of CR, LF, and CR+LF to be translated to #\newline on input. Other values MAY be supported by an implementation. The default value is implementation-dependent.
encoding-error
Specifies what action to take if a character cannot be encoded as bytes or a sequence of bytes cannot be decoded as a character in the specified encoding of a textual port. The value ignore means that the untranslatable byte or character is ignored. The value raise means that an error is signalled. The value replace means that an untranslatable byte is replaced by #\xFFFD; if that character is available in the implementation, or #\? if not, and an untranslatable character is replaced by the byte encoding of #xFFFD; if there is one, or #\? if not. The default value is implementation-dependent.

Implementations MAY support other keys, SHOULD warn if they detect keys or values they do not understand or implement, and MAY signal an error in such cases.

Settings lists are also used by other proposals: NetworkPortsCowan, DirectoryPortsCowan, ProcessPortsCowan.

Procedures

(native-encoding)

Returns a symbol suitable for use in a settings list to represent the native encoding used by the implementation.

(native-newline)

Returns a symbol suitable for use in a settings list to represent the native newline translation used by the implementation.

Possible additions