A stream filter is used to compress a stream or to encode it in an ASCII compatible way; or to reverse this process. Some filters can be used for any content, like
FlateDecode, others are specifically designed for image streams, like
Each filter is implemented via fibers. This allows
HexaPDF to easily process either small chunks or a whole stream at once, depending on the memory restrictions and to create flexible filter pipelines.
It also allows the easy re-processing of a stream without first decoding and the encoding it. Such functionality is useful, for example, when a PDF file should be decrypted and streams compressed in one step.
Each filter is an object (normally a module) that responds to two methods: #encoder and #decoder. Both of these methods are given a source (a Fiber) and options (a Hash) and have to return a Fiber object.
The returned fiber should resume the source fiber to get the next chunk of binary data (possibly only one byte of data, so this situation should be handled gracefully). Once the fiber has processed this chunk, it should yield the processed chunk as binary string. This should be done as long as the source fiber is alive? and doesn't return
nil when resumed.
Such a fiber should not return
nil unless this signifies that no more data is coming!
See: PDF1.7 s7.4
Public Class Methods
Returns a Fiber that can be used as a source for decoders/encoders and that reads chunks from a file.
Note that there will be a problem if the size of the file changes between the invocation of this method and the actual consumption of the file!
::source_from_io for a description of the available options.
Returns a Fiber that can be used as a source for decoders/encoders and that reads chunks of data from an IO object.
Each time a chunk is read, the position pointer of the IO is adjusted. This should be taken into account when working with the IO object.
The position from where the reading should start. A negative position is treated as zero. Default: 0.
The length indicating the number of bytes to read. An error is raised if not all specified bytes could be read. A negative length means reading until the end of the IO stream. Default: -1.
The size of the chunks that should be returned in each iteration. A chunk size of less than or equal to 0 means using the biggest chunk size available (can change between versions!). Default: 0.
Returns a Fiber that can be used as a source for decoders/encoders and that is based on a String object.
Returns the concatenated string chunks retrieved by resuming the given source Fiber until it is dead.
The returned string is always a string with