stream.rb in iostreams-1.0.0.beta2

- old
+ new

@@ -56,54 +56,10 @@
     def pipeline
       streams.pipeline
     end
 
     # Returns a Reader for reading a file / stream
-    #
-    # Parameters
-    #   file_name_or_io [String|IO]
-    #     The file_name of the file to write to, or an IO Stream that implements
-    #     #read.
-    #
-    #   streams [Symbol|Array]
-    #     The formats/streams that be used to convert the data whilst it is
-    #     being read.
-    #     When nil, the file_name will be inspected to try and determine what
-    #     streams should be applied.
-    #     Default: nil
-    #
-    #   file_name [String]
-    #     When `streams` is not supplied, `file_name` can be used for determining the streams
-    #     to apply to read the file/stream.
-    #     This is particularly useful when `file_name_or_io` is a stream, or a temporary file name.
-    #     Default: nil
-    #
-    # Example: Zip
-    #   IOStreams.reader('myfile.zip') do |stream|
-    #     puts stream.read
-    #   end
-    #
-    # Example: Encrypted Zip
-    #   IOStreams.reader('myfile.zip.enc') do |stream|
-    #     puts stream.read
-    #   end
-    #
-    # Example: Explicitly set the streams
-    #   IOStreams.reader('myfile.zip.enc', [:zip, :enc]) do |stream|
-    #     puts stream.read
-    #   end
-    #
-    # Example: Supply custom options
-    #   # Encrypt the file and get Symmetric Encryption to also compress it
-    #   IOStreams.reader('myfile.csv.enc', streams: enc: {compress: true}) do |stream|
-    #     puts stream.read
-    #   end
-    #
-    # Note:
-    # * Passes the file_name_or_io as-is into the block if it is already a reader stream AND
-    #   no streams are passed in.
-    #
     def reader(&block)
       streams.reader(io_stream, &block)
     end
 
     # Read an entire file into memory.
@@ -139,16 +95,16 @@
     # source = IOStreams.path("source_file").stream(encoding: "BINARY")
     # IOStreams.path("target_file.pgp").option(:pgp, passphrase: "hello").copy_from(source)
     def copy_from(source, convert: true)
       if convert
         stream = IOStreams.new(source)
-        streams.writer(io_stream) do |target|
+        writer do |target|
           stream.reader { |src| IO.copy_stream(src, target) }
         end
       else
         stream = source.is_a?(Stream) ? source.dup : IOStreams.new(source)
-        streams.dup.stream(:none).writer(io_stream) do |target|
+        dup.stream(:none).writer do |target|
           stream.stream(:none).reader { |src| IO.copy_stream(src, target) }
         end
       end
     end
 
@@ -180,30 +136,10 @@
     def each_row(**args, &block)
       row_reader(**args) { |row_stream| row_stream.each(&block) }
     end
 
     # Returns [Hash] of every record in a file or stream with support for headers.
-    #
-    # Reading a delimited stream and converting to tabular form.
-    #
-    # Each record / line is returned one at a time so that very large files
-    # can be read without having to load the entire file into memory.
-    #
-    # Embedded lines (within double quotes) will be skipped if
-    #   1. The file name contains .csv
-    #   2. Or the embedded_within argument is set
-    #
-    # Example: Supply custom options
-    #   IOStreams.each_record(file_name, embedded_within: '"') do |line|
-    #     puts line
-    #   end
-    #
-    # Example:
-    #   file_name = 'customer_data.csv.pgp'
-    #   IOStreams.each_record(file_name) do |hash|
-    #     p hash
-    #   end
     def each_record(**args, &block)
       record_reader(**args) { |record_stream| record_stream.each(&block) }
     end
 
     # Iterate over a file / stream returning each record/line one at a time.
@@ -227,61 +163,10 @@
         yield IOStreams::Record::Reader.new(io, **args)
       end
     end
 
     # Returns a Writer for writing to a file / stream
-    #
-    # Parameters
-    #   file_name_or_io [String|IO]
-    #     The file_name of the file to write to, or an IO Stream that implements
-    #     #write.
-    #
-    #   streams [Symbol|Array]
-    #     The formats/streams that be used to convert the data whilst it is
-    #     being written.
-    #     When nil, the file_name will be inspected to try and determine what
-    #     streams should be applied.
-    #     Default: nil
-    #
-    # Stream types / extensions supported:
-    #   .zip       Zip File                                   [ :zip ]
-    #   .gz, .gzip GZip File                                  [ :gzip ]
-    #   .enc       File Encrypted using symmetric encryption  [ :enc ]
-    #   other      All other extensions will be returned as:  [ :file ]
-    #
-    # When a file is encrypted, it may also be compressed:
-    #   .zip.enc  [ :zip, :enc ]
-    #   .gz.enc   [ :gz,  :enc ]
-    #
-    # Example: Zip
-    #   IOStreams.writer('myfile.zip') do |stream|
-    #     stream.write(data)
-    #   end
-    #
-    # Example: Encrypted Zip
-    #   IOStreams.writer('myfile.zip.enc') do |stream|
-    #     stream.write(data)
-    #   end
-    #
-    # Example: Explicitly set the streams
-    #   IOStreams.writer('myfile.zip.enc', [:zip, :enc]) do |stream|
-    #     stream.write(data)
-    #   end
-    #
-    # Example: Supply custom options
-    #   IOStreams.writer('myfile.csv.enc', [enc: { compress: true }]) do |stream|
-    #     stream.write(data)
-    #   end
-    #
-    # Example: Set internal filename when creating a zip file
-    #   IOStreams.writer('myfile.csv.zip', zip: { zip_file_name: 'myfile.csv' }) do |stream|
-    #     stream.write(data)
-    #   end
-    #
-    # Note:
-    # * Passes the file_name_or_io as-is into the block if it is already a writer stream AND
-    #   no streams are passed in.
     def writer(&block)
       streams.writer(io_stream, &block)
     end
 
     # Write entire string to file.
@@ -293,25 +178,35 @@
     #   block of memory at a time.
     def write(data)
       writer { |stream| stream.write(data) }
     end
 
-    def line_writer(**args)
-      writer { |io| yield IOStreams::Line::Writer.new(io, **args) }
+    def line_writer(**args, &block)
+      return block.call(io_stream) if io_stream && io_stream.is_a?(IOStreams::Line::Writer)
+
+      writer { |io| IOStreams::Line::Writer.stream(io, **args, &block) }
     end
 
-    def row_writer(delimiter: $/, **args)
-      line_writer(delimiter: delimiter) { |io| yield IOStreams::Row::Writer.new(io, **args) }
+    def row_writer(delimiter: $/, **args, &block)
+      return block.call(io_stream) if io_stream && io_stream.is_a?(IOStreams::Row::Writer)
+
+      line_writer(delimiter: delimiter) { |io| IOStreams::Row::Writer.stream(io, **args, &block) }
     end
 
-    def record_writer(delimiter: $/, **args)
-      line_writer(delimiter: delimiter) { |io| yield IOStreams::Record::Writer.new(io, **args) }
+    def record_writer(delimiter: $/, **args, &block)
+      return block.call(io_stream) if io_stream && io_stream.is_a?(IOStreams::Record::Writer)
+
+      line_writer(delimiter: delimiter) { |io| IOStreams::Record::Writer.stream(io, **args, &block) }
     end
 
     # Set/get the original file_name
     def file_name(file_name = :none)
-      file_name == :none ? streams.file_name : streams.file_name = file_name
-      self
+      if file_name == :none
+        streams.file_name
+      else
+        streams.file_name = file_name
+        self
+      end
     end
 
     # Set/get the original file_name
     def file_name=(file_name)
       streams.file_name = file_name