iostreams 1.0.0.beta7 → 1.0.0

data/lib/io_streams/io_streams.rb

@@ -37,15 +37,15 @@ module IOStreams
   #    # => "files/file.xls"
   #
   # For Files
-  # IOStreams.path('blah.zip').option(:encode, encoding: 'BINARY').each_line { |line puts line }
-  # IOStreams.path('blah.zip').option(:encode, encoding: 'UTF-8').each_line.first
-  # IOStreams.path('blah.zip').option(:encode, encoding: 'UTF-8').each_record.last
-  # IOStreams.path('blah.zip').option(:encode, encoding: 'UTF-8').each_record.size
+  # IOStreams.path('blah.zip').option(:encode, encoding: 'BINARY').each(:line) { |line| puts line }
+  # IOStreams.path('blah.zip').option(:encode, encoding: 'UTF-8').each(:line).first
+  # IOStreams.path('blah.zip').option(:encode, encoding: 'UTF-8').each(:hash).last
+  # IOStreams.path('blah.zip').option(:encode, encoding: 'UTF-8').each(:hash).size
   # IOStreams.path('blah.zip').option(:encode, encoding: 'UTF-8').reader.size
-  # IOStreams.path('blah.csv.zip').each_line { |line puts line }
-  # IOStreams.path('blah.zip').option(:pgp, passphrase: 'receiver_passphrase').reader(&:read)
-  # IOStreams.path('blah.zip').stream(:zip).stream(:pgp, passphrase: 'receiver_passphrase').reader(&:read)
-  # IOStreams.path('blah.zip').stream(:zip).stream(:encode, encoding: 'BINARY').reader(&:read)
+  # IOStreams.path('blah.csv.zip').each(:line) { |line| puts line }
+  # IOStreams.path('blah.zip').option(:pgp, passphrase: 'receiver_passphrase').read
+  # IOStreams.path('blah.zip').stream(:zip).stream(:pgp, passphrase: 'receiver_passphrase').read
+  # IOStreams.path('blah.zip').stream(:zip).stream(:encode, encoding: 'BINARY').read
   #
   def self.path(*elements, **args)
     return elements.first if (elements.size == 1) && args.empty? && elements.first.is_a?(IOStreams::Path)
@@ -59,9 +59,9 @@ module IOStreams
 
   # For an existing IO Stream
   # IOStreams.stream(io).file_name('blah.zip').encoding('BINARY').reader(&:read)
-  # IOStreams.stream(io).file_name('blah.zip').encoding('BINARY').each_line(...)
-  # IOStreams.stream(io).file_name('blah.csv.zip').each_line(...)
-  # IOStreams.stream(io).stream(:zip).stream(:pgp, passphrase: 'receiver_passphrase').reader(&:read)
+  # IOStreams.stream(io).file_name('blah.zip').encoding('BINARY').each(:line){ ... }
+  # IOStreams.stream(io).file_name('blah.csv.zip').each(:line) { ... }
+  # IOStreams.stream(io).stream(:zip).stream(:pgp, passphrase: 'receiver_passphrase').read
   def self.stream(io_stream)
     return io_stream if io_stream.is_a?(Stream)
 

data/lib/io_streams/line/writer.rb

@@ -32,7 +32,7 @@ module IOStreams
       # Write a line to the output stream
       #
       # Example:
-      #   IOStreams.line_writer('a.txt') do |stream|
+      #   IOStreams.path('a.txt').writer(:line) do |stream|
       #     stream << 'first line' << 'second line'
       #   end
       def <<(data)
@@ -44,7 +44,7 @@ module IOStreams
       # Returns [Integer] the number of bytes written.
       #
       # Example:
-      #   IOStreams.line_writer('a.txt') do |stream|
+      #   IOStreams.path('a.txt').writer(:line) do |stream|
       #     count = stream.write('first line')
       #     puts "Wrote #{count} bytes to the output file, including the delimiter"
       #   end

data/lib/io_streams/path.rb

@@ -8,7 +8,7 @@ module IOStreams
 
       @path      = path.frozen? ? path : path.dup.freeze
       @io_stream = nil
-      @streams   = nil
+      @builder   = nil
     end
 
     # If elements already contains the current path then it is used as is without
@@ -20,7 +20,7 @@ module IOStreams
       relative = ::File.join(*elements)
 
       new_path         = dup
-      new_path.streams = nil
+      new_path.builder = nil
       new_path.path    = relative.start_with?(path) ? relative : ::File.join(path, relative)
       new_path
     end
@@ -117,7 +117,7 @@ module IOStreams
     #   IOStreams.path(".profile").directory        #=> "."
     def directory
       new_path         = dup
-      new_path.streams = nil
+      new_path.builder = nil
       new_path.path    = ::File.dirname(path)
       new_path
     end
@@ -188,15 +188,15 @@ module IOStreams
 
     def inspect
       str = "#<#{self.class.name}:#{path}"
-      str << " @streams=#{streams.streams.inspect}" if streams.streams
-      str << " @options=#{streams.options.inspect}" if streams.options
+      str << " @builder=#{builder.streams.inspect}" if builder.streams
+      str << " @options=#{builder.options.inspect}" if builder.options
       str << " pipeline=#{pipeline.inspect}>"
     end
 
     private
 
-    def streams
-      @streams ||= IOStreams::Streams.new(path)
+    def builder
+      @builder ||= IOStreams::Builder.new(path)
     end
   end
 end

data/lib/io_streams/paths/file.rb

@@ -3,6 +3,13 @@ require "fileutils"
 module IOStreams
   module Paths
     class File < IOStreams::Path
+      attr_accessor :create_path
+
+      def initialize(file_name, create_path: true)
+        @create_path = create_path
+        super(file_name)
+      end
+
       # Yields Paths within the current path.
       #
       # Examples:
@@ -146,9 +153,11 @@ module IOStreams
         self.class.new(::File.realpath(path))
       end
 
+      private
+
       # Read from file
-      def reader(&block)
-        ::File.open(path, "rb") { |io| streams.reader(io, &block) }
+      def stream_reader(&block)
+        ::File.open(path, "rb") { |io| builder.reader(io, &block) }
       end
 
       # Write to file
@@ -156,10 +165,10 @@ module IOStreams
       # Note:
       #   If an exception is raised whilst the file is being written to the file is removed to
       #   prevent incomplete / partial files from being created.
-      def writer(create_path: true, &block)
+      def stream_writer(&block)
         mkpath if create_path
         begin
-          ::File.open(path, "wb") { |io| streams.writer(io, &block) }
+          ::File.open(path, "wb") { |io| builder.writer(io, &block) }
         rescue StandardError => e
           ::File.unlink(path) if ::File.exist?(path)
           raise(e)

data/lib/io_streams/paths/http.rb

@@ -47,6 +47,8 @@ module IOStreams
         url
       end
 
+      private
+
       # Read a file using an http get.
       #
       # For example:
@@ -57,7 +59,7 @@ module IOStreams
       #
       # Notes:
       # * Since Net::HTTP download only supports a push stream, the data is streamed into a tempfile first.
-      def reader(&block)
+      def stream_reader(&block)
         handle_redirects(url, http_redirect_count, &block)
       end
 
@@ -91,7 +93,7 @@ module IOStreams
             Utils.temp_file_name('iostreams_http') do |file_name|
               ::File.open(file_name, 'wb') { |io| response.read_body { |chunk| io.write(chunk) } }
               # Return a read stream
-              result = ::File.open(file_name, "rb") { |io| streams.reader(io, &block) }
+              result = ::File.open(file_name, "rb") { |io| builder.reader(io, &block) }
             end
           end
         end

data/lib/io_streams/paths/s3.rb

@@ -208,12 +208,12 @@ module IOStreams
       # TODO: delete_all
 
       # Read from AWS S3 file.
-      def reader(&block)
+      def stream_reader(&block)
         # Since S3 download only supports a push stream, write it to a tempfile first.
         Utils.temp_file_name("iostreams_s3") do |file_name|
           read_file(file_name)
 
-          ::File.open(file_name, "rb") { |io| streams.reader(io, &block) }
+          ::File.open(file_name, "rb") { |io| builder.reader(io, &block) }
         end
       end
 
@@ -231,10 +231,10 @@ module IOStreams
       #   aborted and this error is raised.  The raised error has a `#errors`
       #   method that returns the failures that caused the upload to be
       #   aborted.
-      def writer(&block)
+      def stream_writer(&block)
         # Since S3 upload only supports a pull stream, write it to a tempfile first.
         Utils.temp_file_name("iostreams_s3") do |file_name|
-          result = ::File.open(file_name, "wb") { |io| streams.writer(io, &block) }
+          result = ::File.open(file_name, "wb") { |io| builder.writer(io, &block) }
 
           # Upload file only once all data has been written to it
           write_file(file_name)

data/lib/io_streams/paths/sftp.rb

@@ -2,6 +2,26 @@ require 'open3'
 
 module IOStreams
   module Paths
+    # Read a file from a remote sftp server.
+    #
+    # Example:
+    #   IOStreams.
+    #     path("sftp://example.org/path/file.txt", username: "jbloggs", password: "secret", compression: false).
+    #     reader do |input|
+    #       puts input.read
+    #     end
+    #
+    # Note:
+    # - raises Net::SFTP::StatusException when the file could not be read.
+    #
+    # Write to a file on a remote sftp server.
+    #
+    # Example:
+    #   IOStreams.
+    #     path("sftp://example.org/path/file.txt", username: "jbloggs", password: "secret", compression: false).
+    #     writer do |output|
+    #       output.write('Hello World')
+    #     end
     class SFTP < IOStreams::Path
       include SemanticLogger::Loggable if defined?(SemanticLogger)
 
@@ -54,7 +74,7 @@ module IOStreams
       #   IOStreams.path("sftp://test.com/path/file_name.csv", username: "jack", IdentityFile: "~/.ssh/private_key").reader do |io|
       #     puts io.read
       #   end
-      def initialize(url, username: nil, password: nil, ruby: true, ssh_options: {})
+      def initialize(url, username: nil, password: nil, ssh_options: {})
         uri = Utils::URI.new(url)
         raise(ArgumentError, "Invalid URL. Required Format: 'sftp://<host_name>/<file_name>'") unless uri.scheme == 'sftp'
 
@@ -87,40 +107,6 @@ module IOStreams
         self
       end
 
-      # Read a file from a remote sftp server.
-      #
-      # Example:
-      #   IOStreams.
-      #     path("sftp://example.org/path/file.txt", username: "jbloggs", password: "secret", compression: false).
-      #     reader do |input|
-      #       puts input.read
-      #     end
-      #
-      # Note:
-      # - raises Net::SFTP::StatusException when the file could not be read.
-      def reader(&block)
-        IOStreams.temp_file("iostreams-sftp-reader") do |temp_file|
-          sftp_download(path, temp_file.to_s)
-          ::File.open(temp_file.to_s, "rb") { |io| streams.reader(io, &block) }
-        end
-      end
-
-      # Write to a file on a remote sftp server.
-      #
-      # Example:
-      #   IOStreams.
-      #     path("sftp://example.org/path/file.txt", username: "jbloggs", password: "secret", compression: false).
-      #     writer do |output|
-      #       output.write('Hello World')
-      #     end
-      def writer(&block)
-        IOStreams.temp_file("iostreams-sftp-writer") do |temp_file|
-          ::File.open(temp_file.to_s, "wb") { |io| streams.writer(io, &block) }
-          sftp_upload(temp_file.to_s, path)
-          temp_file.size
-        end
-      end
-
       # TODO: Add #copy_from shortcut to detect when a file is supplied that does not require conversion.
 
       # Search for files on the remote sftp server that match the provided pattern.
@@ -147,7 +133,7 @@ module IOStreams
         Net::SFTP.start(hostname, username, build_ssh_options) do |sftp|
           sftp.dir.glob(".", pattern, flags) do |path|
             next if !directories && !path.file?
-            new_path = self.class.new("sftp://#{hostname}/#{path.name}", username: username, password: password, ruby: ruby, **ssh_options)
+            new_path = self.class.new("sftp://#{hostname}/#{path.name}", username: username, password: password, **ssh_options)
             yield(new_path, path.attributes.attributes)
           end
         end
@@ -158,6 +144,21 @@ module IOStreams
 
       attr_reader :password
 
+      def stream_reader(&block)
+        IOStreams.temp_file("iostreams-sftp-reader") do |temp_file|
+          sftp_download(path, temp_file.to_s)
+          ::File.open(temp_file.to_s, "rb") { |io| builder.reader(io, &block) }
+        end
+      end
+
+      def stream_writer(&block)
+        IOStreams.temp_file("iostreams-sftp-writer") do |temp_file|
+          ::File.open(temp_file.to_s, "wb") { |io| builder.writer(io, &block) }
+          sftp_upload(temp_file.to_s, path)
+          temp_file.size
+        end
+      end
+
       # Use sftp and sshpass executables to download to a local file
       def sftp_download(remote_file_name, local_file_name)
         with_sftp_args do |args|

data/lib/io_streams/pgp/reader.rb

@@ -21,7 +21,9 @@ module IOStreams
       #
       # passphrase: [String]
       #   Pass phrase for private key to decrypt the file with
-      def self.file(file_name, passphrase: self.default_passphrase)
+      def self.file(file_name, passphrase: nil)
+        # Cannot use `passphrase: self.default_passphrase` since it is considered private
+        passphrase ||= default_passphrase
         raise(ArgumentError, 'Missing both passphrase and IOStreams::Pgp::Reader.default_passphrase') unless passphrase
 
         loopback = IOStreams::Pgp.pgp_version.to_f >= 2.1 ? '--pinentry-mode loopback' : ''

data/lib/io_streams/record/writer.rb

@@ -1,7 +1,7 @@
 module IOStreams
   module Record
     # Example, implied header from first record:
-    #   IOStreams.path('file.csv').record_writer do |stream|
+    #   IOStreams.path('file.csv').writer(:hash) do |stream|
     #     stream << {name: 'Jack', address: 'Somewhere', zipcode: 12345}
     #     stream << {name: 'Joe', address: 'Lost', zipcode: 32443, age: 23}
     #   end

data/lib/io_streams/row/writer.rb

@@ -2,7 +2,7 @@ require 'csv'
 module IOStreams
   module Row
     # Example:
-    #   IOStreams.path("file.csv").row_writer do |stream|
+    #   IOStreams.path("file.csv").writer(:array) do |stream|
     #     stream << ['name', 'address', 'zipcode']
     #     stream << ['Jack', 'Somewhere', 12345]
     #     stream << ['Joe', 'Lost', 32443]

data/lib/io_streams/stream.rb

@@ -1,14 +1,14 @@
 module IOStreams
   class Stream
     attr_reader :io_stream
-    attr_writer :streams
+    attr_writer :builder
 
     def initialize(io_stream)
       raise(ArgumentError, 'io_stream cannot be nil') if io_stream.nil?
       raise(ArgumentError, "io_stream must not be a string: #{io_stream.inspect}") if io_stream.is_a?(String)
 
       @io_stream = io_stream
-      @streams   = nil
+      @builder   = nil
     end
 
     # Ignore the filename and use only the supplied streams.
@@ -19,7 +19,7 @@ module IOStreams
     #
     # IOStreams.path('tempfile2527').stream(:zip).stream(:pgp, passphrase: 'receiver_passphrase').reader(&:read)
     def stream(stream, **options)
-      streams.stream(stream, **options)
+      builder.stream(stream, **options)
       self
     end
 
@@ -34,32 +34,76 @@ module IOStreams
     #
     # IOStreams.path(output_file_name).option(:pgp, passphrase: 'receiver_passphrase').reader(&:read)
     def option(stream, **options)
-      streams.option(stream, **options)
+      builder.option(stream, **options)
       self
     end
 
     # Adds the options for the specified stream as an option,
     # but if streams have already been added it is instead added as a stream.
     def option_or_stream(stream, **options)
-      streams.option_or_stream(stream, **options)
+      builder.option_or_stream(stream, **options)
       self
     end
 
     # Return the options already set for either a stream or option.
     def setting(stream)
-      streams.setting(stream)
+      builder.setting(stream)
       self
     end
 
     # Returns [Hash<Symbol:Hash>] the pipeline of streams
     # with their options that will be applied when the reader or writer is invoked.
     def pipeline
-      streams.pipeline
+      builder.pipeline
+    end
+
+    # Iterate over a file / stream returning one line at a time.
+    #
+    # Example: Read a line at a time
+    #   IOStreams.path("file.txt").each(:line) do |line|
+    #     puts line
+    #   end
+    #
+    # Example: Read a line at a time with custom options
+    #   IOStreams.path("file.csv").each(:line, embedded_within: '"') do |line|
+    #     puts line
+    #   end
+    #
+    # Example: Read a row at a time
+    #   IOStreams.path("file.csv").each(:array) do |array|
+    #     p array
+    #   end
+    #
+    # Example: Read a record at a time
+    #   IOStreams.path("file.csv").each(:hash) do |hash|
+    #     p hash
+    #   end
+    #
+    # Notes:
+    # - Embedded lines (within double quotes) will be skipped if
+    #   1. The file name contains .csv
+    #   2. Or the embedded_within argument is set
+    def each(mode = :line, **args, &block)
+      raise(ArgumentError, "Invalid mode: #{mode.inspect}") if mode == :stream
+
+      #    return enum_for __method__ unless block_given?
+      reader(mode, **args) { |stream| stream.each(&block) }
     end
 
     # Returns a Reader for reading a file / stream
-    def reader(&block)
-      streams.reader(io_stream, &block)
+    def reader(mode = :stream, **args, &block)
+      case mode
+      when :stream
+        stream_reader(&block)
+      when :line
+        line_reader(**args, &block)
+      when :array
+        row_reader(**args, &block)
+      when :hash
+        record_reader(**args, &block)
+      else
+        raise(ArgumentError, "Invalid mode: #{mode.inspect}")
+      end
     end
 
     # Read an entire file into memory.
@@ -67,12 +111,37 @@ module IOStreams
     # Notes:
     # - Use with caution since large files can cause a denial of service since
     #   this method will load the entire file into memory.
-    # - Recommend using instead `#reader`, `#each_line`, or `#each_record` to read a
-    #   block into memory at a time.
+    # - Recommend using instead `#reader` to read a block into memory at a time.
     def read(*args)
       reader { |stream| stream.read(*args) }
     end
 
+    # Returns a Writer for writing to a file / stream
+    def writer(mode = :stream, **args, &block)
+      case mode
+      when :stream
+        stream_writer(&block)
+      when :line
+        line_writer(**args, &block)
+      when :array
+        row_writer(**args, &block)
+      when :hash
+        record_writer(**args, &block)
+      else
+        raise(ArgumentError, "Invalid mode: #{mode.inspect}")
+      end
+    end
+
+    # Write entire string to file.
+    #
+    # Notes:
+    # - Use with caution since preparing large amounts of data in memory can cause a denial of service
+    #   since all the data for the file needs to be resident in memory before writing.
+    # - Recommend using instead `#writer` to write a block of memory at a time.
+    def write(data)
+      writer { |stream| stream.write(data) }
+    end
+
     # Copy from another stream, path, file_name or IO instance.
     #
     # Parameters:
@@ -113,109 +182,19 @@ module IOStreams
       target.copy_from(self, convert: convert)
     end
 
-    # Iterate over a file / stream returning one line at a time.
-    # 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_line(file_name, embedded_within: '"') do |line|
-    #     puts line
-    #   end
-    #
-    def each_line(**args, &block)
-      #    return enum_for __method__ unless block_given?
-      line_reader(**args) { |line_stream| line_stream.each(&block) }
-    end
-
-    # Iterate over a file / stream returning one line at a time.
-    # 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_row(file_name, embedded_within: '"') do |line|
-    #     puts line
-    #   end
-    #
-    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.
-    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.
-    # It will apply the embedded_within argument if the file or input_stream contain .csv in its name.
-    def line_reader(embedded_within: nil, **args)
-      embedded_within = '"' if embedded_within.nil? && streams.file_name&.include?('.csv')
-
-      reader { |io| yield IOStreams::Line::Reader.new(io, embedded_within: embedded_within, **args) }
-    end
-
-    # Iterate over a file / stream returning each line as an array, one at a time.
-    def row_reader(delimiter: nil, embedded_within: nil, **args)
-      line_reader(delimiter: delimiter, embedded_within: embedded_within) do |io|
-        yield IOStreams::Row::Reader.new(io, **args)
-      end
-    end
-
-    # Iterate over a file / stream returning each line as a hash, one at a time.
-    def record_reader(delimiter: nil, embedded_within: nil, **args)
-      line_reader(delimiter: delimiter, embedded_within: embedded_within) do |io|
-        yield IOStreams::Record::Reader.new(io, **args)
-      end
-    end
-
-    # Returns a Writer for writing to a file / stream
-    def writer(&block)
-      streams.writer(io_stream, &block)
-    end
-
-    # Write entire string to file.
-    #
-    # Notes:
-    # - Use with caution since preparing large amounts of data in memory can cause a denial of service
-    #   since all the data for the file needs to be resident in memory before writing.
-    # - Recommend using instead `#writer`, `#line_writer`, or `#row_writer` to write a
-    #   block of memory at a time.
-    def write(data)
-      writer { |stream| stream.write(data) }
-    end
-
-    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, &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, &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)
       if file_name == :none
-        streams.file_name
+        builder.file_name
       else
-        streams.file_name = file_name
+        builder.file_name = file_name
         self
       end
     end
 
     # Set/get the original file_name
     def file_name=(file_name)
-      streams.file_name = file_name
+      builder.file_name = file_name
     end
 
     # Returns [String] the last component of this path.
@@ -230,7 +209,7 @@ module IOStreams
     #   IOStreams.path("/home/gumby/work/ruby.rb").basename(".rb")  #=> "ruby"
     #   IOStreams.path("/home/gumby/work/ruby.rb").basename(".*")   #=> "ruby"
     def basename(suffix = nil)
-      file_name = streams.file_name
+      file_name = builder.file_name
       return unless file_name
 
       suffix.nil? ? ::File.basename(file_name) : ::File.basename(file_name, suffix)
@@ -248,7 +227,7 @@ module IOStreams
     #   IOStreams.path("test").dirname            #=> "."
     #   IOStreams.path(".profile").dirname        #=> "."
     def dirname
-      file_name = streams.file_name
+      file_name = builder.file_name
       ::File.dirname(file_name) if file_name
     end
 
@@ -268,7 +247,7 @@ module IOStreams
     #   IOStreams.path(".profile").extname        #=> ""
     #   IOStreams.path(".profile.sh").extname     #=> ".sh"
     def extname
-      file_name = streams.file_name
+      file_name = builder.file_name
       ::File.extname(file_name) if file_name
     end
 
@@ -293,8 +272,54 @@ module IOStreams
 
     private
 
-    def streams
-      @streams ||= IOStreams::Streams.new
+    def builder
+      @builder ||= IOStreams::Builder.new
+    end
+
+    def stream_reader(&block)
+      builder.reader(io_stream, &block)
+    end
+
+    def line_reader(embedded_within: nil, **args)
+      embedded_within = '"' if embedded_within.nil? && builder.file_name&.include?('.csv')
+
+      stream_reader { |io| yield IOStreams::Line::Reader.new(io, embedded_within: embedded_within, **args) }
+    end
+
+    # Iterate over a file / stream returning each line as an array, one at a time.
+    def row_reader(delimiter: nil, embedded_within: nil, **args)
+      line_reader(delimiter: delimiter, embedded_within: embedded_within) do |io|
+        yield IOStreams::Row::Reader.new(io, **args)
+      end
+    end
+
+    # Iterate over a file / stream returning each line as a hash, one at a time.
+    def record_reader(delimiter: nil, embedded_within: nil, **args)
+      line_reader(delimiter: delimiter, embedded_within: embedded_within) do |io|
+        yield IOStreams::Record::Reader.new(io, **args)
+      end
+    end
+
+    def stream_writer(&block)
+      builder.writer(io_stream, &block)
+    end
+
+    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, &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, &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
   end
 end