Module: SmarterCSV

Defined in:
lib/smarter_csv.rb,
lib/smarter_csv/errors.rb,
lib/smarter_csv/parser.rb,
lib/smarter_csv/reader.rb,
lib/smarter_csv/writer.rb,
lib/smarter_csv/file_io.rb,
lib/smarter_csv/headers.rb,
lib/smarter_csv/version.rb,
lib/smarter_csv/peekable_io.rb,
lib/smarter_csv/auto_detection.rb,
lib/smarter_csv/reader_options.rb,
lib/smarter_csv/writer_options.rb,
lib/smarter_csv/header_validations.rb,
lib/smarter_csv/hash_transformations.rb,
lib/smarter_csv/header_transformations.rb

Overview

:nocov:

Defined Under Namespace

Modules: AutoDetection, FileIO, HashTransformations, HeaderTransformations, HeaderValidations, Headers, Parser Classes: DuplicateHeaders, EmptyFileError, Error, FieldSizeLimitExceeded, HeaderSizeMismatch, IncorrectOption, InvalidInputData, KeyMappingError, MalformedCSV, MissingKeys, NoColSepDetected, PeekableIO, Reader, SmarterCSVException, TooManyBadRows, ValidationError, Writer

Constant Summary collapse

VERSION = 
"1.17.0.pre5"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Attribute Details

#col_sep ⇒ Object (readonly)

Generate CSV files

Create an instance of the Writer class with the filename and options. call ‘<<` one or multiple times to append data to the file. call `finalize` to save the file.

The ‘<<` method can take different arguments:

* a single Hash
* an array of Hashes
* nested arrays of arrays of Hashes

By default SmarterCSV::Writer automatically discovers all headers that are present in the data on-the-fly. This can be disabled, then only given headers are used. Disabling can be useful when you want to select attributes from hashes, or ActiveRecord instances.

If ‘discover_headers` is enabled, and headers are given, any new headers that are found in the data will still be appended.

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
quote_char : defaults to "
discover_headers : defaults to true
headers : defaults to []
quote_headers: defaults to false
force_quotes: defaults to false
map_headers: defaults to {}, can be a hash of key -> value mappings
value_converters: optional hash of key -> lambda to control serialization
encoding: optional encoding string for the output file, e.g. 'UTF-8', 'ISO-8859-1'
          supports Ruby's 'external:internal' transcoding notation, e.g. 'ISO-8859-1:UTF-8'
          defaults to nil (system default). Only applies when writing to a file path.
write_nil_value: string written in place of nil field values (default: '')
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,
  in combination with the :discover_headers option



55
56
57
 
# File 'lib/smarter_csv/writer.rb', line 55

def col_sep
  @col_sep
end

#discover_headers ⇒ Object (readonly)

Generate CSV files

Create an instance of the Writer class with the filename and options. call ‘<<` one or multiple times to append data to the file. call `finalize` to save the file.

The ‘<<` method can take different arguments:

* a single Hash
* an array of Hashes
* nested arrays of arrays of Hashes

By default SmarterCSV::Writer automatically discovers all headers that are present in the data on-the-fly. This can be disabled, then only given headers are used. Disabling can be useful when you want to select attributes from hashes, or ActiveRecord instances.

If ‘discover_headers` is enabled, and headers are given, any new headers that are found in the data will still be appended.

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
quote_char : defaults to "
discover_headers : defaults to true
headers : defaults to []
quote_headers: defaults to false
force_quotes: defaults to false
map_headers: defaults to {}, can be a hash of key -> value mappings
value_converters: optional hash of key -> lambda to control serialization
encoding: optional encoding string for the output file, e.g. 'UTF-8', 'ISO-8859-1'
          supports Ruby's 'external:internal' transcoding notation, e.g. 'ISO-8859-1:UTF-8'
          defaults to nil (system default). Only applies when writing to a file path.
write_nil_value: string written in place of nil field values (default: '')
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,
  in combination with the :discover_headers option



55
56
57
 
# File 'lib/smarter_csv/writer.rb', line 55

def discover_headers
  @discover_headers
end

#force_quotes ⇒ Object (readonly)

Generate CSV files

Create an instance of the Writer class with the filename and options. call ‘<<` one or multiple times to append data to the file. call `finalize` to save the file.

The ‘<<` method can take different arguments:

* a single Hash
* an array of Hashes
* nested arrays of arrays of Hashes

By default SmarterCSV::Writer automatically discovers all headers that are present in the data on-the-fly. This can be disabled, then only given headers are used. Disabling can be useful when you want to select attributes from hashes, or ActiveRecord instances.

If ‘discover_headers` is enabled, and headers are given, any new headers that are found in the data will still be appended.

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
quote_char : defaults to "
discover_headers : defaults to true
headers : defaults to []
quote_headers: defaults to false
force_quotes: defaults to false
map_headers: defaults to {}, can be a hash of key -> value mappings
value_converters: optional hash of key -> lambda to control serialization
encoding: optional encoding string for the output file, e.g. 'UTF-8', 'ISO-8859-1'
          supports Ruby's 'external:internal' transcoding notation, e.g. 'ISO-8859-1:UTF-8'
          defaults to nil (system default). Only applies when writing to a file path.
write_nil_value: string written in place of nil field values (default: '')
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,
  in combination with the :discover_headers option



55
56
57
 
# File 'lib/smarter_csv/writer.rb', line 55

def force_quotes
  @force_quotes
end

#headers ⇒ Object (readonly)

Generate CSV files

Create an instance of the Writer class with the filename and options. call ‘<<` one or multiple times to append data to the file. call `finalize` to save the file.

The ‘<<` method can take different arguments:

* a single Hash
* an array of Hashes
* nested arrays of arrays of Hashes

By default SmarterCSV::Writer automatically discovers all headers that are present in the data on-the-fly. This can be disabled, then only given headers are used. Disabling can be useful when you want to select attributes from hashes, or ActiveRecord instances.

If ‘discover_headers` is enabled, and headers are given, any new headers that are found in the data will still be appended.

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
quote_char : defaults to "
discover_headers : defaults to true
headers : defaults to []
quote_headers: defaults to false
force_quotes: defaults to false
map_headers: defaults to {}, can be a hash of key -> value mappings
value_converters: optional hash of key -> lambda to control serialization
encoding: optional encoding string for the output file, e.g. 'UTF-8', 'ISO-8859-1'
          supports Ruby's 'external:internal' transcoding notation, e.g. 'ISO-8859-1:UTF-8'
          defaults to nil (system default). Only applies when writing to a file path.
write_nil_value: string written in place of nil field values (default: '')
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,
  in combination with the :discover_headers option



55
56
57
 
# File 'lib/smarter_csv/writer.rb', line 55

def headers
  @headers
end

#map_headers ⇒ Object (readonly)

Generate CSV files

Create an instance of the Writer class with the filename and options. call ‘<<` one or multiple times to append data to the file. call `finalize` to save the file.

The ‘<<` method can take different arguments:

* a single Hash
* an array of Hashes
* nested arrays of arrays of Hashes

By default SmarterCSV::Writer automatically discovers all headers that are present in the data on-the-fly. This can be disabled, then only given headers are used. Disabling can be useful when you want to select attributes from hashes, or ActiveRecord instances.

If ‘discover_headers` is enabled, and headers are given, any new headers that are found in the data will still be appended.

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
quote_char : defaults to "
discover_headers : defaults to true
headers : defaults to []
quote_headers: defaults to false
force_quotes: defaults to false
map_headers: defaults to {}, can be a hash of key -> value mappings
value_converters: optional hash of key -> lambda to control serialization
encoding: optional encoding string for the output file, e.g. 'UTF-8', 'ISO-8859-1'
          supports Ruby's 'external:internal' transcoding notation, e.g. 'ISO-8859-1:UTF-8'
          defaults to nil (system default). Only applies when writing to a file path.
write_nil_value: string written in place of nil field values (default: '')
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,
  in combination with the :discover_headers option



55
56
57
 
# File 'lib/smarter_csv/writer.rb', line 55

def map_headers
  @map_headers
end

#options ⇒ Object (readonly)

Generate CSV files

Create an instance of the Writer class with the filename and options. call ‘<<` one or multiple times to append data to the file. call `finalize` to save the file.

The ‘<<` method can take different arguments:

* a single Hash
* an array of Hashes
* nested arrays of arrays of Hashes

By default SmarterCSV::Writer automatically discovers all headers that are present in the data on-the-fly. This can be disabled, then only given headers are used. Disabling can be useful when you want to select attributes from hashes, or ActiveRecord instances.

If ‘discover_headers` is enabled, and headers are given, any new headers that are found in the data will still be appended.

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
quote_char : defaults to "
discover_headers : defaults to true
headers : defaults to []
quote_headers: defaults to false
force_quotes: defaults to false
map_headers: defaults to {}, can be a hash of key -> value mappings
value_converters: optional hash of key -> lambda to control serialization
encoding: optional encoding string for the output file, e.g. 'UTF-8', 'ISO-8859-1'
          supports Ruby's 'external:internal' transcoding notation, e.g. 'ISO-8859-1:UTF-8'
          defaults to nil (system default). Only applies when writing to a file path.
write_nil_value: string written in place of nil field values (default: '')
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,
  in combination with the :discover_headers option



55
56
57
 
# File 'lib/smarter_csv/writer.rb', line 55

def options
  @options
end

#output_file ⇒ Object (readonly)

Generate CSV files

Create an instance of the Writer class with the filename and options. call ‘<<` one or multiple times to append data to the file. call `finalize` to save the file.

The ‘<<` method can take different arguments:

* a single Hash
* an array of Hashes
* nested arrays of arrays of Hashes

By default SmarterCSV::Writer automatically discovers all headers that are present in the data on-the-fly. This can be disabled, then only given headers are used. Disabling can be useful when you want to select attributes from hashes, or ActiveRecord instances.

If ‘discover_headers` is enabled, and headers are given, any new headers that are found in the data will still be appended.

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
quote_char : defaults to "
discover_headers : defaults to true
headers : defaults to []
quote_headers: defaults to false
force_quotes: defaults to false
map_headers: defaults to {}, can be a hash of key -> value mappings
value_converters: optional hash of key -> lambda to control serialization
encoding: optional encoding string for the output file, e.g. 'UTF-8', 'ISO-8859-1'
          supports Ruby's 'external:internal' transcoding notation, e.g. 'ISO-8859-1:UTF-8'
          defaults to nil (system default). Only applies when writing to a file path.
write_nil_value: string written in place of nil field values (default: '')
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,
  in combination with the :discover_headers option



55
56
57
 
# File 'lib/smarter_csv/writer.rb', line 55

def output_file
  @output_file
end

#quote_char ⇒ Object (readonly)

Generate CSV files

Create an instance of the Writer class with the filename and options. call ‘<<` one or multiple times to append data to the file. call `finalize` to save the file.

The ‘<<` method can take different arguments:

* a single Hash
* an array of Hashes
* nested arrays of arrays of Hashes

By default SmarterCSV::Writer automatically discovers all headers that are present in the data on-the-fly. This can be disabled, then only given headers are used. Disabling can be useful when you want to select attributes from hashes, or ActiveRecord instances.

If ‘discover_headers` is enabled, and headers are given, any new headers that are found in the data will still be appended.

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
quote_char : defaults to "
discover_headers : defaults to true
headers : defaults to []
quote_headers: defaults to false
force_quotes: defaults to false
map_headers: defaults to {}, can be a hash of key -> value mappings
value_converters: optional hash of key -> lambda to control serialization
encoding: optional encoding string for the output file, e.g. 'UTF-8', 'ISO-8859-1'
          supports Ruby's 'external:internal' transcoding notation, e.g. 'ISO-8859-1:UTF-8'
          defaults to nil (system default). Only applies when writing to a file path.
write_nil_value: string written in place of nil field values (default: '')
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,
  in combination with the :discover_headers option



55
56
57
 
# File 'lib/smarter_csv/writer.rb', line 55

def quote_char
  @quote_char
end

#row_sep ⇒ Object (readonly)

Generate CSV files

Create an instance of the Writer class with the filename and options. call ‘<<` one or multiple times to append data to the file. call `finalize` to save the file.

The ‘<<` method can take different arguments:

* a single Hash
* an array of Hashes
* nested arrays of arrays of Hashes

By default SmarterCSV::Writer automatically discovers all headers that are present in the data on-the-fly. This can be disabled, then only given headers are used. Disabling can be useful when you want to select attributes from hashes, or ActiveRecord instances.

If ‘discover_headers` is enabled, and headers are given, any new headers that are found in the data will still be appended.

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
quote_char : defaults to "
discover_headers : defaults to true
headers : defaults to []
quote_headers: defaults to false
force_quotes: defaults to false
map_headers: defaults to {}, can be a hash of key -> value mappings
value_converters: optional hash of key -> lambda to control serialization
encoding: optional encoding string for the output file, e.g. 'UTF-8', 'ISO-8859-1'
          supports Ruby's 'external:internal' transcoding notation, e.g. 'ISO-8859-1:UTF-8'
          defaults to nil (system default). Only applies when writing to a file path.
write_nil_value: string written in place of nil field values (default: '')
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,
  in combination with the :discover_headers option



55
56
57
 
# File 'lib/smarter_csv/writer.rb', line 55

def row_sep
  @row_sep
end

Class Method Details

.each(input, options = {}, &block) ⇒ Object

Yields each successfully parsed row as a Hash (row-by-row, Enumerable-compatible). Returns an Enumerator when called without a block. When called with a block, errors from the run are available via SmarterCSV.errors after the call. When called without a block (Enumerator form), use SmarterCSV::Reader directly for error access.

Examples:

SmarterCSV.each("data.csv") { |hash| MyModel.upsert(hash) }
SmarterCSV.each("data.csv").select { |h| h[:country] == "US" }
SmarterCSV.each("data.csv").lazy.map { |h| h[:name] }.first(10)



119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/smarter_csv.rb', line 119

def self.each(input, options = {}, &block)
  Thread.current[:current_thread_recent_errors] = {}
  Thread.current[:current_thread_recent_warnings] = []
  reader = Reader.new(input, options)
  reader.each(&block)
ensure
  if reader
    Thread.current[:current_thread_recent_errors] = reader.errors
    Thread.current[:current_thread_recent_warnings] = reader.warnings
  end
end

.each_chunk(input, options = {}, &block) ⇒ Object

Yields each chunk as Array<Hash> plus its 0-based chunk index. Requires chunk_size to be set in options (must be >= 1). Returns an Enumerator when called without a block. When called with a block, errors from the run are available via SmarterCSV.errors after the call. When called without a block (Enumerator form), use SmarterCSV::Reader directly for error access.

Examples:

SmarterCSV.each_chunk("data.csv", chunk_size: 500) { |chunk, i| Sidekiq.push_bulk(chunk) }
SmarterCSV.each_chunk("data.csv", chunk_size: 100).with_index { |chunk, i| ... }



140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/smarter_csv.rb', line 140

def self.each_chunk(input, options = {}, &block)
  Thread.current[:current_thread_recent_errors] = {}
  Thread.current[:current_thread_recent_warnings] = []
  reader = Reader.new(input, options)
  reader.each_chunk(&block)
ensure
  if reader
    Thread.current[:current_thread_recent_errors] = reader.errors
    Thread.current[:current_thread_recent_warnings] = reader.warnings
  end
end

.errors ⇒ Object

Returns the errors from the most recent call to .process, .parse, .each, or .each_chunk on the current thread. Cleared at the start of each new call.

Keys (when on_bad_row: :skip or :collect is used):

:bad_row_count  — total number of bad rows encountered
:bad_rows       — array of error records (only with on_bad_row: :collect)

Example:

SmarterCSV.process('data.csv', on_bad_row: :skip)
puts SmarterCSV.errors[:bad_row_count]



163
164
165
 
# File 'lib/smarter_csv.rb', line 163

def self.errors
  Thread.current[:current_thread_recent_errors] || {}
end

.generate(file_path_or_io = nil, options = {}, &block) ⇒ Object

Convenience method for generating CSV files, IO objects, or in-memory strings.

When called WITHOUT a first argument, generates CSV in memory and returns it as a String. When called WITH a file path (String/Pathname) or any IO-compatible object (StringIO, open File handle, etc.), writes to that destination and returns nil. The caller retains ownership of any IO object passed in — SmarterCSV will not close it.

Examples:

# Return CSV as a String (no file argument)
csv_string = SmarterCSV.generate(options) do |csv|
  records.each { |r| csv << r }
end

# Write to a file by path
SmarterCSV.generate('output.csv', options) do |csv|
  MyModel.find_in_batches(batch_size: 100) do |batch|
    batch.each { |record| csv << record.attributes }
  end
end

# Write to a StringIO (e.g. for Rails streaming responses)
io = StringIO.new
SmarterCSV.generate(io) do |csv|
  records.each { |r| csv << r }
end
send_data io.string, type: 'text/csv'

# Write to an already-open file handle
File.open('output.csv', 'w') do |f|
  SmarterCSV.generate(f) do |csv|
    records.each { |r| csv << r }
  end
end

Raises:

  • (ArgumentError) 


217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/smarter_csv.rb', line 217

def self.generate(file_path_or_io = nil, options = {}, &block)
  raise ArgumentError, "SmarterCSV.generate requires a block" unless block_given?

  # When called as generate(options_hash) { }, the hash lands in file_path_or_io
  if file_path_or_io.is_a?(Hash)
    options = file_path_or_io
    file_path_or_io = nil
  end

  if file_path_or_io.nil?
    # No destination given — write to an in-memory StringIO and return the result as a String.
    io = StringIO.new
    writer = Writer.new(io, options)
    begin
      yield writer
    ensure
      writer&.finalize # must finalize before reading io.string
    end
    io.string
  else
    writer = Writer.new(file_path_or_io, options)
    begin
      yield writer
    ensure
      writer&.finalize
    end
  end
end

.parse(csv_string, options = {}, &block) ⇒ Object

Convenience method for parsing a CSV string directly. Equivalent to SmarterCSV.process(StringIO.new(csv_string), options). Errors from the run are available via SmarterCSV.errors after the call.

Example:

data = SmarterCSV.parse("name,age\nAlice,30\nBob,25")
# => [{name: "Alice", age: 30}, {name: "Bob", age: 25}]

SmarterCSV.parse("name,age\nAlice,30") { |chunk| chunk.each { |h| puts h } }



106
107
108
 
# File 'lib/smarter_csv.rb', line 106

def self.parse(csv_string, options = {}, &block)
  process(StringIO.new(csv_string), options, &block)
end

.process(input, given_options = {}, &block) ⇒ Object

For backwards compatibility:

while ‘SmarterCSV.process` works for simple cases, you can’t get access to the internal state any longer. e.g. you need the instance of the Reader to access the original headers

Please use this instead:

reader = SmarterCSV::Reader.new(input, options)
reader.process # with or without block

After calling any of the class-level methods, errors and warnings from the last run are available via:

SmarterCSV.errors    # => { bad_row_count: 2, bad_rows: [...] }
SmarterCSV.warnings  # => [ { type:, code:, message:, count: }, ... ]

These expose the same reader.errors / reader.warnings without requiring access to the Reader instance. Both are cleared at the start of each call and stored per-thread, so this is safe in multi-threaded environments (Puma, Sidekiq). Only the most recent call’s errors and warnings are retained per thread.



81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/smarter_csv.rb', line 81

def self.process(input, given_options = {}, &block)
  Thread.current[:current_thread_recent_errors] = {}
  Thread.current[:current_thread_recent_warnings] = []
  reader = Reader.new(input, given_options)
  reader.process(&block)
ensure
  # Preserve partial error state when processing raises mid-stream
  # (e.g. TooManyBadRows, or a user block raising). `reader` is nil if
  # Reader.new itself raised before the local was assigned.
  if reader
    Thread.current[:current_thread_recent_errors] = reader.errors
    Thread.current[:current_thread_recent_warnings] = reader.warnings
  end
end

.warnings ⇒ Object

Returns the warnings from the most recent call to .process, .parse, .each, or .each_chunk on the current thread. Cleared at the start of each new call.

Each warning is a Hash: { type:, code:, message:, count: }. Repeated warnings of the same (type, code) are deduped — ‘count` tracks the number of occurrences.

Example:

SmarterCSV.process('data.csv')
SmarterCSV.warnings.each { |w| logger.warn("[#{w[:type]}/#{w[:code]}] #{w[:message]} (×#{w[:count]})") }



178
179
180
 
# File 'lib/smarter_csv.rb', line 178

def self.warnings
  Thread.current[:current_thread_recent_warnings] || []
end