iostreams 2.0.0 → 2.1.0

data/lib/io_streams/tabular/parser/psv.rb

@@ -3,6 +3,7 @@ module IOStreams
     module Parser
       # For parsing a single line of Pipe-separated values
       class Psv < Base
+        LINE_BREAK = /\r\n|\r|\n/
         # Returns [Array] the parsed PSV line
         def parse(row)
           return row if row.is_a?(::Array)
@@ -12,11 +13,14 @@ module IOStreams
           row.split("|")
         end
 
-        # Return the supplied array as a single line JSON string.
+        # Return the supplied array as a single line PSV string.
+        #
+        # Since PSV has no escaping, any `|` within a value is replaced with `:`,
+        # and any line break with a space, so that a value cannot add columns or records.
         def render(row, header)
           array          = header.to_array(row)
           cleansed_array = array.collect do |i|
-            i.is_a?(String) ? i.tr("|", ":") : i
+            i.is_a?(String) ? i.tr("|", ":").gsub(LINE_BREAK, " ") : i
           end
           cleansed_array.join("|")
         end

data/lib/io_streams/utils.rb

@@ -12,6 +12,17 @@ module IOStreams
       raise(LoadError, "Please install the gem '#{gem_name}' to support #{stream_type}. #{e.message}")
     end
 
+    # Log a warning for options that a stream ignores, until they raise `ArgumentError` in v3.0.
+    def self.warn_unknown_options(unknown, stream, direction, valid)
+      return if unknown.empty?
+
+      names = unknown.keys.map(&:inspect).join(", ")
+      IOStreams.logger&.warn(
+        "Ignoring unknown #{unknown.size == 1 ? 'option' : 'options'} #{names} when #{direction} a #{stream.inspect} " \
+        "stream. Valid options: #{valid.map(&:inspect).join(', ')}. In v3.0 this will raise ArgumentError."
+      )
+    end
+
     # Helper method: Returns [true|false] if a value is blank?
     def self.blank?(value)
       return true if value.nil?
@@ -33,6 +44,26 @@ module IOStreams
       result
     end
 
+    # Yields the name of a new, empty temporary file that only the current user can read or write.
+    #
+    # The file is created exclusively, so that an existing file, or a link planted in a shared
+    # temp directory, is never written to. Only a name collision when creating the file is retried,
+    # and the file is only deleted once it was created here, so that another process's file is never removed.
+    #
+    # Returns the value from the block.
+    def self.private_temp_file(basename, extension = "")
+      file_name = ::Dir::Tmpname.create([basename, extension], IOStreams.temp_dir,
+                                        max_try: MAX_TEMP_FILE_NAME_ATTEMPTS) do |tmpname|
+        ::File.open(tmpname, ::File::WRONLY | ::File::CREAT | ::File::EXCL, 0o600, &:close)
+      end
+
+      begin
+        yield(file_name)
+      ensure
+        ::FileUtils.rm_f(file_name)
+      end
+    end
+
     class URI
       attr_reader :scheme, :hostname, :path, :user, :password, :port, :query
 

data/lib/io_streams/version.rb

@@ -1,3 +1,3 @@
 module IOStreams
-  VERSION = "2.0.0".freeze
+  VERSION = "2.1.0".freeze
 end

data/lib/io_streams/writer.rb

@@ -1,9 +1,18 @@
 module IOStreams
   class Writer
+    # Returns [Array<Symbol>] the names of the options this writer accepts,
+    # or [nil] when the writer does not declare them.
+    #
+    # When declared, `IOStreams::Builder` rejects any other option before the writer is opened,
+    # naming the direction an option belongs to when it is only valid for the other direction.
+    def self.option_names
+      nil
+    end
+
     # When a Writer does not support streams, we copy the stream to a local temp file
     # and then pass that filename in for this reader.
     def self.stream(output_stream, **args, &block)
-      Utils.temp_file_name("iostreams_writer") do |file_name|
+      Utils.private_temp_file("iostreams_writer") do |file_name|
         count = file(file_name, **args, &block)
         ::File.open(file_name, "rb") { |source| ::IO.copy_stream(source, output_stream) }
         count

data/lib/io_streams/xlsx/reader.rb

@@ -3,10 +3,14 @@ require "csv"
 module IOStreams
   module Xlsx
     class Reader < IOStreams::Reader
+      def self.option_names
+        []
+      end
+
       # Convert a xlsx, or xlsm file into CSV format.
       def self.file(file_name, &block)
         # Stream into a temp file as csv
-        Utils.temp_file_name("iostreams_csv") do |temp_file_name|
+        Utils.private_temp_file("iostreams_csv") do |temp_file_name|
           ::File.open(temp_file_name, "wb") { |io| new(file_name).each { |lines| io << lines.to_csv } }
           ::File.open(temp_file_name, "rb", &block)
         end

data/lib/io_streams/zip/reader.rb

@@ -1,6 +1,10 @@
 module IOStreams
   module Zip
     class Reader < IOStreams::Reader
+      def self.option_names
+        %i[entry_file_name]
+      end
+
       # Read from a zip file or stream, decompressing the contents as it is read
       # The input stream from the first file found in the zip file is passed
       # to the supplied block.

data/lib/io_streams/zip/writer.rb

@@ -1,6 +1,10 @@
 module IOStreams
   module Zip
     class Writer < IOStreams::Writer
+      def self.option_names
+        %i[zip_file_name entry_file_name]
+      end
+
       # When writing to a file, default the entry name within the zip to the file name
       # without the `.zip` extension, unless an entry name was explicitly supplied.
       def self.file(file_name, zip_file_name: nil, entry_file_name: zip_file_name, &)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: iostreams
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Reid Morrison
@@ -23,6 +23,10 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+description: IOStreams makes file formats, compression (gzip, zip, bzip2), encryption
+  (PGP, symmetric), and storage location (local file, S3, SFTP, HTTP) transparent
+  to your application code. Files of any size are read and written one block at a
+  time, without loading the entire file into memory.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -30,6 +34,17 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- docs/CLAUDE.md
+- docs/config.md
+- docs/copy_files.md
+- docs/extensions.md
+- docs/formats.md
+- docs/index.md
+- docs/path.md
+- docs/pgp.md
+- docs/streams.md
+- docs/tutorial.md
+- docs/upgrading.md
 - lib/io_streams/builder.rb
 - lib/io_streams/bzip2/reader.rb
 - lib/io_streams/bzip2/writer.rb
@@ -47,6 +62,7 @@ files:
 - lib/io_streams/paths/matcher.rb
 - lib/io_streams/paths/s3.rb
 - lib/io_streams/paths/sftp.rb
+- lib/io_streams/paths/sftp/net_ssh.rb
 - lib/io_streams/pgp.rb
 - lib/io_streams/pgp/reader.rb
 - lib/io_streams/pgp/writer.rb
@@ -74,14 +90,15 @@ files:
 - lib/io_streams/zip/reader.rb
 - lib/io_streams/zip/writer.rb
 - lib/iostreams.rb
-homepage: https://iostreams.rocketjob.io
+homepage: https://iostreams.reidmorrison.com
 licenses:
 - Apache-2.0
 metadata:
   bug_tracker_uri: https://github.com/reidmorrison/iostreams/issues
-  changelog_uri: https://github.com/reidmorrison/iostreams/blob/v2.0.0/CHANGELOG.md
-  documentation_uri: https://iostreams.rocketjob.io
-  source_code_uri: https://github.com/reidmorrison/iostreams/tree/v2.0.0
+  changelog_uri: https://github.com/reidmorrison/iostreams/blob/main/CHANGELOG.md
+  documentation_uri: https://iostreams.reidmorrison.com
+  homepage_uri: https://iostreams.reidmorrison.com
+  source_code_uri: https://github.com/reidmorrison/iostreams/tree/v2.1.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -99,6 +116,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: 'Streaming I/O for Ruby: compression, encryption, format, and storage transparent
-  to your code.'
+summary: 'Streaming I/O for Ruby: compression, encryption, file format, and storage
+  location transparent to your code.'
 test_files: []