module HexaPDF:: Filter
Overview¶ ↑
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 DCTDecode.
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.
Implementation of a Filter
Object
¶ ↑
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: PDF2.0 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!
See ::source_from_io
for a description of the pos
, length
and chunk_size
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.
Options:
- :pos
-
The position from where the reading should start. A negative position is treated as zero. Default: 0.
- :length
-
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.
- :chunk_size
-
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 FiberDoubleForString
that uses the string returned by the provided block and can be used as a source for decoders/encoders.
Returns a FiberDoubleForString
that returns the given string and can be used as a source for decoders/encoders.
Returns the concatenated string chunks retrieved by resuming the given source Fiber until it is dead.
The returned string is always a string with binary (= ASCII-8BIT
) encoding.