csv 3.3.0 → 3.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4be2aab05afe081e964c806337cab1e8763532ecf66ef29bb8f6854cd65b29bf
-  data.tar.gz: 716f28f2377749b95d8f5f9f19a7cba50499e4ff46c4978efdc002ba25162475
+  metadata.gz: 810bc9a744fd02ede6fd069e5fa11c42307533f070f096b0614466a62c37bf1d
+  data.tar.gz: a69e61cc7f0e81f00a8e1d22a33bd90e43e7859444c866393dda01bb61426630
 SHA512:
-  metadata.gz: bc67687257ea7790091d9755199624dced05c3ea07a9afc47b86cc49dac1dfce77b884e1c2397de71f1f2de22720778135373652d7af05acb990814e6fa2d940
-  data.tar.gz: fce6230a6fdcff2ae8044a0f374ea71403cdf1f59d2024bb64a87ade52a897a907dfcb271b39d1ad81299cbd9eebf2ca43008dec99d86648550f73584d8c468c
+  metadata.gz: 69d5f90a13cb9f4411a2d4b127211cabd060889f3f6f55de72061cda4994b62160ca264a6e7601639f056d1c0a148120a24c4b1385e10e66e2425adb01d7be73
+  data.tar.gz: b0d2bf9c262db845b5a8f7af157ef127d5856585af3bb0ea1dd420b2aee114ad6cdf870f246f6f6a80ebaac30634cab3745fe37669799e559d0dfb89e2d7b3ed

data/NEWS.md

@@ -1,5 +1,50 @@
 # News
 
+## 3.3.1 - 2024-12-15
+
+### Improvements
+
+  * `CSV.open`: Changed to detect BOM by default. Note that this isn't
+    enabled on Windows because Ruby may have a bug. See also:
+    https://bugs.ruby-lang.org/issues/20526
+    * GH-301
+    * Reported by Junichi Ito
+
+  * Improved performance.
+    * GH-311
+    * GH-312
+    * Patch by Vladimir Kochnev
+
+  * `CSV.open`: Added support for `StringIO` as an input.
+    * GH-300
+    * GH-302
+    * Patch by Marcelo
+
+  * Added a built-in time converter. You can use it by `converters:
+    :time`.
+    * GH-313
+    * Patch by Bart de Water
+
+  * Added `CSV::TSV` for tab-separated values.
+    * GH-272
+    * GH-319
+    * Reported by kojix2
+    * Patch by Jas
+
+### Thanks
+
+  * Junichi Ito
+
+  * Vladimir Kochnev
+
+  * Marcelo
+
+  * Bart de Water
+
+  * kojix2
+
+  * Jas
+
 ## 3.3.0 - 2024-03-22
 
 ### Fixes

data/doc/csv/recipes/filtering.rdoc

@@ -11,16 +11,20 @@ All code snippets on this page assume that the following has been executed:
 
 - {Source and Output Formats}[#label-Source+and+Output+Formats]
   - {Filtering String to String}[#label-Filtering+String+to+String]
-    - {Recipe: Filter String to String with Headers}[#label-Recipe-3A+Filter+String+to+String+with+Headers]
+    - {Recipe: Filter String to String parsing Headers}[#label-Recipe-3A+Filter+String+to+String+parsing+Headers]
+    - {Recipe: Filter String to String parsing and writing Headers}[#label-Recipe-3A+Filter+String+to+String+parsing+and+writing+Headers]
     - {Recipe: Filter String to String Without Headers}[#label-Recipe-3A+Filter+String+to+String+Without+Headers]
   - {Filtering String to IO Stream}[#label-Filtering+String+to+IO+Stream]
-    - {Recipe: Filter String to IO Stream with Headers}[#label-Recipe-3A+Filter+String+to+IO+Stream+with+Headers]
+    - {Recipe: Filter String to IO Stream parsing Headers}[#label-Recipe-3A+Filter+String+to+IO+Stream+parsing+Headers]
+    - {Recipe: Filter String to IO Stream parsing and writing Headers}[#label-Recipe-3A+Filter+String+to+IO+Stream+parsing+and+writing+Headers]
     - {Recipe: Filter String to IO Stream Without Headers}[#label-Recipe-3A+Filter+String+to+IO+Stream+Without+Headers]
   - {Filtering IO Stream to String}[#label-Filtering+IO+Stream+to+String]
-    - {Recipe: Filter IO Stream to String with Headers}[#label-Recipe-3A+Filter+IO+Stream+to+String+with+Headers]
+    - {Recipe: Filter IO Stream to String parsing Headers}[#label-Recipe-3A+Filter+IO+Stream+to+String+parsing+Headers]
+    - {Recipe: Filter IO Stream to String parsing and writing Headers}[#label-Recipe-3A+Filter+IO+Stream+to+String+parsing+and+writing+Headers]
     - {Recipe: Filter IO Stream to String Without Headers}[#label-Recipe-3A+Filter+IO+Stream+to+String+Without+Headers]
   - {Filtering IO Stream to IO Stream}[#label-Filtering+IO+Stream+to+IO+Stream]
-    - {Recipe: Filter IO Stream to IO Stream with Headers}[#label-Recipe-3A+Filter+IO+Stream+to+IO+Stream+with+Headers]
+    - {Recipe: Filter IO Stream to IO Stream parsing Headers}[#label-Recipe-3A+Filter+IO+Stream+to+IO+Stream+parsing+Headers]
+    - {Recipe: Filter IO Stream to IO Stream parsing and writing Headers}[#label-Recipe-3A+Filter+IO+Stream+to+IO+Stream+parsing+and+writing+Headers]
     - {Recipe: Filter IO Stream to IO Stream Without Headers}[#label-Recipe-3A+Filter+IO+Stream+to+IO+Stream+Without+Headers]
 
 === Source and Output Formats
@@ -33,14 +37,27 @@ The input and output \CSV data may be any mixture of \Strings and \IO streams.
 
 You can filter one \String to another, with or without headers.
 
-===== Recipe: Filter \String to \String with Headers
+===== Recipe: Filter \String to \String parsing Headers
 
 Use class method CSV.filter with option +headers+ to filter a \String to another \String:
   in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
   out_string = ''
   CSV.filter(in_string, out_string, headers: true) do |row|
-    row[0] = row[0].upcase
-    row[1] *= 4
+    row['Name'] = row['Name'].upcase
+    row['Value'] *= 4
+  end
+  out_string # => "FOO,0000\nBAR,1111\nBAZ,2222\n"
+
+===== Recipe: Filter \String to \String parsing and writing Headers
+
+Use class method CSV.filter with option +headers+ and +out_write_headers+ to filter a \String to another \String including header row:
+  in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  out_string = ''
+  CSV.filter(in_string, out_string, headers: true, out_write_headers: true) do |row|
+    unless row.is_a?(Array)
+      row['Name'] = row['Name'].upcase
+      row['Value'] *= 4
+    end
   end
   out_string # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"
 
@@ -59,15 +76,30 @@ Use class method CSV.filter without option +headers+ to filter a \String to anot
 
 You can filter a \String to an \IO stream, with or without headers.
 
-===== Recipe: Filter \String to \IO Stream with Headers
+===== Recipe: Filter \String to \IO Stream parsing Headers
 
 Use class method CSV.filter with option +headers+ to filter a \String to an \IO stream:
   in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
   path = 't.csv'
   File.open(path, 'w') do |out_io|
     CSV.filter(in_string, out_io, headers: true) do |row|
-      row[0] = row[0].upcase
-      row[1] *= 4
+      row['Name'] = row['Name'].upcase
+      row['Value'] *= 4
+    end
+  end
+  p File.read(path) # => "FOO,0000\nBAR,1111\nBAZ,2222\n"
+
+===== Recipe: Filter \String to \IO Stream parsing and writing Headers
+
+Use class method CSV.filter with option +headers+ and +out_write_headers+ to filter a \String to an \IO stream including header row:
+  in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  path = 't.csv'
+  File.open(path, 'w') do |out_io|
+    CSV.filter(in_string, out_io, headers: true, out_write_headers: true ) do |row|
+      unless row.is_a?(Array)
+        row['Name'] = row['Name'].upcase
+        row['Value'] *= 4
+      end
     end
   end
   p File.read(path) # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"
@@ -89,17 +121,34 @@ Use class method CSV.filter without option +headers+ to filter a \String to an \
 
 You can filter an \IO stream to a \String, with or without headers.
 
-===== Recipe: Filter \IO Stream to \String with Headers
+===== Recipe: Filter \IO Stream to \String parsing Headers
 
 Use class method CSV.filter with option +headers+ to filter an \IO stream to a \String:
   in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
   path = 't.csv'
   File.write(path, in_string)
   out_string = ''
-  File.open(path, headers: true) do |in_io|
+  File.open(path) do |in_io|
     CSV.filter(in_io, out_string, headers: true) do |row|
-      row[0] = row[0].upcase
-      row[1] *= 4
+      row['Name'] = row['Name'].upcase
+      row['Value'] *= 4
+    end
+  end
+  out_string # => "FOO,0000\nBAR,1111\nBAZ,2222\n"
+
+===== Recipe: Filter \IO Stream to \String parsing and writing Headers
+
+Use class method CSV.filter with option +headers+ and +out_write_headers+ to filter an \IO stream to a \String including header row:
+  in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  path = 't.csv'
+  File.write(path, in_string)
+  out_string = ''
+  File.open(path) do |in_io|
+    CSV.filter(in_io, out_string, headers: true, out_write_headers: true) do |row|
+      unless row.is_a?(Array)
+        row['Name'] = row['Name'].upcase
+        row['Value'] *= 4
+      end
     end
   end
   out_string # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"
@@ -123,7 +172,7 @@ Use class method CSV.filter without option +headers+ to filter an \IO stream to
 
 You can filter an \IO stream to another \IO stream, with or without headers.
 
-===== Recipe: Filter \IO Stream to \IO Stream with Headers
+===== Recipe: Filter \IO Stream to \IO Stream parsing Headers
 
 Use class method CSV.filter with option +headers+ to filter an \IO stream to another \IO stream:
   in_path = 't.csv'
@@ -133,8 +182,27 @@ Use class method CSV.filter with option +headers+ to filter an \IO stream to ano
   File.open(in_path) do |in_io|
     File.open(out_path, 'w') do |out_io|
       CSV.filter(in_io, out_io, headers: true) do |row|
-        row[0] = row[0].upcase
-        row[1] *= 4
+        row['Name'] = row['Name'].upcase
+        row['Value'] *= 4
+      end
+    end
+  end
+  p File.read(out_path) # => "FOO,0000\nBAR,1111\nBAZ,2222\n"
+
+===== Recipe: Filter \IO Stream to \IO Stream parsing and writing Headers
+
+Use class method CSV.filter with option +headers+ and +out_write_headers+ to filter an \IO stream to another \IO stream including header row:
+  in_path = 't.csv'
+  in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  File.write(in_path, in_string)
+  out_path = 'u.csv'
+  File.open(in_path) do |in_io|
+    File.open(out_path, 'w') do |out_io|
+      CSV.filter(in_io, out_io, headers: true, out_write_headers: true) do |row|
+        unless row.is_a?(Array)
+          row['Name'] = row['Name'].upcase
+          row['Value'] *= 4
+        end
       end
     end
   end

data/doc/csv/recipes/generating.rdoc

@@ -165,7 +165,7 @@ This example defines and uses two custom write converters to strip and upcase ge
 === RFC 4180 Compliance
 
 By default, \CSV generates data that is compliant with
-{RFC 4180}[https://tools.ietf.org/html/rfc4180]
+{RFC 4180}[https://www.rfc-editor.org/rfc/rfc4180]
 with respect to:
 - Column separator.
 - Quote character.

data/doc/csv/recipes/parsing.rdoc

@@ -45,6 +45,7 @@ All code snippets on this page assume that the following has been executed:
     - {Recipe: Convert Fields to Numerics}[#label-Recipe-3A+Convert+Fields+to+Numerics]
     - {Recipe: Convert Fields to Dates}[#label-Recipe-3A+Convert+Fields+to+Dates]
     - {Recipe: Convert Fields to DateTimes}[#label-Recipe-3A+Convert+Fields+to+DateTimes]
+    - {Recipe: Convert Fields to Times}[#label-Recipe-3A+Convert+Fields+to+Times]
     - {Recipe: Convert Assorted Fields to Objects}[#label-Recipe-3A+Convert+Assorted+Fields+to+Objects]
     - {Recipe: Convert Fields to Other Objects}[#label-Recipe-3A+Convert+Fields+to+Other+Objects]
   - {Recipe: Filter Field Strings}[#label-Recipe-3A+Filter+Field+Strings]
@@ -110,7 +111,7 @@ You can parse \CSV data from a \File, with or without headers.
 
 ===== Recipe: Parse from \File with Headers
 
-Use instance method CSV#read with option +headers+ to read a file all at once:
+Use class method CSV.read with option +headers+ to read a file all at once:
   string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
   path = 't.csv'
   File.write(path, string)
@@ -191,7 +192,7 @@ Output:
 === RFC 4180 Compliance
 
 By default, \CSV parses data that is compliant with
-{RFC 4180}[https://tools.ietf.org/html/rfc4180]
+{RFC 4180}[https://www.rfc-editor.org/rfc/rfc4180]
 with respect to:
 - Row separator.
 - Column separator.
@@ -339,6 +340,7 @@ There are built-in field converters for converting to objects of certain classes
 - \Integer
 - \Date
 - \DateTime
+- \Time
 
 Other built-in field converters include:
 - +:numeric+: converts to \Integer and \Float.
@@ -381,6 +383,13 @@ Convert fields to \DateTime objects using built-in converter +:date_time+:
   parsed = CSV.parse(source, headers: true, converters: :date_time)
   parsed.map {|row| row['DateTime'].class} # => [DateTime, DateTime, DateTime]
 
+===== Recipe: Convert Fields to Times
+
+Convert fields to \Time objects using built-in converter +:time+:
+  source = "Name,Time\nfoo,2001-02-03\nbar,2001-02-04\nbaz,2020-05-07T14:59:00-05:00\n"
+  parsed = CSV.parse(source, headers: true, converters: :time)
+  parsed.map {|row| row['Time'].class} # => [Time, Time, Time]
+
 ===== Recipe: Convert Assorted Fields to Objects
 
 Convert assorted fields to objects using built-in converter +:all+:
@@ -542,4 +551,4 @@ Output:
   #<struct CSV::FieldInfo index=0, line=2, header=nil>
   #<struct CSV::FieldInfo index=1, line=2, header=nil>
   #<struct CSV::FieldInfo index=0, line=3, header=nil>
-  #<struct CSV::FieldInfo index=1, line=3, header=nil>
+  #<struct CSV::FieldInfo index=1, line=3, header=nil>

data/lib/csv/core_ext/array.rb

@@ -1,4 +1,4 @@
-class Array # :nodoc:
+class Array
   # Equivalent to CSV::generate_line(self, options)
   #
   #   ["CSV", "data"].to_csv

data/lib/csv/core_ext/string.rb

@@ -1,4 +1,4 @@
-class String # :nodoc:
+class String
   # Equivalent to CSV::parse_line(self, options)
   #
   #   "CSV,data".parse_csv

data/lib/csv/fields_converter.rb

@@ -4,6 +4,13 @@ class CSV
   # Note: Don't use this class directly. This is an internal class.
   class FieldsConverter
     include Enumerable
+
+    NO_QUOTED_FIELDS = [] # :nodoc:
+    def NO_QUOTED_FIELDS.[](_index)
+      false
+    end
+    NO_QUOTED_FIELDS.freeze
+
     #
     # A CSV::FieldsConverter is a data structure for storing the
     # fields converter properties to be passed as a parameter
@@ -44,7 +51,7 @@ class CSV
       @converters.empty?
     end
 
-    def convert(fields, headers, lineno, quoted_fields)
+    def convert(fields, headers, lineno, quoted_fields=NO_QUOTED_FIELDS)
       return fields unless need_convert?
 
       fields.collect.with_index do |field, index|

data/lib/csv/parser.rb

@@ -409,13 +409,7 @@ class CSV
 
       begin
         @scanner ||= build_scanner
-        if quote_character.nil?
-          parse_no_quote(&block)
-        elsif @need_robust_parsing
-          parse_quotable_robust(&block)
-        else
-          parse_quotable_loose(&block)
-        end
+        __send__(@parse_method, &block)
       rescue InvalidEncoding
         if @scanner
           ignore_broken_line
@@ -459,7 +453,6 @@ class CSV
     end
 
     def prepare_variable
-      @need_robust_parsing = false
       @encoding = @options[:encoding]
       liberal_parsing = @options[:liberal_parsing]
       if liberal_parsing
@@ -472,7 +465,6 @@ class CSV
           @double_quote_outside_quote = false
           @backslash_quote = false
         end
-        @need_robust_parsing = true
       else
         @liberal_parsing = false
         @backslash_quote = false
@@ -554,7 +546,6 @@ class CSV
           @rstrip_value = Regexp.new(@escaped_strip +
                                      "+\\z".encode(@encoding))
         end
-        @need_robust_parsing = true
       elsif @strip
         strip_values = " \t\f\v"
         @escaped_strip = strip_values.encode(@encoding)
@@ -562,7 +553,6 @@ class CSV
           @strip_value = Regexp.new("[#{strip_values}]+".encode(@encoding))
           @rstrip_value = Regexp.new("[#{strip_values}]+\\z".encode(@encoding))
         end
-        @need_robust_parsing = true
       end
     end
 
@@ -767,7 +757,7 @@ class CSV
       case headers
       when Array
         @raw_headers = headers
-        quoted_fields = [false] * @raw_headers.size
+        quoted_fields = FieldsConverter::NO_QUOTED_FIELDS
         @use_headers = true
       when String
         @raw_headers, quoted_fields = parse_headers(headers)
@@ -808,6 +798,13 @@ class CSV
 
     def prepare_parser
       @may_quoted = may_quoted?
+      if @quote_character.nil?
+        @parse_method = :parse_no_quote
+      elsif @liberal_parsing or @strip
+        @parse_method = :parse_quotable_robust
+      else
+        @parse_method = :parse_quotable_loose
+      end
     end
 
     def may_quoted?
@@ -944,11 +941,9 @@ class CSV
         if line.empty?
           next if @skip_blanks
           row = []
-          quoted_fields = []
         else
           line = strip_value(line)
           row = line.split(@split_column_separator, -1)
-          quoted_fields = [false] * row.size
           if @max_field_size
             row.each do |column|
               validate_field_size(column)
@@ -962,7 +957,7 @@ class CSV
           end
         end
         @last_line = original_line
-        emit_row(row, quoted_fields, &block)
+        emit_row(row, &block)
       end
     end
 
@@ -984,10 +979,10 @@ class CSV
             next
           end
           row = []
-          quoted_fields = []
+          quoted_fields = FieldsConverter::NO_QUOTED_FIELDS
         elsif line.include?(@cr) or line.include?(@lf)
           @scanner.keep_back
-          @need_robust_parsing = true
+          @parse_method = :parse_quotable_robust
           return parse_quotable_robust(&block)
         else
           row = line.split(@split_column_separator, -1)
@@ -1011,7 +1006,7 @@ class CSV
                 row[i] = column[1..-2]
               else
                 @scanner.keep_back
-                @need_robust_parsing = true
+                @parse_method = :parse_quotable_robust
                 return parse_quotable_robust(&block)
               end
               validate_field_size(row[i])
@@ -1046,13 +1041,13 @@ class CSV
           quoted_fields << @quoted_column_value
         elsif parse_row_end
           if row.empty? and value.nil?
-            emit_row([], [], &block) unless @skip_blanks
+            emit_row(row, &block) unless @skip_blanks
           else
             row << value
             quoted_fields << @quoted_column_value
             emit_row(row, quoted_fields, &block)
             row = []
-            quoted_fields = []
+            quoted_fields.clear
           end
           skip_needless_lines
           start_row
@@ -1257,7 +1252,7 @@ class CSV
       @scanner.keep_start
     end
 
-    def emit_row(row, quoted_fields, &block)
+    def emit_row(row, quoted_fields=FieldsConverter::NO_QUOTED_FIELDS, &block)
       @lineno += 1
 
       raw_row = row

data/lib/csv/version.rb

@@ -2,5 +2,5 @@
 
 class CSV
   # The version of the installed library.
-  VERSION = "3.3.0"
+  VERSION = "3.3.1"
 end

data/lib/csv/writer.rb

@@ -40,8 +40,7 @@ class CSV
       @lineno += 1
 
       if @fields_converter
-        quoted_fields = [false] * row.size
-        row = @fields_converter.convert(row, nil, lineno, quoted_fields)
+        row = @fields_converter.convert(row, nil, lineno)
       end
 
       i = -1

data/lib/csv.rb

@@ -91,6 +91,7 @@
 
 require "forwardable"
 require "date"
+require "time"
 require "stringio"
 
 require_relative "csv/fields_converter"
@@ -521,6 +522,7 @@ require_relative "csv/writer"
 # - <tt>:float</tt>: converts each \String-embedded float into a true \Float.
 # - <tt>:date</tt>: converts each \String-embedded date into a true \Date.
 # - <tt>:date_time</tt>: converts each \String-embedded date-time into a true \DateTime
+# - <tt>:time</tt>: converts each \String-embedded time into a true \Time
 # .
 # This example creates a converter proc, then stores it:
 #   strip_converter = proc {|field| field.strip }
@@ -631,6 +633,7 @@ require_relative "csv/writer"
 #   [:numeric, [:integer, :float]]
 #   [:date, Proc]
 #   [:date_time, Proc]
+#   [:time, Proc]
 #   [:all, [:date_time, :numeric]]
 #
 # Each of these converters transcodes values to UTF-8 before attempting conversion.
@@ -675,6 +678,15 @@ require_relative "csv/writer"
 #   csv = CSV.parse_line(data, converters: :date_time)
 #   csv # => [#<DateTime: 2020-05-07T14:59:00-05:00 ((2458977j,71940s,0n),-18000s,2299161j)>, "x"]
 #
+# Converter +time+ converts each field that Time::parse accepts:
+#   data = '2020-05-07T14:59:00-05:00,x'
+#   # Without the converter
+#   csv = CSV.parse_line(data)
+#   csv # => ["2020-05-07T14:59:00-05:00", "x"]
+#   # With the converter
+#   csv = CSV.parse_line(data, converters: :time)
+#   csv # => [2020-05-07 14:59:00 -0500, "x"]
+#
 # Converter +:numeric+ converts with both +:date_time+ and +:numeric+..
 #
 # As seen above, method #convert adds \converters to a \CSV instance,
@@ -871,10 +883,10 @@ class CSV
   # A Regexp used to find and convert some common Date formats.
   DateMatcher     = / \A(?: (\w+,?\s+)?\w+\s+\d{1,2},?\s+\d{2,4} |
                             \d{4}-\d{2}-\d{2} )\z /x
-  # A Regexp used to find and convert some common DateTime formats.
+  # A Regexp used to find and convert some common (Date)Time formats.
   DateTimeMatcher =
     / \A(?: (\w+,?\s+)?\w+\s+\d{1,2}\s+\d{1,2}:\d{1,2}:\d{1,2},?\s+\d{2,4} |
-            # ISO-8601 and RFC-3339 (space instead of T) recognized by DateTime.parse
+            # ISO-8601 and RFC-3339 (space instead of T) recognized by (Date)Time.parse
             \d{4}-\d{2}-\d{2}
               (?:[T\s]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?(?:[+-]\d{2}(?::\d{2})|Z)?)?)?
         )\z /x
@@ -912,6 +924,14 @@ class CSV
         f
       end
     },
+    time: lambda { |f|
+      begin
+        e = f.encode(ConverterEncoding)
+        e.match?(DateTimeMatcher) ? Time.parse(e) : f
+      rescue  # encoding conversion or parse errors
+        f
+      end
+    },
     all:       [:date_time, :numeric],
   }
 
@@ -1198,7 +1218,44 @@ class CSV
     # * Argument +in_string_or_io+ must be a \String or an \IO stream.
     # * Argument +out_string_or_io+ must be a \String or an \IO stream.
     # * Arguments <tt>**options</tt> must be keyword options.
-    #   See {Options for Parsing}[#class-CSV-label-Options+for+Parsing].
+    #
+    #   - Each option defined as an {option for parsing}[#class-CSV-label-Options+for+Parsing]
+    #     is used for parsing the filter input.
+    #   - Each option defined as an {option for generating}[#class-CSV-label-Options+for+Generating]
+    #     is used for generator the filter input.
+    #
+    # However, there are three options that may be used for both parsing and generating:
+    # +col_sep+, +quote_char+, and +row_sep+.
+    #
+    # Therefore for method +filter+ (and method +filter+ only),
+    # there are special options that allow these parsing and generating options
+    # to be specified separately:
+    #
+    # - Options +input_col_sep+ and +output_col_sep+
+    #   (and their aliases +in_col_sep+ and +out_col_sep+)
+    #   specify the column separators for parsing and generating.
+    # - Options +input_quote_char+ and +output_quote_char+
+    #   (and their aliases +in_quote_char+ and +out_quote_char+)
+    #   specify the quote characters for parsing and generting.
+    # - Options +input_row_sep+ and +output_row_sep+
+    #   (and their aliases +in_row_sep+ and +out_row_sep+)
+    #   specify the row separators for parsing and generating.
+    #
+    # Example options (for column separators):
+    #
+    #   CSV.filter                                    # Default for both parsing and generating.
+    #   CSV.filter(in_col_sep: ';')                   # ';' for parsing, default for generating.
+    #   CSV.filter(out_col_sep: '|')                  # Default for parsing, '|' for generating.
+    #   CSV.filter(in_col_sep: ';', out_col_sep: '|') # ';' for parsing, '|' for generating.
+    #
+    # Note that for a special option (e.g., +input_col_sep+)
+    # and its corresponding "regular" option (e.g., +col_sep+),
+    # the two are mutually overriding.
+    #
+    # Another example (possibly surprising):
+    #
+    #   CSV.filter(in_col_sep: ';', col_sep: '|') # '|' for both parsing(!) and generating.
+    #
     def filter(input=nil, output=nil, **options)
       # parse options for input, output, or both
       in_options, out_options = Hash.new, {row_sep: InputRecordSeparator.value}
@@ -1508,10 +1565,8 @@ class CSV
 
     #
     # :call-seq:
-    #   open(file_path, mode = "rb", **options ) -> new_csv
-    #   open(io, mode = "rb", **options ) -> new_csv
-    #   open(file_path, mode = "rb", **options ) { |csv| ... } -> object
-    #   open(io, mode = "rb", **options ) { |csv| ... } -> object
+    #   open(path_or_io, mode = "rb", **options ) -> new_csv
+    #   open(path_or_io, mode = "rb", **options ) { |csv| ... } -> object
     #
     # possible options elements:
     #   keyword form:
@@ -1520,7 +1575,7 @@ class CSV
     #     :undef => :replace   # replace undefined conversion
     #     :replace => string   # replacement string ("?" or "\uFFFD" if not specified)
     #
-    # * Argument +path+, if given, must be the path to a file.
+    # * Argument +path_or_io+, must be a file path or an \IO stream.
     # :include: ../doc/csv/arguments/io.rdoc
     # * Argument +mode+, if given, must be a \File mode.
     #   See {Access Modes}[https://docs.ruby-lang.org/en/master/File.html#class-File-label-Access+Modes].
@@ -1544,6 +1599,9 @@ class CSV
     #   path = 't.csv'
     #   File.write(path, string)
     #
+    #   string_io = StringIO.new
+    #   string_io << "foo,0\nbar,1\nbaz,2\n"
+    #
     # ---
     #
     # With no block given, returns a new \CSV object.
@@ -1556,6 +1614,9 @@ class CSV
     #   csv = CSV.open(File.open(path))
     #   csv # => #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\n" quote_char:"\"">
     #
+    # Create a \CSV object using a \StringIO:
+    #   csv = CSV.open(string_io)
+    #   csv # => #<CSV io_type:StringIO encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\n" quote_char:"\"">
     # ---
     #
     # With a block given, calls the block with the created \CSV object;
@@ -1573,15 +1634,25 @@ class CSV
     # Output:
     #   #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\n" quote_char:"\"">
     #
+    # Using a \StringIO:
+    #   csv = CSV.open(string_io) {|csv| p csv}
+    #   csv # => #<CSV io_type:StringIO encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\n" quote_char:"\"">
+    # Output:
+    #   #<CSV io_type:StringIO encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\n" quote_char:"\"">
     # ---
     #
     # Raises an exception if the argument is not a \String object or \IO object:
     #   # Raises TypeError (no implicit conversion of Symbol into String)
     #   CSV.open(:foo)
-    def open(filename, mode="r", **options)
+    def open(filename_or_io, mode="r", **options)
       # wrap a File opened with the remaining +args+ with no newline
       # decorator
-      file_opts = options.dup
+      file_opts = {}
+      may_enable_bom_detection_automatically(filename_or_io,
+                                             mode,
+                                             options,
+                                             file_opts)
+      file_opts.merge!(options)
       unless file_opts.key?(:newline)
         file_opts[:universal_newline] ||= false
       end
@@ -1590,14 +1661,19 @@ class CSV
       options.delete(:replace)
       options.delete_if {|k, _| /newline\z/.match?(k)}
 
-      begin
-        f = File.open(filename, mode, **file_opts)
-      rescue ArgumentError => e
-        raise unless /needs binmode/.match?(e.message) and mode == "r"
-        mode = "rb"
-        file_opts = {encoding: Encoding.default_external}.merge(file_opts)
-        retry
+      if filename_or_io.is_a?(StringIO)
+        f = create_stringio(filename_or_io.string, mode, **file_opts)
+      else
+        begin
+          f = File.open(filename_or_io, mode, **file_opts)
+        rescue ArgumentError => e
+          raise unless /needs binmode/.match?(e.message) and mode == "r"
+          mode = "rb"
+          file_opts = {encoding: Encoding.default_external}.merge(file_opts)
+          retry
+        end
       end
+
       begin
         csv = new(f, **options)
       rescue Exception
@@ -1729,6 +1805,23 @@ class CSV
     # Raises an exception if the argument is not a \String object or \IO object:
     #   # Raises NoMethodError (undefined method `close' for :foo:Symbol)
     #   CSV.parse(:foo)
+    #
+    # ---
+    #
+    # Please make sure if your text contains \BOM or not. CSV.parse will not remove
+    # \BOM automatically. You might want to remove \BOM before calling CSV.parse :
+    #   # remove BOM on calling File.open
+    #   File.open(path, encoding: 'bom|utf-8') do |file|
+    #     CSV.parse(file, headers: true) do |row|
+    #       # you can get value by column name because BOM is removed
+    #       p row['Name']
+    #     end
+    #   end
+    #
+    # Output:
+    #   # "foo"
+    #   # "bar"
+    #   # "baz"
     def parse(str, **options, &block)
       csv = new(str, **options)
 
@@ -1862,6 +1955,42 @@ class CSV
       options = default_options.merge(options)
       read(path, **options)
     end
+
+    ON_WINDOWS = /mingw|mswin/.match?(RUBY_PLATFORM)
+    private_constant :ON_WINDOWS
+
+    private
+    def may_enable_bom_detection_automatically(filename_or_io,
+                                               mode,
+                                               options,
+                                               file_opts)
+      if filename_or_io.is_a?(StringIO)
+        # Support to StringIO was dropped for Ruby 2.6 and earlier without BOM support:
+        # https://github.com/ruby/stringio/pull/47
+        return if RUBY_VERSION < "2.7"
+      else
+        # "bom|utf-8" may be buggy on Windows:
+        # https://bugs.ruby-lang.org/issues/20526
+        return if ON_WINDOWS
+      end
+      return unless Encoding.default_external == Encoding::UTF_8
+      return if options.key?(:encoding)
+      return if options.key?(:external_encoding)
+      return if mode.include?(":")
+      file_opts[:encoding] = "bom|utf-8"
+    end
+
+    if RUBY_VERSION < "2.7"
+      def create_stringio(str, mode, opts)
+        opts.delete_if {|k, _| k == :universal_newline or DEFAULT_OPTIONS.key?(k)}
+        raise ArgumentError, "Unsupported options parsing StringIO: #{opts.keys}" unless opts.empty?
+        StringIO.new(str, mode)
+      end
+    else
+      def create_stringio(str, mode, opts)
+        StringIO.new(str, mode, **opts)
+      end
+    end
   end
 
   # :call-seq:
@@ -2000,6 +2129,12 @@ class CSV
     writer if @writer_options[:write_headers]
   end
 
+  class TSV < CSV
+    def initialize(data, **options)
+      super(data, **({col_sep: "\t"}.merge(options)))
+    end
+  end
+
   # :call-seq:
   #   csv.col_sep -> string
   #

metadata

@@ -1,71 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: csv
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 3.3.1
 platform: ruby
 authors:
 - James Edward Gray II
 - Kouhei Sutou
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-03-22 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: benchmark_driver
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: test-unit
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 3.4.8
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 3.4.8
+date: 2024-12-15 00:00:00.000000000 Z
+dependencies: []
 description: The CSV library provides a complete interface to CSV files and data.
   It offers tools to enable you to read and write to and from Strings or IO objects,
   as needed.
@@ -127,6 +72,7 @@ licenses:
 - Ruby
 - BSD-2-Clause
 metadata: {}
+post_install_message:
 rdoc_options:
 - "--main"
 - README.md
@@ -143,7 +89,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.0.dev
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: CSV Reading and Writing
 test_files: []