streamer.rb in zip_kit-6.2.1

- old
+ new

@@ -1,23 +1,23 @@
 # frozen_string_literal: true
 
 require "set"
 
-# Is used to write streamed ZIP archives into the provided IO-ish object.
-# The output IO is never going to be rewound or seeked, so the output
-# of this object can be coupled directly to, say, a Rack output. The
-# output can also be a String, Array or anything that responds to `<<`.
+# Is used to write ZIP archives without having to read them back or to overwrite
+# data. It outputs into any object that supports `<<` or `write`, namely:
 #
-# Allows for splicing raw files (for "stored" entries without compression)
-# and splicing of deflated files (for "deflated" storage mode).
+# An `Array`, `File`, `IO`, `Socket` and even `String` all can be output destinations
+# for the `Streamer`.
 #
-# For stored entries, you need to know the CRC32 (as a uint) and the filesize upfront,
+# You can also combine output through the `Streamer` with direct output to the destination,
+# all while preserving the correct offsets in the ZIP file structures. This allows usage
+# of `sendfile()` or socket `splice()` calls for "through" proxying.
+#
+# If you want to avoid data descriptors - or write data bypassing the Streamer -
+# you need to know the CRC32 (as a uint) and the filesize upfront,
 # before the writing of the entry body starts.
 #
-# Any object that responds to `<<` can be used as the Streamer target - you can use
-# a String, an Array, a Socket or a File, at your leisure.
-#
 # ## Using the Streamer with runtime compression
 #
 # You can use the Streamer with data descriptors (the CRC32 and the sizes will be
 # written after the file data). This allows non-rewinding on-the-fly compression.
 # The streamer will pick the optimum compression method ("stored" or "deflated")
@@ -32,10 +32,10 @@
 #       zip.write_file('long-novel.txt') do |sink|
 #         File.open('novel.txt', 'rb'){|source| IO.copy_stream(source, sink) }
 #       end
 #     end
 #
-# The central directory will be written automatically at the end of the block.
+# The central directory will be written automatically at the end of the `open` block.
 #
 # ## Using the Streamer with entries of known size and having a known CRC32 checksum
 #
 # Streamer allows "IO splicing" - in this mode it will only control the metadata output,
 # but you can write the data to the socket/file outside of the Streamer. For example, when