csv 3.1.8 → 3.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a9f965a5db6ac6d07f525f513e212f082c137b487d73328373d0afef7bb8312
-  data.tar.gz: 5184ad5878a6dee8603e3b48fc820b50e3687eafb96cbcec152a8d621ceaffd6
+  metadata.gz: 8682072d16c079d3d25b3f22ca9f06cae36210998194ae3f3de627c74c062453
+  data.tar.gz: 755bddbed0b08dd681939a76c5f6a80f2c536a0e72edcf6e8c770be860e5fcae
 SHA512:
-  metadata.gz: 422a1a8751e4e8c21884848e7f465e39090b946c3febff711bb756c98e61b7e6aebf0e552adee851d653f89e9ef2772984db2b05a243c7fac8060c64def34ae0
-  data.tar.gz: 9d85fa756cd744e74da2ae1e89650768370566a5fd8ce1830337d528f9875d07422508eb007522ae3e7ec9c20c9ec055983f09c9b951e78441706bb2d33fdd59
+  metadata.gz: 28e191df9cb41c6ca04a9969eace28deac9217de9f2677b7edec8803531c28b4c47e4866d00fd6edbc5ea0b21f10a4f59b376473475a8c96317949b84b53f49a
+  data.tar.gz: 4c747ddbdb78e4e6e8dc725199b2f35aea7949b7eb5b49929c2e818d15cbebfaa07825f57a5ee092a5da7f5c75fc2ea3c035ff204f1a95a12283cea85720e31c

data/NEWS.md

@@ -1,5 +1,103 @@
 # News
 
+## 3.2.2 - 2021-12-24
+
+### Improvements
+
+  * Added a validation for invalid option combination.
+    [GitHub#225][Patch by adamroyjones]
+
+  * Improved documentation for developers.
+    [GitHub#227][Patch by Eriko Sugiyama]
+
+### Fixes
+
+  * Fixed a bug that all of `ARGF` contents may not be consumed.
+    [GitHub#228][Reported by Rafael Navaza]
+
+  * Fixed a bug that some texts may be dropped unexpectedly.
+    [Bug #18245][ruby-core:105587][Reported by Hassan Abdul Rehman]
+
+### Thanks
+
+  * adamroyjones
+
+  * Eriko Sugiyama
+
+  * Rafael Navaza
+
+  * Hassan Abdul Rehman
+
+## 3.2.1 - 2021-10-23
+
+### Improvements
+
+  * doc: Fixed wrong class name.
+    [GitHub#217][Patch by Vince]
+
+  * Changed to always use `"\n"` for the default row separator on Ruby
+    3.0 or later because `$INPUT_RECORD_SEPARATOR` was deprecated
+    since Ruby 3.0.
+
+  * Added support for Ractor.
+    [GitHub#218][Patch by rm155]
+
+    * Users who want to use the built-in converters in non-main
+      Ractors need to call `Ractor.make_shareable(CSV::Converters)`
+      and/or `Ractor.make_shareable(CSV::HeaderConverters)` before
+      creating non-main Ractors.
+
+### Thanks
+
+  * Vince
+
+  * Joakim Antman
+
+  * rm155
+
+## 3.2.0 - 2021-06-06
+
+### Improvements
+
+  * `CSV.open`: Added support for `:newline` option.
+    [GitHub#198][Patch by Nobuyoshi Nakada]
+
+  * `CSV::Table#each`: Added support for column mode with duplicated
+    headers.
+    [GitHub#206][Reported by Yaroslav Berezovskiy]
+
+  * `Object#CSV`: Added support for Ruby 3.0.
+
+  * `CSV::Row`: Added support for pattern matching.
+    [GitHub#207][Patch by Kevin Newton]
+
+### Fixes
+
+  * Fixed typos in documentation.
+    [GitHub#196][GitHub#205][Patch by Sampat Badhe]
+
+### Thanks
+
+  * Sampat Badhe
+
+  * Nobuyoshi Nakada
+
+  * Yaroslav Berezovskiy
+
+  * Kevin Newton
+
+## 3.1.9 - 2020-11-23
+
+### Fixes
+
+  * Fixed a compatibility bug that the line to be processed by
+    `skip_lines:` has a row separator.
+    [GitHub#194][Reported by Josef Šimánek]
+
+### Thanks
+
+  * Josef Šimánek
+
 ## 3.1.8 - 2020-11-18
 
 ### Improvements

data/README.md

@@ -1,8 +1,5 @@
 # CSV
 
-[![Build Status](https://travis-ci.org/ruby/csv.svg?branch=master)](https://travis-ci.org/ruby/csv)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/321fa39e510a0abd0369/test_coverage)](https://codeclimate.com/github/ruby/csv/test_coverage)
-
 This 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.
 
 ## Installation
@@ -33,12 +30,12 @@ end
 
 ## Documentation
 
-- {API}[CSV.html]:  all classes, methods, and constants.
-- {Recipes}[doc/csv/recipes/recipes_rdoc.html]:  specific code for specific tasks.
+- [API](https://ruby-doc.org/stdlib/libdoc/csv/rdoc/CSV.html):  all classes, methods, and constants.
+- [Recipes](https://ruby-doc.org/core/doc/csv/recipes/recipes_rdoc.html):  specific code for specific tasks.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `ruby run-test.rb` to check if your changes can pass the test.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/doc/csv/recipes/parsing.rdoc

@@ -431,7 +431,7 @@ You can use multiple field converters in either of these ways:
 
 ===== Recipe: Specify Multiple Field Converters in Option +:converters+
 
-Apply multiple field converters by specifying them in option +:conveters+:
+Apply multiple field converters by specifying them in option +:converters+:
   source = "Name,Value\nfoo,0\nbar,1.0\nbaz,2.0\n"
   parsed = CSV.parse(source, headers: true, converters: [:integer, :float])
   parsed['Value'] # => [0, 1.0, 2.0]
@@ -500,7 +500,7 @@ You can use multiple header converters in either of these ways:
 
 ===== Recipe: Specify Multiple Header Converters in Option :header_converters
 
-Apply multiple header converters by specifying them in option +:header_conveters+:
+Apply multiple header converters by specifying them in option +:header_converters+:
   source = "Name,Value\nfoo,0\nbar,1.0\nbaz,2.0\n"
   parsed = CSV.parse(source, headers: true, header_converters: [:downcase, :symbol])
   parsed.headers # => [:name, :value]

data/lib/csv/fields_converter.rb

@@ -16,7 +16,7 @@ class CSV
       @empty_value = options[:empty_value]
       @empty_value_is_empty_string = (@empty_value == "")
       @accept_nil = options[:accept_nil]
-      @builtin_converters = options[:builtin_converters]
+      @builtin_converters_name = options[:builtin_converters_name]
       @need_static_convert = need_static_convert?
     end
 
@@ -24,7 +24,7 @@ class CSV
       if name.nil?  # custom converter
         @converters << converter
       else          # named converter
-        combo = @builtin_converters[name]
+        combo = builtin_converters[name]
         case combo
         when Array  # combo converter
           combo.each do |sub_name|
@@ -80,5 +80,9 @@ class CSV
       @need_static_convert or
         (not @converters.empty?)
     end
+
+    def builtin_converters
+      @builtin_converters ||= ::CSV.const_get(@builtin_converters_name)
+    end
   end
 end

data/lib/csv/input_record_separator.rb

@@ -0,0 +1,31 @@
+require "English"
+require "stringio"
+
+class CSV
+  module InputRecordSeparator
+    class << self
+      is_input_record_separator_deprecated = false
+      verbose, $VERBOSE = $VERBOSE, true
+      stderr, $stderr = $stderr, StringIO.new
+      input_record_separator = $INPUT_RECORD_SEPARATOR
+      begin
+        $INPUT_RECORD_SEPARATOR = "\r\n"
+        is_input_record_separator_deprecated = (not $stderr.string.empty?)
+      ensure
+        $INPUT_RECORD_SEPARATOR = input_record_separator
+        $stderr = stderr
+        $VERBOSE = verbose
+      end
+
+      if is_input_record_separator_deprecated
+        def value
+          "\n"
+        end
+      else
+        def value
+          $INPUT_RECORD_SEPARATOR
+        end
+      end
+    end
+  end
+end

data/lib/csv/parser.rb

@@ -3,6 +3,7 @@
 require "strscan"
 
 require_relative "delete_suffix"
+require_relative "input_record_separator"
 require_relative "match_p"
 require_relative "row"
 require_relative "table"
@@ -84,9 +85,10 @@ class CSV
     # If there is no more data (eos? = true), it returns "".
     #
     class InputsScanner
-      def initialize(inputs, encoding, chunk_size: 8192)
+      def initialize(inputs, encoding, row_separator, chunk_size: 8192)
         @inputs = inputs.dup
         @encoding = encoding
+        @row_separator = row_separator
         @chunk_size = chunk_size
         @last_scanner = @inputs.empty?
         @keeps = []
@@ -232,7 +234,7 @@ class CSV
           @last_scanner = @inputs.empty?
           true
         else
-          chunk = input.gets(nil, @chunk_size)
+          chunk = input.gets(@row_separator, @chunk_size)
           if chunk
             raise InvalidEncoding unless chunk.valid_encoding?
             @scanner = StringScanner.new(chunk)
@@ -360,6 +362,7 @@ class CSV
       prepare_skip_lines
       prepare_strip
       prepare_separators
+      validate_strip_and_col_sep_options
       prepare_quoted
       prepare_unquoted
       prepare_line
@@ -479,9 +482,9 @@ class CSV
     begin
       StringScanner.new("x").scan("x")
     rescue TypeError
-      @@string_scanner_scan_accept_string = false
+      STRING_SCANNER_SCAN_ACCEPT_STRING = false
     else
-      @@string_scanner_scan_accept_string = true
+      STRING_SCANNER_SCAN_ACCEPT_STRING = true
     end
 
     def prepare_separators
@@ -505,7 +508,7 @@ class CSV
         @first_column_separators = Regexp.new(@escaped_first_column_separator +
                                               "+".encode(@encoding))
       else
-        if @@string_scanner_scan_accept_string
+        if STRING_SCANNER_SCAN_ACCEPT_STRING
           @column_end = @column_separator
         else
           @column_end = Regexp.new(@escaped_column_separator)
@@ -526,10 +529,32 @@ class CSV
 
       @cr = "\r".encode(@encoding)
       @lf = "\n".encode(@encoding)
-      @cr_or_lf = Regexp.new("[\r\n]".encode(@encoding))
+      @line_end = Regexp.new("\r\n|\n|\r".encode(@encoding))
       @not_line_end = Regexp.new("[^\r\n]+".encode(@encoding))
     end
 
+    # This method verifies that there are no (obvious) ambiguities with the
+    # provided +col_sep+ and +strip+ parsing options. For example, if +col_sep+
+    # and +strip+ were both equal to +\t+, then there would be no clear way to
+    # parse the input.
+    def validate_strip_and_col_sep_options
+      return unless @strip
+
+      if @strip.is_a?(String)
+        if @column_separator.start_with?(@strip) || @column_separator.end_with?(@strip)
+          raise ArgumentError,
+                "The provided strip (#{@escaped_strip}) and " \
+                "col_sep (#{@escaped_column_separator}) options are incompatible."
+        end
+      else
+        if Regexp.new("\\A[#{@escaped_strip}]|[#{@escaped_strip}]\\z").match?(@column_separator)
+          raise ArgumentError,
+                "The provided strip (true) and " \
+                "col_sep (#{@escaped_column_separator}) options are incompatible."
+        end
+      end
+    end
+
     def prepare_quoted
       if @quote_character
         @quotes = Regexp.new(@escaped_quote_character +
@@ -605,7 +630,7 @@ class CSV
             # do nothing:  ensure will set default
           end
         end
-        separator = $INPUT_RECORD_SEPARATOR if separator == :auto
+        separator = InputRecordSeparator.value if separator == :auto
       end
       separator.to_s.encode(@encoding)
     end
@@ -724,6 +749,8 @@ class CSV
         end
       end
 
+      SCANNER_TEST_CHUNK_SIZE =
+        Integer((ENV["CSV_PARSER_SCANNER_TEST_CHUNK_SIZE"] || "1"), 10)
       def build_scanner
         inputs = @samples.collect do |sample|
           UnoptimizedStringIO.new(sample)
@@ -733,17 +760,20 @@ class CSV
         else
           inputs << @input
         end
-        chunk_size = ENV["CSV_PARSER_SCANNER_TEST_CHUNK_SIZE"] || "1"
         InputsScanner.new(inputs,
                           @encoding,
-                          chunk_size: Integer(chunk_size, 10))
+                          @row_separator,
+                          chunk_size: SCANNER_TEST_CHUNK_SIZE)
       end
     else
       def build_scanner
         string = nil
         if @samples.empty? and @input.is_a?(StringIO)
           string = @input.read
-        elsif @samples.size == 1 and @input.respond_to?(:eof?) and @input.eof?
+        elsif @samples.size == 1 and
+              @input != ARGF and
+              @input.respond_to?(:eof?) and
+              @input.eof?
           string = @samples[0]
         end
         if string
@@ -762,7 +792,7 @@ class CSV
             StringIO.new(sample)
           end
           inputs << @input
-          InputsScanner.new(inputs, @encoding)
+          InputsScanner.new(inputs, @encoding, @row_separator)
         end
       end
     end
@@ -785,6 +815,7 @@ class CSV
     end
 
     def skip_line?(line)
+      line = line.delete_suffix(@row_separator)
       case @skip_lines
       when String
         line.include?(@skip_lines)
@@ -913,7 +944,7 @@ class CSV
             message = "Any value after quoted field isn't allowed"
             raise MalformedCSVError.new(message, @lineno)
           elsif @unquoted_column_value and
-                (new_line = @scanner.scan(@cr_or_lf))
+                (new_line = @scanner.scan(@line_end))
             ignore_broken_line
             message = "Unquoted fields do not allow new line " +
                       "<#{new_line.inspect}>"
@@ -922,7 +953,7 @@ class CSV
             ignore_broken_line
             message = "Illegal quoting"
             raise MalformedCSVError.new(message, @lineno)
-          elsif (new_line = @scanner.scan(@cr_or_lf))
+          elsif (new_line = @scanner.scan(@line_end))
             ignore_broken_line
             message = "New line must be <#{@row_separator.inspect}> " +
                       "not <#{new_line.inspect}>"
@@ -1088,7 +1119,7 @@ class CSV
 
     def ignore_broken_line
       @scanner.scan_all(@not_line_end)
-      @scanner.scan_all(@cr_or_lf)
+      @scanner.scan_all(@line_end)
       @lineno += 1
     end
 

data/lib/csv/row.rb

@@ -203,7 +203,7 @@ class CSV
     def field(header_or_index, minimum_index = 0)
       # locate the pair
       finder = (header_or_index.is_a?(Integer) || header_or_index.is_a?(Range)) ? :[] : :assoc
-      pair   = @row[minimum_index..-1].send(finder, header_or_index)
+      pair   = @row[minimum_index..-1].public_send(finder, header_or_index)
 
       # return the field if we have a pair
       if pair.nil?
@@ -659,8 +659,30 @@ class CSV
     end
     alias_method :to_hash, :to_h
 
+    # :call-seq:
+    #   row.deconstruct_keys(keys) -> hash
+    #
+    # Returns the new \Hash suitable for pattern matching containing only the
+    # keys specified as an argument.
+    def deconstruct_keys(keys)
+      if keys.nil?
+        to_h
+      else
+        keys.to_h { |key| [key, self[key]] }
+      end
+    end
+
     alias_method :to_ary, :to_a
 
+    # :call-seq:
+    #   row.deconstruct -> array
+    #
+    # Returns the new \Array suitable for pattern matching containing the values
+    # of the row.
+    def deconstruct
+      fields
+    end
+
     # :call-seq:
     #   row.to_csv -> csv_string
     #

data/lib/csv/table.rb

@@ -932,7 +932,9 @@ class CSV
       return enum_for(__method__) { @mode == :col ? headers.size : size } unless block_given?
 
       if @mode == :col
-        headers.each { |header| yield([header, self[header]]) }
+        headers.each.with_index do |header, i|
+          yield([header, @table.map {|row| row[header, i]}])
+        end
       else
         @table.each(&block)
       end

data/lib/csv/version.rb

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

data/lib/csv/writer.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "input_record_separator"
 require_relative "match_p"
 require_relative "row"
 
@@ -133,7 +134,7 @@ class CSV
       @column_separator = @options[:column_separator].to_s.encode(@encoding)
       row_separator = @options[:row_separator]
       if row_separator == :auto
-        @row_separator = $INPUT_RECORD_SEPARATOR.encode(@encoding)
+        @row_separator = InputRecordSeparator.value.encode(@encoding)
       else
         @row_separator = row_separator.to_s.encode(@encoding)
       end

data/lib/csv.rb

@@ -48,7 +48,7 @@
 #
 # === Interface
 #
-# * CSV now uses Hash-style parameters to set options.
+# * CSV now uses keyword parameters to set options.
 # * CSV no longer has generate_row() or parse_row().
 # * The old CSV's Reader and Writer classes have been dropped.
 # * CSV::open() is now more like Ruby's open().
@@ -90,11 +90,11 @@
 # with any questions.
 
 require "forwardable"
-require "English"
 require "date"
 require "stringio"
 
 require_relative "csv/fields_converter"
+require_relative "csv/input_record_separator"
 require_relative "csv/match_p"
 require_relative "csv/parser"
 require_relative "csv/row"
@@ -341,6 +341,7 @@ using CSV::MatchP if CSV.const_defined?(:MatchP)
 #     liberal_parsing:    false,
 #     nil_value:          nil,
 #     empty_value:        "",
+#     strip:              false,
 #     # For generating.
 #     write_headers:      nil,
 #     quote_empty:        true,
@@ -348,7 +349,6 @@ using CSV::MatchP if CSV.const_defined?(:MatchP)
 #     write_converters:   nil,
 #     write_nil_value:    nil,
 #     write_empty_value:  "",
-#     strip:              false,
 #   }
 #
 # ==== Options for Parsing
@@ -366,8 +366,9 @@ using CSV::MatchP if CSV.const_defined?(:MatchP)
 # - +header_converters+: Specifies the header converters to be used.
 # - +skip_blanks+: Specifies whether blanks lines are to be ignored.
 # - +skip_lines+: Specifies how comments lines are to be recognized.
-# - +strip+: Specifies whether leading and trailing whitespace are
-#   to be stripped from fields..
+# - +strip+: Specifies whether leading and trailing whitespace are to be
+#   stripped from fields. This must be compatible with +col_sep+; if it is not,
+#   then an +ArgumentError+ exception will be raised.
 # - +liberal_parsing+: Specifies whether \CSV should attempt to parse
 #   non-compliant data.
 # - +nil_value+: Specifies the object that is to be substituted for each null (no-text) field.
@@ -513,7 +514,7 @@ using CSV::MatchP if CSV.const_defined?(:MatchP)
 #  [" 1 ", #<struct CSV::FieldInfo index=1, line=2, header=nil>]
 #  [" baz ", #<struct CSV::FieldInfo index=0, line=3, header=nil>]
 #  [" 2 ", #<struct CSV::FieldInfo index=1, line=3, header=nil>]
-# Each CSV::Info object shows:
+# Each CSV::FieldInfo object shows:
 # - The 0-based field index.
 # - The 1-based line index.
 # - The field header, if any.
@@ -547,6 +548,14 @@ using CSV::MatchP if CSV.const_defined?(:MatchP)
 #
 # There is no such storage structure for write headers.
 #
+# In order for the parsing methods to access stored converters in non-main-Ractors, the
+# storage structure must be made shareable first.
+# Therefore, <tt>Ractor.make_shareable(CSV::Converters)</tt> and
+# <tt>Ractor.make_shareable(CSV::HeaderConverters)</tt> must be called before the creation
+# of Ractors that use the converters stored in these structures. (Since making the storage
+# structures shareable involves freezing them, any custom converters that are to be used
+# must be added first.)
+#
 # ===== Converter Lists
 #
 # A _converter_ _list_ is an \Array that may include any assortment of:
@@ -705,7 +714,7 @@ using CSV::MatchP if CSV.const_defined?(:MatchP)
 # Header converters operate only on headers (and not on other rows).
 #
 # There are three ways to use header \converters;
-# these examples use built-in header converter +:dowhcase+,
+# these examples use built-in header converter +:downcase+,
 # which downcases each parsed header.
 #
 # - Option +header_converters+ with a singleton parsing method:
@@ -919,6 +928,7 @@ class CSV
                                            gsub(/\s+/, "_").to_sym
     }
   }
+
   # Default values for method options.
   DEFAULT_OPTIONS = {
     # For both parsing and generating.
@@ -937,6 +947,7 @@ class CSV
     liberal_parsing:    false,
     nil_value:          nil,
     empty_value:        "",
+    strip:              false,
     # For generating.
     write_headers:      nil,
     quote_empty:        true,
@@ -944,7 +955,6 @@ class CSV
     write_converters:   nil,
     write_nil_value:    nil,
     write_empty_value:  "",
-    strip:              false,
   }.freeze
 
   class << self
@@ -957,6 +967,8 @@ class CSV
     # Creates or retrieves cached \CSV objects.
     # For arguments and options, see CSV.new.
     #
+    # This API is not Ractor-safe.
+    #
     # ---
     #
     # With no block given, returns a \CSV object.
@@ -1006,63 +1018,188 @@ class CSV
     end
 
     # :call-seq:
-    #   filter(**options) {|row| ... }
-    #   filter(in_string, **options) {|row| ... }
-    #   filter(in_io, **options) {|row| ... }
-    #   filter(in_string, out_string, **options) {|row| ... }
-    #   filter(in_string, out_io, **options) {|row| ... }
-    #   filter(in_io, out_string, **options) {|row| ... }
-    #   filter(in_io, out_io, **options) {|row| ... }
-    #
-    # Reads \CSV input and writes \CSV output.
-    #
-    # For each input row:
-    # - Forms the data into:
-    #   - A CSV::Row object, if headers are in use.
-    #   - An \Array of Arrays, otherwise.
-    # - Calls the block with that object.
-    # - Appends the block's return value to the output.
+    #   filter(in_string_or_io, **options) {|row| ... } -> array_of_arrays or csv_table
+    #   filter(in_string_or_io, out_string_or_io, **options) {|row| ... } -> array_of_arrays or csv_table
+    #   filter(**options) {|row| ... } -> array_of_arrays or csv_table
     #
-    # Arguments:
-    # * \CSV source:
-    #   * Argument +in_string+, if given, should be a \String object;
-    #     it will be put into a new StringIO object positioned at the beginning.
-    #   * Argument +in_io+, if given, should be an IO object that is
-    #     open for reading; on return, the IO object will be closed.
-    #   * If neither  +in_string+ nor +in_io+ is given,
-    #     the input stream defaults to {ARGF}[https://ruby-doc.org/core/ARGF.html].
-    # * \CSV output:
-    #   * Argument +out_string+, if given, should be a \String object;
-    #     it will be put into a new StringIO object positioned at the beginning.
-    #   * Argument +out_io+, if given, should be an IO object that is
-    #     ppen for writing; on return, the IO object will be closed.
-    #   * If neither +out_string+ nor +out_io+ is given,
-    #     the output stream defaults to <tt>$stdout</tt>.
-    # * Argument +options+ should be keyword arguments.
-    #   - Each argument name that is prefixed with +in_+ or +input_+
-    #     is stripped of its prefix and is treated as an option
-    #     for parsing the input.
-    #     Option +input_row_sep+ defaults to <tt>$INPUT_RECORD_SEPARATOR</tt>.
-    #   - Each argument name that is prefixed with +out_+ or +output_+
-    #     is stripped of its prefix and is treated as an option
-    #     for generating the output.
-    #     Option +output_row_sep+ defaults to <tt>$INPUT_RECORD_SEPARATOR</tt>.
-    #   - Each argument not prefixed as above is treated as an option
-    #     both for parsing the input and for generating the output.
-    #   - See {Options for Parsing}[#class-CSV-label-Options+for+Parsing]
-    #     and {Options for Generating}[#class-CSV-label-Options+for+Generating].
+    # - Parses \CSV from a source (\String, \IO stream, or ARGF).
+    # - Calls the given block with each parsed row:
+    #   - Without headers, each row is an \Array.
+    #   - With headers, each row is a CSV::Row.
+    # - Generates \CSV to an output (\String, \IO stream, or STDOUT).
+    # - Returns the parsed source:
+    #   - Without headers, an \Array of \Arrays.
+    #   - With headers, a CSV::Table.
     #
-    # Example:
-    #   in_string = "foo,0\nbar,1\nbaz,2\n"
+    # When +in_string_or_io+ is given, but not +out_string_or_io+,
+    # parses from the given +in_string_or_io+
+    # and generates to STDOUT.
+    #
+    # \String input without headers:
+    #
+    #   in_string = "foo,0\nbar,1\nbaz,2"
+    #   CSV.filter(in_string) do |row|
+    #     row[0].upcase!
+    #     row[1] = - row[1].to_i
+    #   end # => [["FOO", 0], ["BAR", -1], ["BAZ", -2]]
+    #
+    # Output (to STDOUT):
+    #
+    #   FOO,0
+    #   BAR,-1
+    #   BAZ,-2
+    #
+    # \String input with headers:
+    #
+    #   in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2"
+    #   CSV.filter(in_string, headers: true) do |row|
+    #     row[0].upcase!
+    #     row[1] = - row[1].to_i
+    #   end # => #<CSV::Table mode:col_or_row row_count:4>
+    #
+    # Output (to STDOUT):
+    #
+    #   Name,Value
+    #   FOO,0
+    #   BAR,-1
+    #   BAZ,-2
+    #
+    # \IO stream input without headers:
+    #
+    #   File.write('t.csv', "foo,0\nbar,1\nbaz,2")
+    #   File.open('t.csv') do |in_io|
+    #     CSV.filter(in_io) do |row|
+    #       row[0].upcase!
+    #       row[1] = - row[1].to_i
+    #     end
+    #   end # => [["FOO", 0], ["BAR", -1], ["BAZ", -2]]
+    #
+    # Output (to STDOUT):
+    #
+    #   FOO,0
+    #   BAR,-1
+    #   BAZ,-2
+    #
+    # \IO stream input with headers:
+    #
+    #   File.write('t.csv', "Name,Value\nfoo,0\nbar,1\nbaz,2")
+    #   File.open('t.csv') do |in_io|
+    #     CSV.filter(in_io, headers: true) do |row|
+    #       row[0].upcase!
+    #       row[1] = - row[1].to_i
+    #     end
+    #   end # => #<CSV::Table mode:col_or_row row_count:4>
+    #
+    # Output (to STDOUT):
+    #
+    #   Name,Value
+    #   FOO,0
+    #   BAR,-1
+    #   BAZ,-2
+    #
+    # When both +in_string_or_io+ and +out_string_or_io+ are given,
+    # parses from +in_string_or_io+ and generates to +out_string_or_io+.
+    #
+    # \String output without headers:
+    #
+    #   in_string = "foo,0\nbar,1\nbaz,2"
     #   out_string = ''
     #   CSV.filter(in_string, out_string) do |row|
-    #     row[0] = row[0].upcase
-    #     row[1] *= 4
-    #   end
-    #   out_string # => "FOO,0000\nBAR,1111\nBAZ,2222\n"
+    #     row[0].upcase!
+    #     row[1] = - row[1].to_i
+    #   end # => [["FOO", 0], ["BAR", -1], ["BAZ", -2]]
+    #   out_string # => "FOO,0\nBAR,-1\nBAZ,-2\n"
+    #
+    # \String output with headers:
+    #
+    #   in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2"
+    #   out_string = ''
+    #   CSV.filter(in_string, out_string, headers: true) do |row|
+    #     row[0].upcase!
+    #     row[1] = - row[1].to_i
+    #   end # => #<CSV::Table mode:col_or_row row_count:4>
+    #   out_string # => "Name,Value\nFOO,0\nBAR,-1\nBAZ,-2\n"
+    #
+    # \IO stream output without headers:
+    #
+    #   in_string = "foo,0\nbar,1\nbaz,2"
+    #   File.open('t.csv', 'w') do |out_io|
+    #     CSV.filter(in_string, out_io) do |row|
+    #       row[0].upcase!
+    #       row[1] = - row[1].to_i
+    #     end
+    #   end # => [["FOO", 0], ["BAR", -1], ["BAZ", -2]]
+    #   File.read('t.csv') # => "FOO,0\nBAR,-1\nBAZ,-2\n"
+    #
+    # \IO stream output with headers:
+    #
+    #   in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2"
+    #   File.open('t.csv', 'w') do |out_io|
+    #     CSV.filter(in_string, out_io, headers: true) do |row|
+    #       row[0].upcase!
+    #       row[1] = - row[1].to_i
+    #     end
+    #   end # => #<CSV::Table mode:col_or_row row_count:4>
+    #   File.read('t.csv') # => "Name,Value\nFOO,0\nBAR,-1\nBAZ,-2\n"
+    #
+    # When neither +in_string_or_io+ nor +out_string_or_io+ given,
+    # parses from {ARGF}[https://docs.ruby-lang.org/en/master/ARGF.html]
+    # and generates to STDOUT.
+    #
+    # Without headers:
+    #
+    #   # Put Ruby code into a file.
+    #   ruby = <<-EOT
+    #     require 'csv'
+    #     CSV.filter do |row|
+    #       row[0].upcase!
+    #       row[1] = - row[1].to_i
+    #     end
+    #   EOT
+    #   File.write('t.rb', ruby)
+    #   # Put some CSV into a file.
+    #   File.write('t.csv', "foo,0\nbar,1\nbaz,2")
+    #   # Run the Ruby code with CSV filename as argument.
+    #   system(Gem.ruby, "t.rb", "t.csv")
+    #
+    # Output (to STDOUT):
+    #
+    #   FOO,0
+    #   BAR,-1
+    #   BAZ,-2
+    #
+    # With headers:
+    #
+    #   # Put Ruby code into a file.
+    #   ruby = <<-EOT
+    #     require 'csv'
+    #     CSV.filter(headers: true) do |row|
+    #       row[0].upcase!
+    #       row[1] = - row[1].to_i
+    #     end
+    #   EOT
+    #   File.write('t.rb', ruby)
+    #   # Put some CSV into a file.
+    #   File.write('t.csv', "Name,Value\nfoo,0\nbar,1\nbaz,2")
+    #   # Run the Ruby code with CSV filename as argument.
+    #   system(Gem.ruby, "t.rb", "t.csv")
+    #
+    # Output (to STDOUT):
+    #
+    #   Name,Value
+    #   FOO,0
+    #   BAR,-1
+    #   BAZ,-2
+    #
+    # Arguments:
+    #
+    # * 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].
     def filter(input=nil, output=nil, **options)
       # parse options for input, output, or both
-      in_options, out_options = Hash.new, {row_sep: $INPUT_RECORD_SEPARATOR}
+      in_options, out_options = Hash.new, {row_sep: InputRecordSeparator.value}
       options.each do |key, value|
         case key.to_s
         when /\Ain(?:put)?_(.+)\Z/
@@ -1106,111 +1243,90 @@ class CSV
 
     #
     # :call-seq:
-    #   foreach(path, mode='r', **options) {|row| ... )
-    #   foreach(io, mode='r', **options {|row| ... )
-    #   foreach(path, mode='r', headers: ..., **options) {|row| ... )
-    #   foreach(io, mode='r', headers: ..., **options {|row| ... )
-    #   foreach(path, mode='r', **options) -> new_enumerator
-    #   foreach(io, mode='r', **options -> new_enumerator
+    #   foreach(path_or_io, mode='r', **options) {|row| ... )
+    #   foreach(path_or_io, mode='r', **options) -> new_enumerator
     #
-    # Calls the block with each row read from source +path+ or +io+.
+    # Calls the block with each row read from source +path_or_io+.
     #
-    # * Argument +path+, if given, must be the path to a file.
-    # :include: ../doc/csv/arguments/io.rdoc
-    # * Argument +mode+, if given, must be a \File mode
-    #   See {Open Mode}[IO.html#method-c-new-label-Open+Mode].
-    # * Arguments <tt>**options</tt> must be keyword options.
-    #   See {Options for Parsing}[#class-CSV-label-Options+for+Parsing].
-    # * This method optionally accepts an additional <tt>:encoding</tt> option
-    #   that you can use to specify the Encoding of the data read from +path+ or +io+.
-    #   You must provide this unless your data is in the encoding
-    #   given by <tt>Encoding::default_external</tt>.
-    #   Parsing will use this to determine how to parse the data.
-    #   You may provide a second Encoding to
-    #   have the data transcoded as it is read. For example,
-    #     encoding: 'UTF-32BE:UTF-8'
-    #   would read +UTF-32BE+ data from the file
-    #   but transcode it to +UTF-8+ before parsing.
+    # \Path input without headers:
     #
-    # ====== Without Option +headers+
-    #
-    # Without option +headers+, returns each row as an \Array object.
-    #
-    # These examples assume prior execution of:
     #   string = "foo,0\nbar,1\nbaz,2\n"
-    #   path = 't.csv'
-    #   File.write(path, string)
+    #   in_path = 't.csv'
+    #   File.write(in_path, string)
+    #   CSV.foreach(in_path) {|row| p row }
     #
-    # Read rows from a file at +path+:
-    #   CSV.foreach(path) {|row| p row }
     # Output:
-    #   ["foo", "0"]
-    #   ["bar", "1"]
-    #   ["baz", "2"]
-    #
-    # Read rows from an \IO object:
-    #   File.open(path) do |file|
-    #     CSV.foreach(file) {|row| p row }
-    #   end
     #
-    # Output:
     #   ["foo", "0"]
     #   ["bar", "1"]
     #   ["baz", "2"]
     #
-    # Returns a new \Enumerator if no block given:
-    #   CSV.foreach(path) # => #<Enumerator: CSV:foreach("t.csv", "r")>
-    #   CSV.foreach(File.open(path)) # => #<Enumerator: CSV:foreach(#<File:t.csv>, "r")>
+    # \Path input with headers:
+    #
+    #   string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   in_path = 't.csv'
+    #   File.write(in_path, string)
+    #   CSV.foreach(in_path, headers: true) {|row| p row }
     #
-    # Issues a warning if an encoding is unsupported:
-    #   CSV.foreach(File.open(path), encoding: 'foo:bar') {|row| }
     # Output:
-    #   warning: Unsupported encoding foo ignored
-    #   warning: Unsupported encoding bar ignored
     #
-    # ====== With Option +headers+
+    #   <CSV::Row "Name":"foo" "Value":"0">
+    #   <CSV::Row "Name":"bar" "Value":"1">
+    #   <CSV::Row "Name":"baz" "Value":"2">
     #
-    # With {option +headers+}[#class-CSV-label-Option+headers],
-    # returns each row as a CSV::Row object.
+    # \IO stream input without headers:
     #
-    # These examples assume prior execution of:
-    #   string = "Name,Count\nfoo,0\nbar,1\nbaz,2\n"
+    #   string = "foo,0\nbar,1\nbaz,2\n"
     #   path = 't.csv'
     #   File.write(path, string)
-    #
-    # Read rows from a file at +path+:
-    #   CSV.foreach(path, headers: true) {|row| p row }
+    #   File.open('t.csv') do |in_io|
+    #     CSV.foreach(in_io) {|row| p row }
+    #   end
     #
     # Output:
-    #   #<CSV::Row "Name":"foo" "Count":"0">
-    #   #<CSV::Row "Name":"bar" "Count":"1">
-    #   #<CSV::Row "Name":"baz" "Count":"2">
     #
-    # Read rows from an \IO object:
-    #   File.open(path) do |file|
-    #     CSV.foreach(file, headers: true) {|row| p row }
+    #   ["foo", "0"]
+    #   ["bar", "1"]
+    #   ["baz", "2"]
+    #
+    # \IO stream input with headers:
+    #
+    #   string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   path = 't.csv'
+    #   File.write(path, string)
+    #   File.open('t.csv') do |in_io|
+    #     CSV.foreach(in_io, headers: true) {|row| p row }
     #   end
     #
     # Output:
-    #   #<CSV::Row "Name":"foo" "Count":"0">
-    #   #<CSV::Row "Name":"bar" "Count":"1">
-    #   #<CSV::Row "Name":"baz" "Count":"2">
-    #
-    # ---
     #
-    # Raises an exception if +path+ is a \String, but not the path to a readable file:
-    #   # Raises Errno::ENOENT (No such file or directory @ rb_sysopen - nosuch.csv):
-    #   CSV.foreach('nosuch.csv') {|row| }
+    #   <CSV::Row "Name":"foo" "Value":"0">
+    #   <CSV::Row "Name":"bar" "Value":"1">
+    #   <CSV::Row "Name":"baz" "Value":"2">
     #
-    # Raises an exception if +io+ is an \IO object, but not open for reading:
-    #   io = File.open(path, 'w') {|row| }
-    #   # Raises TypeError (no implicit conversion of nil into String):
-    #   CSV.foreach(io) {|row| }
+    # With no block given, returns an \Enumerator:
     #
-    # Raises an exception if +mode+ is invalid:
-    #   # Raises ArgumentError (invalid access mode nosuch):
-    #   CSV.foreach(path, 'nosuch') {|row| }
+    #   string = "foo,0\nbar,1\nbaz,2\n"
+    #   path = 't.csv'
+    #   File.write(path, string)
+    #   CSV.foreach(path) # => #<Enumerator: CSV:foreach("t.csv", "r")>
     #
+    # Arguments:
+    # * Argument +path_or_io+ must be a file path or an \IO stream.
+    # * Argument +mode+, if given, must be a \File mode
+    #   See {Open Mode}[https://ruby-doc.org/core/IO.html#method-c-new-label-Open+Mode].
+    # * Arguments <tt>**options</tt> must be keyword options.
+    #   See {Options for Parsing}[#class-CSV-label-Options+for+Parsing].
+    # * This method optionally accepts an additional <tt>:encoding</tt> option
+    #   that you can use to specify the Encoding of the data read from +path+ or +io+.
+    #   You must provide this unless your data is in the encoding
+    #   given by <tt>Encoding::default_external</tt>.
+    #   Parsing will use this to determine how to parse the data.
+    #   You may provide a second Encoding to
+    #   have the data transcoded as it is read. For example,
+    #     encoding: 'UTF-32BE:UTF-8'
+    #   would read +UTF-32BE+ data from the file
+    #   but transcode it to +UTF-8+ before parsing.
     def foreach(path, mode="r", **options, &block)
       return to_enum(__method__, path, mode, **options) unless block_given?
       open(path, mode, **options) do |csv|
@@ -1303,8 +1419,8 @@ class CSV
     # Argument +ary+ must be an \Array.
     #
     # Special options:
-    # * Option <tt>:row_sep</tt> defaults to <tt>$INPUT_RECORD_SEPARATOR</tt>
-    #   (<tt>$/</tt>).:
+    # * Option <tt>:row_sep</tt> defaults to <tt>"\n"> on Ruby 3.0 or later
+    #   and <tt>$INPUT_RECORD_SEPARATOR</tt> (<tt>$/</tt>) otherwise.:
     #     $INPUT_RECORD_SEPARATOR # => "\n"
     # * This method accepts an additional option, <tt>:encoding</tt>, which sets the base
     #   Encoding for the output. This method will try to guess your Encoding from
@@ -1326,7 +1442,7 @@ class CSV
     #   CSV.generate_line(:foo)
     #
     def generate_line(row, **options)
-      options = {row_sep: $INPUT_RECORD_SEPARATOR}.merge(options)
+      options = {row_sep: InputRecordSeparator.value}.merge(options)
       str = +""
       if options[:encoding]
         str.force_encoding(options[:encoding])
@@ -1356,7 +1472,7 @@ class CSV
     #   open(io, mode = "rb", **options ) { |csv| ... } -> object
     #
     # possible options elements:
-    #   hash form:
+    #   keyword form:
     #     :invalid => nil      # raise error on invalid byte sequence (default)
     #     :invalid => :replace # replace invalid byte sequence
     #     :undef => :replace   # replace undefined conversion
@@ -1423,10 +1539,14 @@ class CSV
     def open(filename, mode="r", **options)
       # wrap a File opened with the remaining +args+ with no newline
       # decorator
-      file_opts = {universal_newline: false}.merge(options)
+      file_opts = options.dup
+      unless file_opts.key?(:newline)
+        file_opts[:universal_newline] ||= false
+      end
       options.delete(:invalid)
       options.delete(:undef)
       options.delete(:replace)
+      options.delete_if {|k, _| /newline\z/.match?(k)}
 
       begin
         f = File.open(filename, mode, **file_opts)
@@ -1681,7 +1801,7 @@ class CSV
     #
     # Calls CSV.read with +source+, +options+, and certain default options:
     # - +headers+: +true+
-    # - +converbers+: +:numeric+
+    # - +converters+: +:numeric+
     # - +header_converters+: +:symbol+
     #
     # Returns a CSV::Table object.
@@ -1760,11 +1880,11 @@ class CSV
                  encoding: nil,
                  nil_value: nil,
                  empty_value: "",
+                 strip: false,
                  quote_empty: true,
                  write_converters: nil,
                  write_nil_value: nil,
-                 write_empty_value: "",
-                 strip: false)
+                 write_empty_value: "")
     raise ArgumentError.new("Cannot parse nil as CSV") if data.nil?
 
     if data.is_a?(String)
@@ -1884,6 +2004,10 @@ class CSV
   #   csv.converters # => [:integer]
   #   csv.convert(proc {|x| x.to_s })
   #   csv.converters
+  #
+  # Notes that you need to call
+  # +Ractor.make_shareable(CSV::Converters)+ on the main Ractor to use
+  # this method.
   def converters
     parser_fields_converter.map do |converter|
       name = Converters.rassoc(converter)
@@ -1946,6 +2070,10 @@ class CSV
   # Returns an \Array containing header converters; used for parsing;
   # see {Header Converters}[#class-CSV-label-Header+Converters]:
   #   CSV.new('').header_converters # => []
+  #
+  # Notes that you need to call
+  # +Ractor.make_shareable(CSV::HeaderConverters)+ on the main Ractor
+  # to use this method.
   def header_converters
     header_fields_converter.map do |converter|
       name = HeaderConverters.rassoc(converter)
@@ -1985,7 +2113,7 @@ class CSV
   end
 
   # :call-seq:
-  #   csv.encoding -> endcoding
+  #   csv.encoding -> encoding
   #
   # Returns the encoding used for parsing and generating;
   # see {Character Encodings (M17n or Multilingualization)}[#class-CSV-label-Character+Encodings+-28M17n+or+Multilingualization-29]:
@@ -2586,7 +2714,7 @@ class CSV
 
   def build_parser_fields_converter
     specific_options = {
-      builtin_converters: Converters,
+      builtin_converters_name: :Converters,
     }
     options = @base_fields_converter_options.merge(specific_options)
     build_fields_converter(@initial_converters, options)
@@ -2598,7 +2726,7 @@ class CSV
 
   def build_header_fields_converter
     specific_options = {
-      builtin_converters: HeaderConverters,
+      builtin_converters_name: :HeaderConverters,
       accept_nil: true,
     }
     options = @base_fields_converter_options.merge(specific_options)
@@ -2661,8 +2789,15 @@ end
 #     c.read.any? { |a| a.include?("zombies") }
 #   } #=> false
 #
-def CSV(*args, &block)
-  CSV.instance(*args, &block)
+# CSV options may also be given.
+#
+#   io = StringIO.new
+#   CSV(io, col_sep: ";") { |csv| csv << ["a", "b", "c"] }
+#
+# This API is not Ractor-safe.
+#
+def CSV(*args, **options, &block)
+  CSV.instance(*args, **options, &block)
 end
 
 require_relative "csv/version"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: csv
 version: !ruby/object:Gem::Version
-  version: 3.1.8
+  version: 3.2.2
 platform: ruby
 authors:
 - James Edward Gray II
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-11-17 00:00:00.000000000 Z
+date: 2021-12-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -54,19 +54,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: simplecov
+  name: test-unit
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.4.8
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.4.8
 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.
@@ -118,6 +118,7 @@ files:
 - lib/csv/core_ext/string.rb
 - lib/csv/delete_suffix.rb
 - lib/csv/fields_converter.rb
+- lib/csv/input_record_separator.rb
 - lib/csv/match_p.rb
 - lib/csv/parser.rb
 - lib/csv/row.rb
@@ -126,6 +127,7 @@ files:
 - lib/csv/writer.rb
 homepage: https://github.com/ruby/csv
 licenses:
+- Ruby
 - BSD-2-Clause
 metadata: {}
 post_install_message: 
@@ -145,7 +147,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.0.rc.2
+rubygems_version: 3.3.0
 signing_key: 
 specification_version: 4
 summary: CSV Reading and Writing