class ZipTricks::OutputEnumerator
The output enumerator makes it possible to “pull” from a ZipTricks
streamer object instead of having it “push” writes to you. It will “stash” the block which writes the ZIP archive through the streamer, and when you call `each` on the Enumerator it will yield you the bytes the block writes. Since it is an enumerator you can use `next` to take chunks written by the ZipTricks
streamer one by one. It can be very convenient when you need to segment your ZIP output into bigger chunks for, say, uploading them to a cloud storage provider such as S3.
Another use of the output enumerator is outputting a ZIP archive from Rails or Rack, where an object responding to `each` is required which yields Strings. For instance, you can return a ZIP archive from Rack like so:
iterable_zip_body = ZipTricks::OutputEnumerator.new do | streamer | streamer.write_deflated_file('big.csv') do |sink| CSV(sink) do |csv_writer| csv_writer << Person.column_names Person.all.find_each do |person| csv_writer << person.attributes.values end end end end [200, {'Content-Type' => 'binary/octet-stream'}, iterable_zip_body]
Constants
- DEFAULT_WRITE_BUFFER_SIZE
Public Class Methods
Creates a new OutputEnumerator
.
@param streamer_options options for Streamer, see {ZipTricks::Streamer.new} @param write_buffer_size By default all ZipTricks
writes are unbuffered. For output to sockets
it is beneficial to bulkify those writes so that they are roughly sized to a socket buffer chunk. This object will bulkify writes for you in this way (so `each` will yield not on every call to `<<` from the Streamer but at block size boundaries or greater). Set it to 0 for unbuffered writes.
@param blk a block that will receive the Streamer object when executing. The block will not be executed
immediately but only once `each` is called on the OutputEnumerator
# File lib/zip_tricks/output_enumerator.rb, line 38 def initialize(write_buffer_size: DEFAULT_WRITE_BUFFER_SIZE, **streamer_options, &blk) @streamer_options = streamer_options.to_h @bufsize = write_buffer_size.to_i @archiving_block = blk end
Public Instance Methods
Executes the block given to the constructor with a {ZipTricks::Streamer} and passes each written chunk to the block given to the method. This allows one to “take” output of the ZIP piecewise. If called without a block will return an Enumerator that you can pull data from using `next`.
NOTE Because the `WriteBuffer` inside this object can reuse the buffer, it is important
that the `String` that is yielded **either** gets consumed eagerly (written byte-by-byte somewhere, or `#dup`-ed) since the write buffer will clear it after your block returns. If you expand this Enumerator eagerly into an Array you might notice that a lot of the segments of your ZIP output are empty - this means that you need to duplicate them.
@yield [String] a chunk of the ZIP output in binary encoding
# File lib/zip_tricks/output_enumerator.rb, line 56 def each if block_given? block_write = ZipTricks::BlockWrite.new { |chunk| yield(chunk) } buffer = ZipTricks::WriteBuffer.new(block_write, @bufsize) ZipTricks::Streamer.open(buffer, **@streamer_options, &@archiving_block) buffer.flush else enum_for(:each) end end