| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
Arguments: stream format
This function is called for its side-effects. Its return value is unspecified. This function configures the stream by adding or subtracting as many composing-stream encapsulations as are necessary to make it appropriate for the external-format specified by the format. This function will not be called directly. It is needed for lower-level things, like writing a setf method for stream-external-format on custom stream classes. (If you simply want to change the external format of an instance of an existing stream class, you simply setf its stream-external-format.)
This function configures the stream by adding or subtracting as many
composing-stream encapsulations as are necessary to match the shape of
the external-format. An encapsulating-stream-based composing format
(see Composed external
formats in iacl.htm) has exactly one base
stream and zero or more encapsulating composer formats. As of the 6.1
release, zero or one encapsulating composer formats can be used, and
only :e-crlf
and :e-crcrlf
composer formats have been created, but the potential exists for
chains of encapsulations, including ligatures and other
character-translation mappings.
If the format argument's name (as returned by
ef-name) is atomic (i.e. not
a list), the external-format is a base format and the
stream is configured with no composing-streams
encapsulating it. If the name is a list, then the format is an
encapsulating format, and the stream is configured with as many
composing-streams as there are composer formats. In the case of
(:e-crlf :latin1-base)
, for example, there is one
composer format, :e-crlf
, and thus the stream will
be configured to have one composing-stream associated with it.
Usually, stream encapsulations are accomplished by wrapping the encapsulator around the encapsulatee. However, this would force the user to use a different stream than the one which was originally opened, and the encapsulation as a whole would not have the same class/type as the original, nor would it have the same slots as the original stream, which would have been buried somewhere in the encapsulation chain. Therefore, when encapsulations are made for external-formats, the base stream stays on top, and retains its identity, class, and most of its slots, and the composing-stream encapsulations are instead placed within the base-stream.
You must load the :iodefs
module to use this
function. Do that by evaluating (require :iodefs)
. (It
is not an error to evaluate that form if the module is already
loaded.) This function is intended for implementing device-level
functionality and should not be used except for that purpose. See Simple-stream Description
in streams.htm for a description of the device-level.
See streams.htm.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |