smarter_csv 1.16.2 → 1.16.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d4cf6c7123e6048cb2c8de80ad92625a9985954e4308084f0a5b86cae4df03c
-  data.tar.gz: 5bd6237f017a8d4c54e4ee9ce6f9c3863d65d744c49ed1d6409c78c07f84ec88
+  metadata.gz: b40fb76fef88599d7449691806af6f76a131ffcd41e2ee145d5c87f3554a2006
+  data.tar.gz: edb27057973c0a88524579f450dc8ed3ffadbd983de7155a84ff159495c31233
 SHA512:
-  metadata.gz: 25259d4b0b4edfe05c8e5d83e5ba691f6c82effaacc3a2cb9b78490f89b1e7a132ae70c8d1ea32731d1c3cce1f62e1dd98d05ae23576cc9872bd1ff4ac635ea3
-  data.tar.gz: 045fae96155913ff53c7661c7b4fe59946a792b72ff833eb723b49138406f30b3d6763e196c2cb6d5286ce014dc3d07f7bda94434a58857701b97d24a407fb4f
+  metadata.gz: 5b9e2a17ae14a5d7b3dfddd854148f38c8892d67544b51fecba888aa11c540096057460880564b89251194fea513c3e2807c500d93f896826db885daf64271fe
+  data.tar.gz: 90b5aa10c6bc36cbc97662de879deaf61c2417a61e4cb5171924aac991a37c762588ff6413a924bfd083ca10c1fa1739049561f3c6e9de6ff196bdba85c7878f

data/CHANGELOG.md

@@ -1,6 +1,20 @@
 
 # SmarterCSV 1.x Change Log
 
+## 1.16.3 (2026-04-14) — New Feature
+
+RSpec tests: **1,425 → 1,434** (+9 tests)
+
+### New Features
+
+* **`write_headers: false`** — new `SmarterCSV::Writer` option to suppress the header line when appending rows to an existing CSV file opened in `'a'` mode.
+  Defaults to `true` (existing behavior, fully backwards-compatible).
+  
+  See [Appending to an Existing CSV File](docs/basic_write_api.md#appending-to-an-existing-csv-file).
+
+### Other
+* Refactor of internal options handling
+
 ## 1.16.2 (2026-03-30) — Bug Fixes
 
 RSpec tests: **1,410 → 1,425** (+15 tests)

data/docs/basic_write_api.md

@@ -568,6 +568,54 @@ end
 > **Note:** Only use `write_bom: true` with UTF-8 output. Adding a UTF-8 BOM to a
 > non-UTF-8 file will corrupt it.
 
+## Appending to an Existing CSV File
+
+Use `write_headers: false` to suppress the header line when appending rows to an
+existing CSV file. The caller is responsible for opening the file in append mode — the
+Writer writes only what you ask it to write.
+
+```ruby
+# First write: create the file with header + first batch of rows
+SmarterCSV.generate('output.csv') do |csv|
+  csv << { name: 'Alice', age: 30 }
+end
+# output.csv:
+# name,age
+# Alice,30
+
+# Later: append more rows without repeating the header
+File.open('output.csv', 'a') do |f|
+  SmarterCSV.generate(f, write_headers: false) do |csv|
+    csv << { name: 'Bob', age: 25 }
+  end
+end
+# output.csv:
+# name,age
+# Alice,30
+# Bob,25
+```
+
+The Writer still uses the hash keys to determine column order, so the appended rows
+will be aligned correctly as long as the same set of keys is used. If you need to
+guarantee column order across both writes, pass `headers:` explicitly:
+
+```ruby
+HEADERS = %i[name age]
+
+SmarterCSV.generate('output.csv', headers: HEADERS) do |csv|
+  csv << { name: 'Alice', age: 30 }
+end
+
+File.open('output.csv', 'a') do |f|
+  SmarterCSV.generate(f, headers: HEADERS, write_headers: false) do |csv|
+    csv << { name: 'Bob', age: 25 }
+  end
+end
+```
+
+> **Note:** `write_headers: false` only suppresses the header line. All other
+> options (`col_sep:`, `row_sep:`, `value_converters:`, etc.) apply as normal.
+
 ## More Examples
 
 Check out the [RSpec tests](../spec/smarter_csv/writer_spec.rb) for more examples.

data/docs/options.md

@@ -45,6 +45,7 @@
 | `:write_nil_value` | `''` | String written in place of `nil` field values. E.g. `write_nil_value: 'N/A'`. |
 | `:write_empty_value` | `''` | String written in place of empty-string field values, including missing keys. E.g. `write_empty_value: 'EMPTY'`. |
 | `:write_bom` | `false` | Prepends a UTF-8 BOM (`\xEF\xBB\xBF`) to the output. Use with `encoding: 'UTF-8'` for Excel compatibility. |
+| `:write_headers` | `true` | When `false`, suppresses the header line entirely. Use when appending rows to an existing CSV file (open the file in `'a'` mode yourself and pass the IO object). |
 
 
 ## CSV Reading

data/ext/smarter_csv/Makefile

@@ -13,12 +13,12 @@ NULLCMD = :
 #### Start of system configuration section. ####
 
 srcdir = .
-topdir = /Users/tilo/.rvm/rubies/ruby-3.4.7/include/ruby-3.4.0
+topdir = /Users/tilo/.rvm/rubies/ruby-3.2.2/include/ruby-3.2.0
 hdrdir = $(topdir)
-arch_hdrdir = /Users/tilo/.rvm/rubies/ruby-3.4.7/include/ruby-3.4.0/arm64-darwin25
+arch_hdrdir = /Users/tilo/.rvm/rubies/ruby-3.2.2/include/ruby-3.2.0/arm64-darwin23
 PATH_SEPARATOR = :
 VPATH = $(srcdir):$(arch_hdrdir)/ruby:$(hdrdir)/ruby
-prefix = $(DESTDIR)/Users/tilo/.rvm/rubies/ruby-3.4.7
+prefix = $(DESTDIR)/Users/tilo/.rvm/rubies/ruby-3.2.2
 rubysitearchprefix = $(rubylibprefix)/$(sitearch)
 rubyarchprefix = $(rubylibprefix)/$(arch)
 rubylibprefix = $(libdir)/$(RUBY_BASE_NAME)
@@ -42,7 +42,6 @@ archincludedir = $(includedir)/$(arch)
 sitearchlibdir = $(libdir)/$(sitearch)
 archlibdir = $(libdir)/$(arch)
 ridir = $(datarootdir)/$(RI_BASE_NAME)
-modular_gc_dir = $(DESTDIR)
 mandir = $(datarootdir)/man
 localedir = $(datarootdir)/locale
 libdir = $(exec_prefix)/lib
@@ -79,11 +78,11 @@ COUTFLAG = -o $(empty)
 CSRCFLAG = $(empty)
 
 RUBY_EXTCONF_H = 
-cflags   = $(hardenflags) -fdeclspec  $(optflags) $(debugflags) $(warnflags)
+cflags   = -fdeclspec $(optflags) $(debugflags) $(warnflags)
 cxxflags = 
-optflags = -O3 -march=native -flto -fomit-frame-pointer -DNDEBUG
-debugflags = 
-warnflags = -Wall -Wextra -Wextra-tokens -Wdeprecated-declarations -Wdivision-by-zero -Wdiv-by-zero -Wimplicit-function-declaration -Wimplicit-int -Wpointer-arith -Wshorten-64-to-32 -Wwrite-strings -Wold-style-definition -Wmissing-noreturn -Wno-cast-function-type -Wno-constant-logical-operand -Wno-long-long -Wno-missing-field-initializers -Wno-overlength-strings -Wno-parentheses-equality -Wno-self-assign -Wno-tautological-compare -Wno-unused-parameter -Wno-unused-value -Wunused-variable -Wmisleading-indentation -Wundef
+optflags = -O3
+debugflags = -ggdb3
+warnflags = -Wall -Wextra -Wextra-tokens -Wdeprecated-declarations -Wdivision-by-zero -Wdiv-by-zero -Wimplicit-function-declaration -Wimplicit-int -Wmisleading-indentation -Wpointer-arith -Wshorten-64-to-32 -Wwrite-strings -Wold-style-definition -Wmissing-noreturn -Wno-cast-function-type -Wno-constant-logical-operand -Wno-long-long -Wno-missing-field-initializers -Wno-overlength-strings -Wno-parentheses-equality -Wno-self-assign -Wno-tautological-compare -Wno-unused-parameter -Wno-unused-value -Wunused-variable -Wundef
 cppflags = 
 CCDLFLAGS = -fno-common
 CFLAGS   = $(CCDLFLAGS) -O3 -I/opt/homebrew/opt/libyaml/include -I/opt/homebrew/opt/libksba/include -I/opt/homebrew/opt/readline/include -I/opt/homebrew/opt/zlib/include -I/opt/homebrew/opt/openssl@1.1/include $(cflags) -fno-common -pipe $(ARCH_FLAG)
@@ -92,26 +91,24 @@ DEFS     =
 CPPFLAGS =  -D_XOPEN_SOURCE -D_DARWIN_C_SOURCE -D_DARWIN_UNLIMITED_SELECT -D_REENTRANT $(DEFS) $(cppflags)
 CXXFLAGS = $(CCDLFLAGS) -fdeclspec $(ARCH_FLAG)
 ldflags  = -L. -L/opt/homebrew/opt/libyaml/lib -L/opt/homebrew/opt/libksba/lib -L/opt/homebrew/opt/readline/lib -L/opt/homebrew/opt/zlib/lib -L/opt/homebrew/opt/openssl@1.1/lib -fstack-protector-strong
-dldflags = -L/opt/homebrew/opt/libyaml/lib -L/opt/homebrew/opt/libksba/lib -L/opt/homebrew/opt/readline/lib -L/opt/homebrew/opt/zlib/lib -L/opt/homebrew/opt/openssl@1.1/lib -Wl,-undefined,dynamic_lookup 
-ARCH_FLAG = -arch arm64
+dldflags = -L/opt/homebrew/opt/libyaml/lib -L/opt/homebrew/opt/libksba/lib -L/opt/homebrew/opt/readline/lib -L/opt/homebrew/opt/zlib/lib -L/opt/homebrew/opt/openssl@1.1/lib -Wl,-undefined,dynamic_lookup $(LIBRUBYARG_SHARED)
+ARCH_FLAG = 
 DLDFLAGS = $(ldflags) $(dldflags) $(ARCH_FLAG)
 LDSHARED = $(CC) -dynamic -bundle
 LDSHAREDXX = $(CXX) -dynamic -bundle
-POSTLINK = dsymutil $@ 2>/dev/null; { test -z '$(RUBY_CODESIGN)' || codesign -s '$(RUBY_CODESIGN)' $@; }
 AR = ar
-LD = ld
 EXEEXT = 
 
 RUBY_INSTALL_NAME = $(RUBY_BASE_NAME)
-RUBY_SO_NAME = ruby.3.4
+RUBY_SO_NAME = ruby.3.2
 RUBYW_INSTALL_NAME = 
 RUBY_VERSION_NAME = $(RUBY_BASE_NAME)-$(ruby_version)
 RUBYW_BASE_NAME = rubyw
 RUBY_BASE_NAME = ruby
 
-arch = arm64-darwin25
+arch = arm64-darwin23
 sitearch = $(arch)
-ruby_version = 3.4.0
+ruby_version = 3.2.0
 ruby = $(bindir)/$(RUBY_BASE_NAME)
 RUBY = $(ruby)
 BUILTRUBY = $(bindir)/$(RUBY_BASE_NAME)
@@ -131,7 +128,7 @@ TOUCH = exit >
 
 preload = 
 libpath = . $(libdir)
-LIBPATH = -L. -L$(libdir)
+LIBPATH =  -L. -L$(libdir)
 DEFFILE = 
 
 CLEANFILES = mkmf.log
@@ -164,7 +161,7 @@ HDRDIR        = $(sitehdrdir)$(target_prefix)
 ARCHHDRDIR    = $(sitearchhdrdir)$(target_prefix)
 TARGET_SO_DIR =
 TARGET_SO     = $(TARGET_SO_DIR)$(DLLIB)
-CLEANLIBS     = $(TARGET_SO) $(TARGET_SO:=.dSYM)
+CLEANLIBS     = $(TARGET_SO) $(TARGET_SO).dSYM
 CLEANOBJS     = $(OBJS) *.bak
 TARGET_SO_DIR_TIMESTAMP = $(TIMESTAMP_DIR)/.sitearchdir.-.smarter_csv.time
 

data/lib/smarter_csv/reader.rb

@@ -10,7 +10,7 @@ module SmarterCSV
     # A warning is emitted to STDERR so users know to configure it explicitly.
     DEFAULT_CHUNK_SIZE = 100
 
-    include ::SmarterCSV::Options
+    include ::SmarterCSV::Reader::Options
     include ::SmarterCSV::FileIO
     include ::SmarterCSV::AutoDetection
     include ::SmarterCSV::Headers
@@ -24,6 +24,10 @@ module SmarterCSV
     attr_reader :enforce_utf8, :has_rails, :has_acceleration
     attr_reader :errors, :warnings, :headers, :raw_header, :result
 
+    def self.default_options
+      Options::DEFAULT_OPTIONS
+    end
+
     # rubocop:disable Naming/MethodName
     def headerA
       warn "Deprecarion Warning: 'headerA' will be removed in future versions. Use 'headders'"

data/lib/smarter_csv/reader_options.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module SmarterCSV
+  class Reader
+    module Options
+      DEFAULT_OPTIONS = {
+        acceleration: true, # if user wants to use accelleration or not
+        auto_row_sep_chars: 500,
+        bad_row_limit: nil,
+        chunk_size: nil,
+        col_sep: :auto, # was: ',',
+        collect_raw_lines: true,
+        comment_regexp: nil, # was: /\A#/,
+        convert_values_to_numeric: true,
+        downcase_header: true,
+        duplicate_header_suffix: '', # was: nil,
+        field_size_limit: nil, # Integer (bytes) or nil for no limit. Raises FieldSizeLimitExceeded if any
+        #                          extracted field exceeds this size. Prevents DoS from runaway quoted
+        #                          fields (unbounded multiline stitching) or huge inline payloads.
+        file_encoding: 'utf-8',
+        force_utf8: false,
+        headers_in_file: true,
+        invalid_byte_sequence: '',
+        keep_original_headers: false,
+        key_mapping: nil,
+        strict: false,              # DEPRECATED -> use missing_headers
+        missing_headers: :auto,     # :auto (auto-generate names for extra cols) or :raise (raise HeaderSizeMismatch)
+        missing_header_prefix: 'column_',
+        nil_values_matching: nil,   # regex: set matching values to nil (key kept); pairs with remove_empty_values
+        on_bad_row: :raise,
+        on_chunk: nil,    # callable: fired after each chunk is parsed, before yielding to the block
+        on_complete: nil, # callable: fired once after the entire file is processed
+        on_start: nil,    # callable: fired once before the first row is parsed
+        quote_boundary: :standard, # :standard (only at field boundary 👍) or :legacy (any quote toggles state 👎)
+        quote_char: '"',
+        quote_escaping: :auto,
+        remove_empty_hashes: true,
+        remove_empty_values: true,
+        remove_unmapped_keys: false,
+        remove_values_matching: nil, # DEPRECATED: use nil_values_matching instead
+        remove_zero_values: false,
+        required_headers: nil,
+        required_keys: nil,
+        row_sep: :auto, # was: $/,
+        silence_missing_keys: false,
+        skip_lines: nil,
+        strings_as_keys: false,
+        strip_chars_from_headers: nil,
+        strip_whitespace: true,
+        user_provided_headers: nil,
+        value_converters: nil,
+        verbose: :normal, # nil/:normal (default), :quiet (suppress warnings), :debug (print diagnostics); true/false are deprecated
+        with_line_numbers: false,
+      }.freeze
+
+      # NOTE: this is not called when "parse" methods are tested by themselves
+      def process_options(given_options = {})
+        # Debug output before merge — check raw verbose value (true or :debug)
+        $stderr.puts "User provided options:\n#{pp(given_options)}\n" if [true, :debug].include?(given_options[:verbose])
+
+        # Special case for :user_provided_headers:
+        #
+        # If we would use the default `headers_in_file: true`, and `:user_provided_headers` are given,
+        # we could lose the first data row
+        #
+        # We now err on the side of treating an actual header as data, rather than losing a data row.
+        #
+        if given_options[:user_provided_headers] && !given_options.keys.include?(:headers_in_file)
+          given_options[:headers_in_file] = false
+          warn "WARNING: setting `headers_in_file: false` as a precaution to not lose the first row. Set explicitly to `true` if you have headers." unless given_options[:verbose] == :quiet
+        end
+
+        @options = DEFAULT_OPTIONS.dup.merge!(given_options)
+
+        # Normalize verbose to a symbol — done once here, stored back into @options.
+        # All subsequent checks are free symbol comparisons; no re-evaluation needed.
+        #   :quiet  — suppress all warnings and notices (good for production)
+        #   :normal — show behavioral warnings (default; helpful for new users)
+        #   :debug  — :normal + print computed options and per-row diagnostics
+        # nil is silently normalized to :normal; true/false are deprecated.
+        case @options[:verbose]
+        when :quiet, :normal, :debug
+          # keep as is
+        when nil
+          @options[:verbose] = :normal
+        when false
+          warn "DEPRECATION WARNING: verbose: false is deprecated. Use verbose: :normal instead (or omit — it is the default)."
+          @options[:verbose] = :normal
+        when true
+          warn "DEPRECATION WARNING: verbose: true is deprecated. Use verbose: :debug instead."
+          @options[:verbose] = :debug
+        else
+          warn "WARNING: unknown verbose value #{@options[:verbose].inspect}, defaulting to :normal. Valid values: :quiet, :normal, :debug."
+          @options[:verbose] = :normal
+        end
+
+        # fix invalid input
+        @options[:invalid_byte_sequence] ||= ''
+
+        # Normalize headers: { only: [...] } / { except: [...] } to internal option names.
+        # The public API is headers: { only: } or headers: { except: }.
+        # Internally we use only_headers: / except_headers: (what the C extension reads).
+        if (hdr = @options.delete(:headers)).is_a?(Hash)
+          @options[:only_headers]   = hdr[:only]   if hdr.key?(:only)
+          @options[:except_headers] = hdr[:except] if hdr.key?(:except)
+        end
+
+        # Deprecation: direct use of only_headers: / except_headers: (use headers: { only: } instead)
+        if given_options.key?(:only_headers) && !given_options.key?(:headers)
+          warn "DEPRECATION WARNING: 'only_headers:' is deprecated. Use 'headers: { only: [...] }' instead." unless @options[:verbose] == :quiet
+        end
+        if given_options.key?(:except_headers) && !given_options.key?(:headers)
+          warn "DEPRECATION WARNING: 'except_headers:' is deprecated. Use 'headers: { except: [...] }' instead." unless @options[:verbose] == :quiet
+        end
+
+        # Normalize only_headers/except_headers to arrays of symbols (internal names, read by C extension)
+        if @options[:only_headers]
+          values = Array(@options[:only_headers])
+          bad = values.reject { |v| v.is_a?(Symbol) || v.is_a?(String) }
+          raise SmarterCSV::ValidationError, "headers: { only: } elements must be String or Symbol, got: #{bad.map(&:class).uniq.inspect}" if bad.any?
+          @options[:only_headers] = values.map(&:to_sym)
+        end
+        if @options[:except_headers]
+          values = Array(@options[:except_headers])
+          bad = values.reject { |v| v.is_a?(Symbol) || v.is_a?(String) }
+          raise SmarterCSV::ValidationError, "headers: { except: } elements must be String or Symbol, got: #{bad.map(&:class).uniq.inspect}" if bad.any?
+          @options[:except_headers] = values.map(&:to_sym)
+        end
+
+        # Deprecation: remove_values_matching → nil_values_matching
+        # Old behavior: removes the key-value pair entirely.
+        # New behavior: nil_values_matching sets the value to nil (key kept);
+        # combined with the default remove_empty_values: true the net effect is identical.
+        # With remove_empty_values: false, the key is retained with a nil value.
+        if given_options.key?(:remove_values_matching)
+          unless @options[:verbose] == :quiet
+            warn "DEPRECATION WARNING: 'remove_values_matching' is deprecated. " \
+                 "Use 'nil_values_matching' instead. With the default 'remove_empty_values: true' " \
+                 "the net behavior is identical. With 'remove_empty_values: false', matching values " \
+                 "are set to nil but the key is retained in the result hash."
+          end
+          @options[:nil_values_matching] ||= @options[:remove_values_matching]
+          @options[:remove_values_matching] = nil # clear to prevent double-processing
+        end
+
+        # Translate deprecated :strict option to :missing_headers
+        if given_options.key?(:strict)
+          unless @options[:verbose] == :quiet
+            warn "DEPRECATION WARNING: 'strict' option is deprecated and will be removed in a future version. " \
+                 "Use 'missing_headers: :raise' instead of 'strict: true', or 'missing_headers: :auto' instead of 'strict: false'."
+          end
+          @options[:missing_headers] = @options[:strict] ? :raise : :auto unless given_options.key?(:missing_headers)
+        end
+
+        # Keep :strict synchronized with :missing_headers (C extension reads :strict directly)
+        @options[:strict] = (@options[:missing_headers] == :raise)
+
+        $stderr.puts "Computed options:\n#{pp(@options)}\n" if @options[:verbose] == :debug
+
+        validate_options!(@options)
+        @options
+      end
+
+      private
+
+      def validate_options!(options)
+        # deprecate required_headers
+        unless options[:required_headers].nil?
+          warn "DEPRECATION WARNING: please use 'required_keys' instead of 'required_headers'" unless options[:verbose] == :quiet
+          if options[:required_keys].nil?
+            options[:required_keys] = options[:required_headers]
+            options[:required_headers] = nil
+          end
+        end
+
+        keys = options.keys
+        errors = []
+        errors << "invalid row_sep" if keys.include?(:row_sep) && !option_valid?(options[:row_sep])
+        errors << "invalid col_sep" if keys.include?(:col_sep) && !option_valid?(options[:col_sep])
+        errors << "invalid quote_char" if keys.include?(:quote_char) && !option_valid?(options[:quote_char])
+        if keys.include?(:quote_char) && options[:quote_char].is_a?(String) && options[:quote_char].bytesize > 1
+          errors << "invalid quote_char: must be a single byte (got #{options[:quote_char].inspect})"
+        end
+        unless %i[double_quotes backslash auto].include?(options[:quote_escaping])
+          errors << "invalid quote_escaping: must be :double_quotes, :backslash, or :auto"
+        end
+        unless %i[legacy standard].include?(options[:quote_boundary])
+          errors << "invalid quote_boundary: must be :legacy or :standard"
+        end
+        fsl = options[:field_size_limit]
+        unless fsl.nil? || (fsl.is_a?(Integer) && fsl > 0)
+          errors << "invalid field_size_limit: must be nil or a positive Integer (got #{fsl.inspect})"
+        end
+        obr = options[:on_bad_row]
+        unless %i[raise skip collect].include?(obr) || obr.respond_to?(:call)
+          errors << "invalid on_bad_row: must be :raise, :skip, :collect, or a callable"
+        end
+        %i[on_start on_chunk on_complete].each do |hook|
+          val = options[hook]
+          errors << "invalid #{hook}: must be nil or a callable" if !val.nil? && !val.respond_to?(:call)
+        end
+        unless %i[auto raise].include?(options[:missing_headers])
+          errors << "invalid missing_headers: must be :auto or :raise"
+        end
+        if options[:only_headers] && options[:except_headers]
+          errors << "cannot use both 'headers: { only: }' and 'headers: { except: }' at the same time"
+        end
+        raise SmarterCSV::ValidationError, errors.inspect if errors.any?
+      end
+
+      def option_valid?(str)
+        return true if str.is_a?(Symbol) && str == :auto
+        return true if str.is_a?(String) && !str.empty?
+
+        false
+      end
+
+      def pp(value)
+        defined?(AwesomePrint) ? value.awesome_inspect(index: nil) : value.inspect
+      end
+    end
+  end
+end

data/lib/smarter_csv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SmarterCSV
-  VERSION = "1.16.2"
+  VERSION = "1.16.3"
 end

data/lib/smarter_csv/writer.rb

@@ -25,6 +25,8 @@ module SmarterCSV
   #
   # The Writer automatically quotes fields containing the col_sep, row_sep, or the quote_char.
   #
+  # See SmarterCSV::Writer::Options::DEFAULT_OPTIONS for all options and their defaults.
+  #
   # Options:
   #   col_sep : defaults to , but can be set to any other character
   #   row_sep : defaults to LF \n , but can be set to \r\n or \r or anything else
@@ -42,7 +44,9 @@ module SmarterCSV
   #   write_empty_value: string written in place of empty-string field values (default: '')
   #   write_bom: when true, prepends a UTF-8 BOM (\xEF\xBB\xBF) to the output (default: false)
   #              Useful for Excel compatibility with non-ASCII content.
-
+  #   write_headers: when false, suppresses the header line (default: true). Useful when appending to
+  #                  an existing CSV file opened in 'a' mode — the caller controls the file mode.
+  #
   # IMPORTANT NOTES:
   #  * Data hashes could contain strings or symbols as keys.
   #    Make sure to use the correct form when specifying headers manually,
@@ -51,36 +55,42 @@ module SmarterCSV
   attr_reader :options, :row_sep, :col_sep, :quote_char, :force_quotes, :discover_headers, :headers, :map_headers, :output_file
 
   class Writer
-    def initialize(file_path_or_io, options = {})
-      @options = options
+    include ::SmarterCSV::Writer::Options
+
+    def self.default_options
+      Options::DEFAULT_OPTIONS
+    end
+
+    def initialize(file_path_or_io, given_options = {})
+      opts = Options::DEFAULT_OPTIONS.merge(given_options)
+      @options = opts
 
-      @row_sep = options[:row_sep] || $/
-      @col_sep = options[:col_sep] || ','
-      @quote_char = options[:quote_char] || '"'
+      @row_sep = opts[:row_sep]
+      @col_sep = opts[:col_sep]
+      @quote_char = opts[:quote_char]
       @escaped_quote_char = @quote_char * 2
-      @force_quotes = options[:force_quotes] == true
-      @quote_headers = options[:quote_headers] == true
-      @disable_auto_quoting = options[:disable_auto_quoting] == true
-      @value_converters = options[:value_converters] || {}
-      @encoding = options[:encoding]
-      @write_nil_value = options.fetch(:write_nil_value, '')
-      @write_empty_value = options.fetch(:write_empty_value, '')
-      @write_bom = options[:write_bom] == true
+      @force_quotes = opts[:force_quotes] == true
+      @quote_headers = opts[:quote_headers] == true
+      @disable_auto_quoting = opts[:disable_auto_quoting] == true
+      @value_converters = opts[:value_converters] || {}
+      @encoding = opts[:encoding]
+      @write_nil_value = opts[:write_nil_value]
+      @write_empty_value = opts[:write_empty_value]
+      @write_bom = opts[:write_bom] == true
+      @write_headers = opts[:write_headers] == true
       @map_all_keys = @value_converters.has_key?(:_all)
       @mapped_keys = Set.new(@value_converters.keys - [:_all])
-      @header_converter = options[:header_converter]
+      @header_converter = opts[:header_converter]
 
-      @discover_headers = true
-      if options.has_key?(:discover_headers)
-        @discover_headers = options[:discover_headers] == true
+      if given_options.has_key?(:discover_headers)
+        @discover_headers = given_options[:discover_headers] == true
       else
-        @discover_headers = !(options.has_key?(:map_headers) || options.has_key?(:headers))
+        @discover_headers = !(given_options.has_key?(:map_headers) || given_options.has_key?(:headers))
       end
 
-      @headers = []
-      @headers = options[:headers] if options.has_key?(:headers)
-      @headers = options[:map_headers].keys if options.has_key?(:map_headers) && !options.has_key?(:headers)
-      @map_headers = options[:map_headers] || {}
+      @headers = opts[:headers].dup
+      @headers = given_options[:map_headers].keys if given_options.has_key?(:map_headers) && !given_options.has_key?(:headers)
+      @map_headers = opts[:map_headers]
 
       # Accept an IO-like object (StringIO, IO, etc.) or any path-like object (String, Pathname, etc.)
       if file_path_or_io.respond_to?(:write)
@@ -110,7 +120,7 @@ module SmarterCSV
         # and stream data rows directly to @output_file, bypassing the temp file entirely.
         @temp_file = nil
         @output_file.write("\xEF\xBB\xBF") if @write_bom
-        write_header_line
+        write_header_line if @write_headers
       else
         @temp_file = Tempfile.new('smarter_csv')
       end
@@ -134,7 +144,7 @@ module SmarterCSV
         # Header-discovery mode: headers were accumulated while writing rows;
         # now prepend the header line and copy the buffered rows to the output.
         @output_file.write("\xEF\xBB\xBF") if @write_bom
-        write_header_line
+        write_header_line if @write_headers
         @temp_file.rewind
         @output_file.write(@temp_file.read)
         @temp_file.close!

data/lib/smarter_csv/writer_options.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SmarterCSV
+  class Writer
+    module Options
+      DEFAULT_OPTIONS = {
+        col_sep: ',',
+        row_sep: $/,
+        quote_char: '"',
+        force_quotes: false,
+        quote_headers: false,
+        disable_auto_quoting: false,
+        value_converters: {},
+        encoding: nil,
+        write_nil_value: '',
+        write_empty_value: '',
+        write_bom: false,
+        write_headers: true,
+        header_converter: nil,
+        discover_headers: true,
+        headers: [],
+        map_headers: {},
+      }.freeze
+    end
+  end
+end

data/lib/smarter_csv.rb

@@ -5,7 +5,8 @@ require "smarter_csv/version"
 require "smarter_csv/errors"
 
 require "smarter_csv/file_io"
-require "smarter_csv/options"
+require "smarter_csv/reader_options"
+require "smarter_csv/writer_options"
 require "smarter_csv/auto_detection"
 require 'smarter_csv/header_transformations'
 require 'smarter_csv/header_validations'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: smarter_csv
 version: !ruby/object:Gem::Version
-  version: 1.16.2
+  version: 1.16.3
 platform: ruby
 authors:
 - Tilo Sloboda
 bindir: bin
 cert_chain: []
-date: 2026-03-30 00:00:00.000000000 Z
+date: 2026-04-14 00:00:00.000000000 Z
 dependencies: []
 description: |
   SmarterCSV is a high-performance CSV reader and writer for Ruby focused on
@@ -64,12 +64,7 @@ files:
 - docs/value_converters.md
 - ext/smarter_csv/Makefile
 - ext/smarter_csv/extconf.rb
-- ext/smarter_csv/smarter_csv.bundle
-- ext/smarter_csv/smarter_csv.bundle.dSYM/Contents/Info.plist
-- ext/smarter_csv/smarter_csv.bundle.dSYM/Contents/Resources/DWARF/smarter_csv.bundle
-- ext/smarter_csv/smarter_csv.bundle.dSYM/Contents/Resources/Relocations/aarch64/smarter_csv.bundle.yml
 - ext/smarter_csv/smarter_csv.c
-- ext/smarter_csv/smarter_csv.o
 - images/SmarterCSV_1.16.0_vs_RubyCSV_3.3.5_speedup.png
 - images/SmarterCSV_1.16.0_vs_RubyCSV_3.3.5_speedup.svg
 - images/SmarterCSV_1.16.0_vs_previous_C-speedup.png
@@ -84,11 +79,12 @@ files:
 - lib/smarter_csv/header_transformations.rb
 - lib/smarter_csv/header_validations.rb
 - lib/smarter_csv/headers.rb
-- lib/smarter_csv/options.rb
 - lib/smarter_csv/parser.rb
 - lib/smarter_csv/reader.rb
+- lib/smarter_csv/reader_options.rb
 - lib/smarter_csv/version.rb
 - lib/smarter_csv/writer.rb
+- lib/smarter_csv/writer_options.rb
 - smarter_csv.gemspec
 homepage: https://github.com/tilo/smarter_csv
 licenses:

data/ext/smarter_csv/smarter_csv.bundle.dSYM/Contents/Info.plist

@@ -1,20 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-	<dict>
-		<key>CFBundleDevelopmentRegion</key>
-		<string>English</string>
-		<key>CFBundleIdentifier</key>
-		<string>com.apple.xcode.dsym.smarter_csv.bundle</string>
-		<key>CFBundleInfoDictionaryVersion</key>
-		<string>6.0</string>
-		<key>CFBundlePackageType</key>
-		<string>dSYM</string>
-		<key>CFBundleSignature</key>
-		<string>????</string>
-		<key>CFBundleShortVersionString</key>
-		<string>1.0</string>
-		<key>CFBundleVersion</key>
-		<string>1</string>
-	</dict>
-</plist>

data/ext/smarter_csv/smarter_csv.bundle.dSYM/Contents/Resources/Relocations/aarch64/smarter_csv.bundle.yml

@@ -1,5 +0,0 @@
----
-triple:          'arm64-apple-darwin'
-binary-path:     smarter_csv.bundle
-relocations:     []
-...

data/lib/smarter_csv/options.rb

@@ -1,229 +0,0 @@
-# frozen_string_literal: true
-
-module SmarterCSV
-  #
-  # NOTE: this is not called when "parse" methods are tested by themselves
-  #
-  # ONLY FOR BACKWARDS-COMPATIBILITY
-  def self.default_options
-    Options::DEFAULT_OPTIONS
-  end
-
-  module Options
-    DEFAULT_OPTIONS = {
-      acceleration: true, # if user wants to use accelleration or not
-      auto_row_sep_chars: 500,
-      bad_row_limit: nil,
-      chunk_size: nil,
-      col_sep: :auto, # was: ',',
-      collect_raw_lines: true,
-      comment_regexp: nil, # was: /\A#/,
-      convert_values_to_numeric: true,
-      downcase_header: true,
-      duplicate_header_suffix: '', # was: nil,
-      field_size_limit: nil, # Integer (bytes) or nil for no limit. Raises FieldSizeLimitExceeded if any
-      #                          extracted field exceeds this size. Prevents DoS from runaway quoted
-      #                          fields (unbounded multiline stitching) or huge inline payloads.
-      file_encoding: 'utf-8',
-      force_utf8: false,
-      headers_in_file: true,
-      invalid_byte_sequence: '',
-      keep_original_headers: false,
-      key_mapping: nil,
-      strict: false,              # DEPRECATED -> use missing_headers
-      missing_headers: :auto,     # :auto (auto-generate names for extra cols) or :raise (raise HeaderSizeMismatch)
-      missing_header_prefix: 'column_',
-      nil_values_matching: nil,   # regex: set matching values to nil (key kept); pairs with remove_empty_values
-      on_bad_row: :raise,
-      on_chunk: nil,    # callable: fired after each chunk is parsed, before yielding to the block
-      on_complete: nil, # callable: fired once after the entire file is processed
-      on_start: nil,    # callable: fired once before the first row is parsed
-      quote_boundary: :standard, # :standard (only at field boundary 👍) or :legacy (any quote toggles state 👎)
-      quote_char: '"',
-      quote_escaping: :auto,
-      remove_empty_hashes: true,
-      remove_empty_values: true,
-      remove_unmapped_keys: false,
-      remove_values_matching: nil, # DEPRECATED: use nil_values_matching instead
-      remove_zero_values: false,
-      required_headers: nil,
-      required_keys: nil,
-      row_sep: :auto, # was: $/,
-      silence_missing_keys: false,
-      skip_lines: nil,
-      strings_as_keys: false,
-      strip_chars_from_headers: nil,
-      strip_whitespace: true,
-      user_provided_headers: nil,
-      value_converters: nil,
-      verbose: :normal, # nil/:normal (default), :quiet (suppress warnings), :debug (print diagnostics); true/false are deprecated
-      with_line_numbers: false,
-    }.freeze
-
-    # NOTE: this is not called when "parse" methods are tested by themselves
-    def process_options(given_options = {})
-      # Debug output before merge — check raw verbose value (true or :debug)
-      $stderr.puts "User provided options:\n#{pp(given_options)}\n" if [true, :debug].include?(given_options[:verbose])
-
-      # Special case for :user_provided_headers:
-      #
-      # If we would use the default `headers_in_file: true`, and `:user_provided_headers` are given,
-      # we could lose the first data row
-      #
-      # We now err on the side of treating an actual header as data, rather than losing a data row.
-      #
-      if given_options[:user_provided_headers] && !given_options.keys.include?(:headers_in_file)
-        given_options[:headers_in_file] = false
-        warn "WARNING: setting `headers_in_file: false` as a precaution to not lose the first row. Set explicitly to `true` if you have headers." unless given_options[:verbose] == :quiet
-      end
-
-      @options = DEFAULT_OPTIONS.dup.merge!(given_options)
-
-      # Normalize verbose to a symbol — done once here, stored back into @options.
-      # All subsequent checks are free symbol comparisons; no re-evaluation needed.
-      #   :quiet  — suppress all warnings and notices (good for production)
-      #   :normal — show behavioral warnings (default; helpful for new users)
-      #   :debug  — :normal + print computed options and per-row diagnostics
-      # nil is silently normalized to :normal; true/false are deprecated.
-      case @options[:verbose]
-      when :quiet, :normal, :debug
-        # keep as is
-      when nil
-        @options[:verbose] = :normal
-      when false
-        warn "DEPRECATION WARNING: verbose: false is deprecated. Use verbose: :normal instead (or omit — it is the default)."
-        @options[:verbose] = :normal
-      when true
-        warn "DEPRECATION WARNING: verbose: true is deprecated. Use verbose: :debug instead."
-        @options[:verbose] = :debug
-      else
-        warn "WARNING: unknown verbose value #{@options[:verbose].inspect}, defaulting to :normal. Valid values: :quiet, :normal, :debug."
-        @options[:verbose] = :normal
-      end
-
-      # fix invalid input
-      @options[:invalid_byte_sequence] ||= ''
-
-      # Normalize headers: { only: [...] } / { except: [...] } to internal option names.
-      # The public API is headers: { only: } or headers: { except: }.
-      # Internally we use only_headers: / except_headers: (what the C extension reads).
-      if (hdr = @options.delete(:headers)).is_a?(Hash)
-        @options[:only_headers]   = hdr[:only]   if hdr.key?(:only)
-        @options[:except_headers] = hdr[:except] if hdr.key?(:except)
-      end
-
-      # Deprecation: direct use of only_headers: / except_headers: (use headers: { only: } instead)
-      if given_options.key?(:only_headers) && !given_options.key?(:headers)
-        warn "DEPRECATION WARNING: 'only_headers:' is deprecated. Use 'headers: { only: [...] }' instead." unless @options[:verbose] == :quiet
-      end
-      if given_options.key?(:except_headers) && !given_options.key?(:headers)
-        warn "DEPRECATION WARNING: 'except_headers:' is deprecated. Use 'headers: { except: [...] }' instead." unless @options[:verbose] == :quiet
-      end
-
-      # Normalize only_headers/except_headers to arrays of symbols (internal names, read by C extension)
-      if @options[:only_headers]
-        values = Array(@options[:only_headers])
-        bad = values.reject { |v| v.is_a?(Symbol) || v.is_a?(String) }
-        raise SmarterCSV::ValidationError, "headers: { only: } elements must be String or Symbol, got: #{bad.map(&:class).uniq.inspect}" if bad.any?
-        @options[:only_headers] = values.map(&:to_sym)
-      end
-      if @options[:except_headers]
-        values = Array(@options[:except_headers])
-        bad = values.reject { |v| v.is_a?(Symbol) || v.is_a?(String) }
-        raise SmarterCSV::ValidationError, "headers: { except: } elements must be String or Symbol, got: #{bad.map(&:class).uniq.inspect}" if bad.any?
-        @options[:except_headers] = values.map(&:to_sym)
-      end
-
-      # Deprecation: remove_values_matching → nil_values_matching
-      # Old behavior: removes the key-value pair entirely.
-      # New behavior: nil_values_matching sets the value to nil (key kept);
-      # combined with the default remove_empty_values: true the net effect is identical.
-      # With remove_empty_values: false, the key is retained with a nil value.
-      if given_options.key?(:remove_values_matching)
-        unless @options[:verbose] == :quiet
-          warn "DEPRECATION WARNING: 'remove_values_matching' is deprecated. " \
-               "Use 'nil_values_matching' instead. With the default 'remove_empty_values: true' " \
-               "the net behavior is identical. With 'remove_empty_values: false', matching values " \
-               "are set to nil but the key is retained in the result hash."
-        end
-        @options[:nil_values_matching] ||= @options[:remove_values_matching]
-        @options[:remove_values_matching] = nil # clear to prevent double-processing
-      end
-
-      # Translate deprecated :strict option to :missing_headers
-      if given_options.key?(:strict)
-        unless @options[:verbose] == :quiet
-          warn "DEPRECATION WARNING: 'strict' option is deprecated and will be removed in a future version. " \
-               "Use 'missing_headers: :raise' instead of 'strict: true', or 'missing_headers: :auto' instead of 'strict: false'."
-        end
-        @options[:missing_headers] = @options[:strict] ? :raise : :auto unless given_options.key?(:missing_headers)
-      end
-
-      # Keep :strict synchronized with :missing_headers (C extension reads :strict directly)
-      @options[:strict] = (@options[:missing_headers] == :raise)
-
-      $stderr.puts "Computed options:\n#{pp(@options)}\n" if @options[:verbose] == :debug
-
-      validate_options!(@options)
-      @options
-    end
-
-    private
-
-    def validate_options!(options)
-      # deprecate required_headers
-      unless options[:required_headers].nil?
-        warn "DEPRECATION WARNING: please use 'required_keys' instead of 'required_headers'" unless options[:verbose] == :quiet
-        if options[:required_keys].nil?
-          options[:required_keys] = options[:required_headers]
-          options[:required_headers] = nil
-        end
-      end
-
-      keys = options.keys
-      errors = []
-      errors << "invalid row_sep" if keys.include?(:row_sep) && !option_valid?(options[:row_sep])
-      errors << "invalid col_sep" if keys.include?(:col_sep) && !option_valid?(options[:col_sep])
-      errors << "invalid quote_char" if keys.include?(:quote_char) && !option_valid?(options[:quote_char])
-      if keys.include?(:quote_char) && options[:quote_char].is_a?(String) && options[:quote_char].bytesize > 1
-        errors << "invalid quote_char: must be a single byte (got #{options[:quote_char].inspect})"
-      end
-      unless %i[double_quotes backslash auto].include?(options[:quote_escaping])
-        errors << "invalid quote_escaping: must be :double_quotes, :backslash, or :auto"
-      end
-      unless %i[legacy standard].include?(options[:quote_boundary])
-        errors << "invalid quote_boundary: must be :legacy or :standard"
-      end
-      fsl = options[:field_size_limit]
-      unless fsl.nil? || (fsl.is_a?(Integer) && fsl > 0)
-        errors << "invalid field_size_limit: must be nil or a positive Integer (got #{fsl.inspect})"
-      end
-      obr = options[:on_bad_row]
-      unless %i[raise skip collect].include?(obr) || obr.respond_to?(:call)
-        errors << "invalid on_bad_row: must be :raise, :skip, :collect, or a callable"
-      end
-      %i[on_start on_chunk on_complete].each do |hook|
-        val = options[hook]
-        errors << "invalid #{hook}: must be nil or a callable" if !val.nil? && !val.respond_to?(:call)
-      end
-      unless %i[auto raise].include?(options[:missing_headers])
-        errors << "invalid missing_headers: must be :auto or :raise"
-      end
-      if options[:only_headers] && options[:except_headers]
-        errors << "cannot use both 'headers: { only: }' and 'headers: { except: }' at the same time"
-      end
-      raise SmarterCSV::ValidationError, errors.inspect if errors.any?
-    end
-
-    def option_valid?(str)
-      return true if str.is_a?(Symbol) && str == :auto
-      return true if str.is_a?(String) && !str.empty?
-
-      false
-    end
-
-    def pp(value)
-      defined?(AwesomePrint) ? value.awesome_inspect(index: nil) : value.inspect
-    end
-  end
-end