multistream.codec
Core multistream codec protocols and functions.
*eof-guard*
dynamic
When bound, decoder streams will return this instead of throwing an exception when the end of the input stream is reached.
Codec
protocol
A codec provides a central place for collecting options and producing new stream instances.
members
decode-byte-stream
(decode-byte-stream codec header input-stream)
Apply decoding to the given stream of bytes. The stream should be a java.io.InputStream
instance.
This method should return either another InputStream
or a DecoderStream
.
decode-value-stream
(decode-value-stream codec header decoder-stream)
Wrap decoding logic around the values produced by the given decoder stream.
encode-byte-stream
(encode-byte-stream codec selector output-stream)
Apply encoding to the given stream of bytes. The stream should be a java.io.OutputStream
instance.
This method should return either another OutputStream
or an EncoderStream
.
encode-value-stream
(encode-value-stream codec selector encoder-stream)
Wrap encoding logic around the values produced by the given encoder stream.
processable?
(processable? codec header)
True if this codec can process the given header.
select-header
(select-header codec selector)
Generate the header string to use for this codec. This defaults to the codec’s :header
field.
CodecFactory
protocol
A codec factory supports the creation of encoder and decoder streams by composing codecs together.
members
decoder-stream
(decoder-stream factory input)
Open a new decoding stream to read values from the given byte input. This reads headers from the stream to select codecs.
encoder-stream
(encoder-stream factory selectors output)
Open a new encoder stream to write values to the given byte output.
The selectors
argument may be a vector of either codec keys or headers processable by one of the codecs in the factory.
decode
(decode codec-or-factory input)
Decodes the given byte array using either a direct codec or a multicodec factory.
DecoderStream
protocol
A stream which can be used to decode values from some underlying byte input stream.
members
read!
(read! stream)
Read the next value from the underlying byte stream. Returns the decoded value, or throws an exception on error.
If the end of the stream has been reached, this method should return the value of *eof-guard*
if it is bound, or throw an ex-info with :type
:multistream.codec/eof
.
defcodec
macro
(defcodec name-sym attr-vec & more)
Define a new codec, filling in the protocol with default method implementations.
The autogenerated constructors will be private.
defdecoder
macro
(defdecoder name-sym attr-vec read-form & more)
Define a new decoder stream record, filling in the protocol, Closeable
, and IReduceInit
implementations. The first record attribute must be the wrapped stream.
The autogenerated constructors will be private.
defencoder
macro
(defencoder name-sym attr-vec write-form & more)
Define a new encoder stream record, filling in the protocol and Closeable
implementation. The first record attribute must be the wrapped stream.
The autogenerated constructors will be private.
encode
(encode codec value)
(encode factory selectors value)
Encodes the given value using either a direct codec or a multicodec factory and the given selectors. Returns a byte array containing the encoded value, or throws an exception on error.
EncoderStream
protocol
A stream which can be used to encode values to some underlying byte output stream.
members
write!
(write! stream value)
Write the value as a sequence of bytes to the stream. Returns the number of bytes the value was encoded to, though this may be different than the final bytes written.
This method should throw an exception if the value cannot be written.
headers
Map of codec keywords to header paths, drawn from the multicodec standards document.
multi
(multi & {:as codecs})
Construct a new multiplexing codec factory.
The arguments to this function should be key/codec pairs to register with the factory.