compose-encapsulating-streams

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-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.