2.19.1.1 Supported types

ECL implements all stream types described in ANSI [see ANSI]. Additionally, when configured with option --enable-clos-streams, ECL includes a version of Gray streams where any object that implements the appropriate methods (stream-input-p, stream-read-char, etc) is a valid argument for the functions that expect streams, such as read, print, etc.

2.19.1.2 Element types

ECL distinguishes between two kinds of streams: character streams and byte streams. Character streams only accept and produce characters, written or read one by one, with write-char or read-char, or in chunks, with write-sequence or any of the Lisp printer functions. Character operations are conditioned by the external format, as described in External formats.

ANSI Common Lisp also supports binary streams. Here input and output is performed in chunks of bits. Binary streams are created with the function open passing as argument a subtype of integer and the implementation is free to round up that integer type to the closest size it supports. In particular ECL rounds up the size to a multiple of a byte. For example, the form (open "foo.bin" :direction :output :element-type '(unsigned-byte 13)), will open the file foo.bin for writing, using 16-bit words as the element type.

2.19.1.3 External formats

An external format is an encoding for characters that maps character codes to a sequence of bytes, in a one-to-one or one-to-many fashion. External formats are also known as "character encodings" in the programming world and are an essential ingredient to be able to read and write text in different languages and alphabets.

ECL has one of the most complete supports for external formats, covering all of the usual codepages from the Windows and Unix world, up to the more recent UTF-8, UCS-2 and UCS-4 formats, all of them with big and small endian variants, and considering different encodings for the newline character.

However, the set of supported external formats depends on the size of the space of character codes. When ECL is built with Unicode support (the default option), it can represent all known characters from all known codepages, and thus all external formats are supported. However, when ECL is built with the restricted character set, it can only use one codepage (the one provided by the C library), with a few variants for the representation of end-of-line characters.

In ECL, an external format designator is defined recursively as either a symbol or a list of symbols. The grammar is as follows

external-format-designator := 
   symbol |
   ( {symbol}+ )

and the table of known symbols is shown below. Note how some symbols (:cr, :little-endian, etc.) just modify other external formats.

2.19.2.1 File Stream Extensions

Function: open filespec &key direction element-type if-exists if-does-not-exist external-format close-on-exec nonblock ¶

Additional options for open include:

:close-on-exec

Child processes don’t inherit a copy of this stream: new processes created by fork and exec (for example by calling ext:run-program) close the stream after calling exec. Defaults to t.

:nonblock

Open fifos or device files in nonblocking mode. Defaults to nil.

These options are ignored on operating systems which do not support them.

Function: ext:set-buffering-mode stream mode ¶

Control the buffering mode of a stream

Synopsis

stream

an ANSI stream

mode

one of nil, :none, :line, :line-buffered, :full or :full-buffered

returns

The supplied stream

Description

If mode is nil or :none, stream will not be buffered, if it is :line or :line-buffered resp. :full or :fully-buffered, stream will be line resp. fully buffered. If the stream does not support buffering, nothing will happen.

Function: ext:file-stream-fd file-stream ¶

Return the POSIX file descriptor of file-stream as an integer

2.19.2.2 External Format Extensions

Variable: ext:*default-external-format* ¶

Default external format to use for reading from streams, dealing with filenames, etc. The default is to use utf-8 encoding if ECL is built with Unicode support.

Function: ext:all-encodings ¶

Return a list of all supported external formats

Condition: ext:character-coding-error ¶

Character coding error

Class Precedence List

ext:character-coding-error, error, serious-condition, condition, t

Methods

Function: ext:character-coding-error-external-format condition ¶

returns

The external format of condition

Description

Superclass of ext:character-encoding-error and ext:character-decoding-error.

Condition: ext:character-encoding-error ¶

Character encoding error

Class Precedence List

ext:character-encoding-error, ext:character-coding-error, error, serious-condition, condition, t

Methods

Function: ext:character-encoding-error-code condition ¶

returns

The character code of the character, which can’t be encoded

Description

Condition for characters, which can’t be encoded with some external format.

Condition: ext:character-decoding-error ¶

Character decoding error

Class Precedence List

ext:character-decoding-error, ext:character-coding-error, error, serious-condition, condition, t

Methods

Function: ext:character-decoding-error-octects condition ¶

returns

A list of integers with the values of the unsigned char’s which can’t be decoded.

Description

Condition for characters, which can’t be decoded with some external format.

Condition: ext:stream-encoding-error ¶

Stream encoding error

Class Precedence List

ext:stream-encoding-error, ext:character-encoding-error, ext:character-coding-error, stream-error, error, serious-condition, condition, t

Description

This condition is signaled when trying to write a character to a stream, which can’t be encoded with the streams external format.

Condition: ext:stream-decoding-error ¶

Stream decoding error

Class Precedence List

ext:stream-decoding-error, ext:character-decoding-error, ext:character-coding-error, stream-error, error, serious-condition, condition, t

Description

This condition is signaled when trying to read a character from a stream, which can’t be decoded with the streams external format.

Function: ext:encoding-error stream external-format code ¶

Signal a ext:stream-encoding-error with the given external-format and code. Make a restart available so that the error can be ignored or the character can be replaced with a different one.

Function: ext:decoding-error stream external-format octects ¶

Signal a ext:stream-decoding-error with the given external-format and octets. Make a restart available so that the error can be ignored or the octets can be replaced with a character.

2.19.2.3 Sequence Streams

System Class: ext:sequence-stream ¶

Class Precedence List

ext:sequence-stream, stream, t

Description

Sequence streams work similar to string streams for vectors. The supplied vectors that the streams read from or write to must have a byte sized element type, i.e. (signed-byte 8), (unsigned-byte 8) or base-char.

The semantics depend on the vector element type and the external format of the stream. If no external format is supplied and the element type is an integer type, the stream is a binary stream and accepts only integers of the same type as the element type of the vector. Otherwise, the stream accepts both characters and integers and converts them using the given external format. If the element type is base-char, the elements of the vectors are treated as bytes. This means that writing a character may use multiple elements of the vector, whose char-codes will be equal to the values of the bytes comprising the character in the given external format.

Function: ext:make-sequence-input-stream vector &key (start 0) (end nil) (external-format nil) ¶

Create a sequence input stream with the subsequence bounded by start and end of the given vector.

Function: ext:make-sequence-output-stream vector &key (external-format nil) ¶

Create a sequence output stream.

Example:

Using sequence streams to convert to a UTF8 encoded base string

CL-USER> (defvar *output* (make-array 20 :element-type 'base-char :adjustable t :fill-pointer 0))
*OUTPUT*
CL-USER> (defvar *stream* (ext:make-sequence-output-stream *output* :external-format :utf-8))
*STREAM*
CL-USER> (write-string "Spätzle mit Soß'" *stream*)
"Spätzle mit Soß'"
CL-USER> *output*
"Spätzle mit SoÃ\237'"

2.19.3.1 ANSI dictionary

Common Lisp and C equivalence