# encoding: US-ASCII

# frozen_string_literal: true

# = csv.rb -- CSV Reading and Writing

#

# Created by James Edward Gray II on 2005-10-31.

#

# See CSV for documentation.

#

# == Description

#

# Welcome to the new and improved CSV.

#

# This version of the CSV library began its life as FasterCSV. FasterCSV was

# intended as a replacement to Ruby's then standard CSV library. It was

# designed to address concerns users of that library had and it had three

# primary goals:

#

# 1. Be significantly faster than CSV while remaining a pure Ruby library.

# 2. Use a smaller and easier to maintain code base. (FasterCSV eventually

# grew larger, was also but considerably richer in features. The parsing

# core remains quite small.)

# 3. Improve on the CSV interface.

#

# Obviously, the last one is subjective. I did try to defer to the original

# interface whenever I didn't have a compelling reason to change it though, so

# hopefully this won't be too radically different.

#

# We must have met our goals because FasterCSV was renamed to CSV and replaced

# the original library as of Ruby 1.9. If you are migrating code from 1.8 or

# earlier, you may have to change your code to comply with the new interface.

#

# == What's the Different From the Old CSV?

#

# I'm sure I'll miss something, but I'll try to mention most of the major

# differences I am aware of, to help others quickly get up to speed:

#

# === \CSV Parsing

#

# * This parser is m17n aware. See CSV for full details.

# * This library has a stricter parser and will throw MalformedCSVErrors on

# problematic data.

# * This library has a less liberal idea of a line ending than CSV. What you

# set as the <tt>:row_sep</tt> is law. It can auto-detect your line endings

# though.

# * The old library returned empty lines as <tt>[nil]</tt>. This library calls

# them <tt>[]</tt>.

# * This library has a much faster parser.

#

# === Interface

#

# * 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().

# * CSV objects now support most standard IO methods.

# * CSV now has a new() method used to wrap objects like String and IO for

# reading and writing.

# * CSV::generate() is different from the old method.

# * CSV no longer supports partial reads. It works line-by-line.

# * CSV no longer allows the instance methods to override the separators for

# performance reasons. They must be set in the constructor.

#

# If you use this library and find yourself missing any functionality I have

# trimmed, please {let me know}[mailto:james@grayproductions.net].

#

# == Documentation

#

# See CSV for documentation.

#

# == What is CSV, really?

#

# CSV maintains a pretty strict definition of CSV taken directly from

# {the RFC}[https://www.ietf.org/rfc/rfc4180.txt]. I relax the rules in only one

# place and that is to make using this library easier. CSV will parse all valid

# CSV.

#

# What you don't want to do is to feed CSV invalid data. Because of the way the

# CSV format works, it's common for a parser to need to read until the end of

# the file to be sure a field is invalid. This consumes a lot of time and memory.

#

# Luckily, when working with invalid CSV, Ruby's built-in methods will almost

# always be superior in every way. For example, parsing non-quoted fields is as

# easy as:

#

# data.split(",")

#

# == Questions and/or Comments

#

# Feel free to email {James Edward Gray II}[mailto:james@grayproductions.net]

# with any questions.

require "forwardable"

require "date"

require "stringio"

require_relative "csv/fields_converter"

require_relative "csv/input_record_separator"

require_relative "csv/parser"

require_relative "csv/row"

require_relative "csv/table"

require_relative "csv/writer"

# == \CSV

#

# === \CSV Data

#

# \CSV (comma-separated values) data is a text representation of a table:

# - A _row_ _separator_ delimits table rows.

# A common row separator is the newline character <tt>"\n"</tt>.

# - A _column_ _separator_ delimits fields in a row.

# A common column separator is the comma character <tt>","</tt>.

#

# This \CSV \String, with row separator <tt>"\n"</tt>

# and column separator <tt>","</tt>,

# has three rows and two columns:

# "foo,0\nbar,1\nbaz,2\n"

#

# Despite the name \CSV, a \CSV representation can use different separators.

#

# For more about tables, see the Wikipedia article

# "{Table (information)}[https://en.wikipedia.org/wiki/Table_(information)]",

# especially its section

# "{Simple table}[https://en.wikipedia.org/wiki/Table_(information)#Simple_table]"

#

# == \Class \CSV

#

# Class \CSV provides methods for:

# - Parsing \CSV data from a \String object, a \File (via its file path), or an \IO object.

# - Generating \CSV data to a \String object.

#

# To make \CSV available:

# require 'csv'

#

# All examples here assume that this has been done.

#

# == Keeping It Simple

#

# A \CSV object has dozens of instance methods that offer fine-grained control

# of parsing and generating \CSV data.

# For many needs, though, simpler approaches will do.

#

# This section summarizes the singleton methods in \CSV

# that allow you to parse and generate without explicitly

# creating \CSV objects.

# For details, follow the links.

#

# === Simple Parsing

#

# Parsing methods commonly return either of:

# - An \Array of Arrays of Strings:

# - The outer \Array is the entire "table".

# - Each inner \Array is a row.

# - Each \String is a field.

# - A CSV::Table object. For details, see

# {\CSV with Headers}[#class-CSV-label-CSV+with+Headers].

#

# ==== Parsing a \String

#

# The input to be parsed can be a string:

# string = "foo,0\nbar,1\nbaz,2\n"

#

# \Method CSV.parse returns the entire \CSV data:

# CSV.parse(string) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

#

# \Method CSV.parse_line returns only the first row:

# CSV.parse_line(string) # => ["foo", "0"]

#

# \CSV extends class \String with instance method String#parse_csv,

# which also returns only the first row:

# string.parse_csv # => ["foo", "0"]

#

# ==== Parsing Via a \File Path

#

# The input to be parsed can be in a file:

# string = "foo,0\nbar,1\nbaz,2\n"

# path = 't.csv'

# File.write(path, string)

#

# \Method CSV.read returns the entire \CSV data:

# CSV.read(path) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

#

# \Method CSV.foreach iterates, passing each row to the given block:

# CSV.foreach(path) do |row|

# p row

# end

# Output:

# ["foo", "0"]

# ["bar", "1"]

# ["baz", "2"]

#

# \Method CSV.table returns the entire \CSV data as a CSV::Table object:

# CSV.table(path) # => #<CSV::Table mode:col_or_row row_count:3>

#

# ==== Parsing from an Open \IO Stream

#

# The input to be parsed can be in an open \IO stream:

#

# \Method CSV.read returns the entire \CSV data:

# File.open(path) do |file|

# CSV.read(file)

# end # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

#

# As does method CSV.parse:

# File.open(path) do |file|

# CSV.parse(file)

# end # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

#

# \Method CSV.parse_line returns only the first row:

# File.open(path) do |file|

# CSV.parse_line(file)

# end # => ["foo", "0"]

#

# \Method CSV.foreach iterates, passing each row to the given block:

# File.open(path) do |file|

# CSV.foreach(file) do |row|

# p row

# end

# end

# Output:

# ["foo", "0"]

# ["bar", "1"]

# ["baz", "2"]

#

# \Method CSV.table returns the entire \CSV data as a CSV::Table object:

# File.open(path) do |file|

# CSV.table(file)

# end # => #<CSV::Table mode:col_or_row row_count:3>

#

# === Simple Generating

#

# \Method CSV.generate returns a \String;

# this example uses method CSV#<< to append the rows

# that are to be generated:

# output_string = CSV.generate do |csv|

# csv << ['foo', 0]

# csv << ['bar', 1]

# csv << ['baz', 2]

# end

# output_string # => "foo,0\nbar,1\nbaz,2\n"

#

# \Method CSV.generate_line returns a \String containing the single row

# constructed from an \Array:

# CSV.generate_line(['foo', '0']) # => "foo,0\n"

#

# \CSV extends class \Array with instance method <tt>Array#to_csv</tt>,

# which forms an \Array into a \String:

# ['foo', '0'].to_csv # => "foo,0\n"

#

# === "Filtering" \CSV

#

# \Method CSV.filter provides a Unix-style filter for \CSV data.

# The input data is processed to form the output data:

# in_string = "foo,0\nbar,1\nbaz,2\n"

# 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"

#

# == \CSV Objects

#

# There are three ways to create a \CSV object:

# - \Method CSV.new returns a new \CSV object.

# - \Method CSV.instance returns a new or cached \CSV object.

# - \Method \CSV() also returns a new or cached \CSV object.

#

# === Instance Methods

#

# \CSV has three groups of instance methods:

# - Its own internally defined instance methods.

# - Methods included by module Enumerable.

# - Methods delegated to class IO. See below.

#

# ==== Delegated Methods

#

# For convenience, a CSV object will delegate to many methods in class IO.

# (A few have wrapper "guard code" in \CSV.) You may call:

# * IO#binmode

# * #binmode?

# * IO#close

# * IO#close_read

# * IO#close_write

# * IO#closed?

# * #eof

# * #eof?

# * IO#external_encoding

# * IO#fcntl

# * IO#fileno

# * #flock

# * IO#flush

# * IO#fsync

# * IO#internal_encoding

# * #ioctl

# * IO#isatty

# * #path

# * IO#pid

# * IO#pos

# * IO#pos=

# * IO#reopen

# * #rewind

# * IO#seek

# * #stat

# * IO#string

# * IO#sync

# * IO#sync=

# * IO#tell

# * #to_i

# * #to_io

# * IO#truncate

# * IO#tty?

#

# === Options

#

# The default values for options are:

# DEFAULT_OPTIONS = {

# # For both parsing and generating.

# col_sep: ",",

# row_sep: :auto,

# quote_char: '"',

# # For parsing.

# field_size_limit: nil,

# converters: nil,

# unconverted_fields: nil,

# headers: false,

# return_headers: false,

# header_converters: nil,

# skip_blanks: false,

# skip_lines: nil,

# liberal_parsing: false,

# nil_value: nil,

# empty_value: "",

# strip: false,

# # For generating.

# write_headers: nil,

# quote_empty: true,

# force_quotes: false,

# write_converters: nil,

# write_nil_value: nil,

# write_empty_value: "",

# }

#

# ==== Options for Parsing

#

# Options for parsing, described in detail below, include:

# - +row_sep+: Specifies the row separator; used to delimit rows.

# - +col_sep+: Specifies the column separator; used to delimit fields.

# - +quote_char+: Specifies the quote character; used to quote fields.

# - +field_size_limit+: Specifies the maximum field size + 1 allowed.

# Deprecated since 3.2.3. Use +max_field_size+ instead.

# - +max_field_size+: Specifies the maximum field size allowed.

# - +converters+: Specifies the field converters to be used.

# - +unconverted_fields+: Specifies whether unconverted fields are to be available.

# - +headers+: Specifies whether data contains headers,

# or specifies the headers themselves.

# - +return_headers+: Specifies whether headers are to be returned.

# - +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. 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.

# - +empty_value+: Specifies the object that is to be substituted for each empty field.

#

# :include: ../doc/csv/options/common/row_sep.rdoc

#

# :include: ../doc/csv/options/common/col_sep.rdoc

#

# :include: ../doc/csv/options/common/quote_char.rdoc

#

# :include: ../doc/csv/options/parsing/field_size_limit.rdoc

#

# :include: ../doc/csv/options/parsing/converters.rdoc

#

# :include: ../doc/csv/options/parsing/unconverted_fields.rdoc

#

# :include: ../doc/csv/options/parsing/headers.rdoc

#

# :include: ../doc/csv/options/parsing/return_headers.rdoc

#

# :include: ../doc/csv/options/parsing/header_converters.rdoc

#

# :include: ../doc/csv/options/parsing/skip_blanks.rdoc

#

# :include: ../doc/csv/options/parsing/skip_lines.rdoc

#

# :include: ../doc/csv/options/parsing/strip.rdoc

#

# :include: ../doc/csv/options/parsing/liberal_parsing.rdoc

#

# :include: ../doc/csv/options/parsing/nil_value.rdoc

#

# :include: ../doc/csv/options/parsing/empty_value.rdoc

#

# ==== Options for Generating

#

# Options for generating, described in detail below, include:

# - +row_sep+: Specifies the row separator; used to delimit rows.

# - +col_sep+: Specifies the column separator; used to delimit fields.

# - +quote_char+: Specifies the quote character; used to quote fields.

# - +write_headers+: Specifies whether headers are to be written.

# - +force_quotes+: Specifies whether each output field is to be quoted.

# - +quote_empty+: Specifies whether each empty output field is to be quoted.

# - +write_converters+: Specifies the field converters to be used in writing.

# - +write_nil_value+: Specifies the object that is to be substituted for each +nil+-valued field.

# - +write_empty_value+: Specifies the object that is to be substituted for each empty field.

#

# :include: ../doc/csv/options/common/row_sep.rdoc

#

# :include: ../doc/csv/options/common/col_sep.rdoc

#

# :include: ../doc/csv/options/common/quote_char.rdoc

#

# :include: ../doc/csv/options/generating/write_headers.rdoc

#

# :include: ../doc/csv/options/generating/force_quotes.rdoc

#

# :include: ../doc/csv/options/generating/quote_empty.rdoc

#

# :include: ../doc/csv/options/generating/write_converters.rdoc

#

# :include: ../doc/csv/options/generating/write_nil_value.rdoc

#

# :include: ../doc/csv/options/generating/write_empty_value.rdoc

#

# === \CSV with Headers

#

# CSV allows to specify column names of CSV file, whether they are in data, or

# provided separately. If headers are specified, reading methods return an instance

# of CSV::Table, consisting of CSV::Row.

#

# # Headers are part of data

# data = CSV.parse(<<~ROWS, headers: true)

# Name,Department,Salary

# Bob,Engineering,1000

# Jane,Sales,2000

# John,Management,5000

# ROWS

#

# data.class #=> CSV::Table

# data.first #=> #<CSV::Row "Name":"Bob" "Department":"Engineering" "Salary":"1000">

# data.first.to_h #=> {"Name"=>"Bob", "Department"=>"Engineering", "Salary"=>"1000"}

#

# # Headers provided by developer

# data = CSV.parse('Bob,Engineering,1000', headers: %i[name department salary])

# data.first #=> #<CSV::Row name:"Bob" department:"Engineering" salary:"1000">

#

# === \Converters

#

# By default, each value (field or header) parsed by \CSV is formed into a \String.

# You can use a _field_ _converter_ or _header_ _converter_

# to intercept and modify the parsed values:

# - See {Field Converters}[#class-CSV-label-Field+Converters].

# - See {Header Converters}[#class-CSV-label-Header+Converters].

#

# Also by default, each value to be written during generation is written 'as-is'.

# You can use a _write_ _converter_ to modify values before writing.

# - See {Write Converters}[#class-CSV-label-Write+Converters].

#

# ==== Specifying \Converters

#

# You can specify converters for parsing or generating in the +options+

# argument to various \CSV methods:

# - Option +converters+ for converting parsed field values.

# - Option +header_converters+ for converting parsed header values.

# - Option +write_converters+ for converting values to be written (generated).

#

# There are three forms for specifying converters:

# - A converter proc: executable code to be used for conversion.

# - A converter name: the name of a stored converter.

# - A converter list: an array of converter procs, converter names, and converter lists.

#

# ===== Converter Procs

#

# This converter proc, +strip_converter+, accepts a value +field+

# and returns <tt>field.strip</tt>:

# strip_converter = proc {|field| field.strip }

# In this call to <tt>CSV.parse</tt>,

# the keyword argument <tt>converters: string_converter</tt>

# specifies that:

# - \Proc +string_converter+ is to be called for each parsed field.

# - The converter's return value is to replace the +field+ value.

# Example:

# string = " foo , 0 \n bar , 1 \n baz , 2 \n"

# array = CSV.parse(string, converters: strip_converter)

# array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

#

# A converter proc can receive a second argument, +field_info+,

# that contains details about the field.

# This modified +strip_converter+ displays its arguments:

# strip_converter = proc do |field, field_info|

# p [field, field_info]

# field.strip

# end

# string = " foo , 0 \n bar , 1 \n baz , 2 \n"

# array = CSV.parse(string, converters: strip_converter)

# array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

# Output:

# [" foo ", #<struct CSV::FieldInfo index=0, line=1, header=nil>]

# [" 0 ", #<struct CSV::FieldInfo index=1, line=1, header=nil>]

# [" bar ", #<struct CSV::FieldInfo index=0, line=2, header=nil>]

# [" 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::FieldInfo object shows:

# - The 0-based field index.

# - The 1-based line index.

# - The field header, if any.

#

# ===== Stored \Converters

#

# A converter may be given a name and stored in a structure where

# the parsing methods can find it by name.

#

# The storage structure for field converters is the \Hash CSV::Converters.

# It has several built-in converter procs:

# - <tt>:integer</tt>: converts each \String-embedded integer into a true \Integer.

# - <tt>:float</tt>: converts each \String-embedded float into a true \Float.

# - <tt>:date</tt>: converts each \String-embedded date into a true \Date.

# - <tt>:date_time</tt>: converts each \String-embedded date-time into a true \DateTime

# .

# This example creates a converter proc, then stores it:

# strip_converter = proc {|field| field.strip }

# CSV::Converters[:strip] = strip_converter

# Then the parsing method call can refer to the converter

# by its name, <tt>:strip</tt>:

# string = " foo , 0 \n bar , 1 \n baz , 2 \n"

# array = CSV.parse(string, converters: :strip)

# array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

#

# The storage structure for header converters is the \Hash CSV::HeaderConverters,

# which works in the same way.

# It also has built-in converter procs:

# - <tt>:downcase</tt>: Downcases each header.

# - <tt>:symbol</tt>: Converts each header to a \Symbol.

#

# 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:

# - Converter procs.

# - Names of stored converters.

# - Nested converter lists.

#

# Examples:

# numeric_converters = [:integer, :float]

# date_converters = [:date, :date_time]

# [numeric_converters, strip_converter]

# [strip_converter, date_converters, :float]

#

# Like a converter proc, a converter list may be named and stored in either

# \CSV::Converters or CSV::HeaderConverters:

# CSV::Converters[:custom] = [strip_converter, date_converters, :float]

# CSV::HeaderConverters[:custom] = [:downcase, :symbol]

#

# There are two built-in converter lists:

# CSV::Converters[:numeric] # => [:integer, :float]

# CSV::Converters[:all] # => [:date_time, :numeric]

#

# ==== Field \Converters

#

# With no conversion, all parsed fields in all rows become Strings:

# string = "foo,0\nbar,1\nbaz,2\n"

# ary = CSV.parse(string)

# ary # => # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

#

# When you specify a field converter, each parsed field is passed to the converter;

# its return value becomes the stored value for the field.

# A converter might, for example, convert an integer embedded in a \String

# into a true \Integer.

# (In fact, that's what built-in field converter +:integer+ does.)

#

# There are three ways to use field \converters.

#

# - Using option {converters}[#class-CSV-label-Option+converters] with a parsing method:

# ary = CSV.parse(string, converters: :integer)

# ary # => [0, 1, 2] # => [["foo", 0], ["bar", 1], ["baz", 2]]

# - Using option {converters}[#class-CSV-label-Option+converters] with a new \CSV instance:

# csv = CSV.new(string, converters: :integer)

# # Field converters in effect:

# csv.converters # => [:integer]

# csv.read # => [["foo", 0], ["bar", 1], ["baz", 2]]

# - Using method #convert to add a field converter to a \CSV instance:

# csv = CSV.new(string)

# # Add a converter.

# csv.convert(:integer)

# csv.converters # => [:integer]

# csv.read # => [["foo", 0], ["bar", 1], ["baz", 2]]

#

# Installing a field converter does not affect already-read rows:

# csv = CSV.new(string)

# csv.shift # => ["foo", "0"]

# # Add a converter.

# csv.convert(:integer)

# csv.converters # => [:integer]

# csv.read # => [["bar", 1], ["baz", 2]]

#

# There are additional built-in \converters, and custom \converters are also supported.

#

# ===== Built-In Field \Converters

#

# The built-in field converters are in \Hash CSV::Converters:

# - Each key is a field converter name.

# - Each value is one of:

# - A \Proc field converter.

# - An \Array of field converter names.

#

# Display:

# CSV::Converters.each_pair do |name, value|

# if value.kind_of?(Proc)

# p [name, value.class]

# else

# p [name, value]

# end

# end

# Output:

# [:integer, Proc]

# [:float, Proc]

# [:numeric, [:integer, :float]]

# [:date, Proc]

# [:date_time, Proc]

# [:all, [:date_time, :numeric]]

#

# Each of these converters transcodes values to UTF-8 before attempting conversion.

# If a value cannot be transcoded to UTF-8 the conversion will

# fail and the value will remain unconverted.

#

# Converter +:integer+ converts each field that Integer() accepts:

# data = '0,1,2,x'

# # Without the converter

# csv = CSV.parse_line(data)

# csv # => ["0", "1", "2", "x"]

# # With the converter

# csv = CSV.parse_line(data, converters: :integer)

# csv # => [0, 1, 2, "x"]

#

# Converter +:float+ converts each field that Float() accepts:

# data = '1.0,3.14159,x'

# # Without the converter

# csv = CSV.parse_line(data)

# csv # => ["1.0", "3.14159", "x"]

# # With the converter

# csv = CSV.parse_line(data, converters: :float)

# csv # => [1.0, 3.14159, "x"]

#

# Converter +:numeric+ converts with both +:integer+ and +:float+..

#

# Converter +:date+ converts each field that Date::parse accepts:

# data = '2001-02-03,x'

# # Without the converter

# csv = CSV.parse_line(data)

# csv # => ["2001-02-03", "x"]

# # With the converter

# csv = CSV.parse_line(data, converters: :date)

# csv # => [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, "x"]

#

# Converter +:date_time+ converts each field that DateTime::parse accepts:

# data = '2020-05-07T14:59:00-05:00,x'

# # Without the converter

# csv = CSV.parse_line(data)

# csv # => ["2020-05-07T14:59:00-05:00", "x"]

# # With the converter

# csv = CSV.parse_line(data, converters: :date_time)

# csv # => [#<DateTime: 2020-05-07T14:59:00-05:00 ((2458977j,71940s,0n),-18000s,2299161j)>, "x"]

#

# Converter +:numeric+ converts with both +:date_time+ and +:numeric+..

#

# As seen above, method #convert adds \converters to a \CSV instance,

# and method #converters returns an \Array of the \converters in effect:

# csv = CSV.new('0,1,2')

# csv.converters # => []

# csv.convert(:integer)

# csv.converters # => [:integer]

# csv.convert(:date)

# csv.converters # => [:integer, :date]

#

# ===== Custom Field \Converters

#

# You can define a custom field converter:

# strip_converter = proc {|field| field.strip }

# string = " foo , 0 \n bar , 1 \n baz , 2 \n"

# array = CSV.parse(string, converters: strip_converter)

# array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

# You can register the converter in \Converters \Hash,

# which allows you to refer to it by name:

# CSV::Converters[:strip] = strip_converter

# string = " foo , 0 \n bar , 1 \n baz , 2 \n"

# array = CSV.parse(string, converters: :strip)

# array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

#

# ==== Header \Converters

#

# 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 +:downcase+,

# which downcases each parsed header.

#

# - Option +header_converters+ with a singleton parsing method:

# string = "Name,Count\nFoo,0\n,Bar,1\nBaz,2"

# tbl = CSV.parse(string, headers: true, header_converters: :downcase)

# tbl.class # => CSV::Table

# tbl.headers # => ["name", "count"]

#

# - Option +header_converters+ with a new \CSV instance:

# csv = CSV.new(string, header_converters: :downcase)

# # Header converters in effect:

# csv.header_converters # => [:downcase]

# tbl = CSV.parse(string, headers: true)

# tbl.headers # => ["Name", "Count"]

#

# - Method #header_convert adds a header converter to a \CSV instance:

# csv = CSV.new(string)

# # Add a header converter.

# csv.header_convert(:downcase)

# csv.header_converters # => [:downcase]

# tbl = CSV.parse(string, headers: true)

# tbl.headers # => ["Name", "Count"]

#

# ===== Built-In Header \Converters

#

# The built-in header \converters are in \Hash CSV::HeaderConverters.

# The keys there are the names of the \converters:

# CSV::HeaderConverters.keys # => [:downcase, :symbol]

#

# Converter +:downcase+ converts each header by downcasing it:

# string = "Name,Count\nFoo,0\n,Bar,1\nBaz,2"

# tbl = CSV.parse(string, headers: true, header_converters: :downcase)

# tbl.class # => CSV::Table

# tbl.headers # => ["name", "count"]

#

# Converter +:symbol+ converts each header by making it into a \Symbol:

# string = "Name,Count\nFoo,0\n,Bar,1\nBaz,2"

# tbl = CSV.parse(string, headers: true, header_converters: :symbol)

# tbl.headers # => [:name, :count]

# Details:

# - Strips leading and trailing whitespace.

# - Downcases the header.

# - Replaces embedded spaces with underscores.

# - Removes non-word characters.

# - Makes the string into a \Symbol.

#

# ===== Custom Header \Converters

#

# You can define a custom header converter:

# upcase_converter = proc {|header| header.upcase }

# string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"

# table = CSV.parse(string, headers: true, header_converters: upcase_converter)

# table # => #<CSV::Table mode:col_or_row row_count:4>

# table.headers # => ["NAME", "VALUE"]

# You can register the converter in \HeaderConverters \Hash,

# which allows you to refer to it by name:

# CSV::HeaderConverters[:upcase] = upcase_converter

# table = CSV.parse(string, headers: true, header_converters: :upcase)

# table # => #<CSV::Table mode:col_or_row row_count:4>

# table.headers # => ["NAME", "VALUE"]

#

# ===== Write \Converters

#

# When you specify a write converter for generating \CSV,

# each field to be written is passed to the converter;

# its return value becomes the new value for the field.

# A converter might, for example, strip whitespace from a field.

#

# Using no write converter (all fields unmodified):

# output_string = CSV.generate do |csv|

# csv << [' foo ', 0]

# csv << [' bar ', 1]

# csv << [' baz ', 2]

# end

# output_string # => " foo ,0\n bar ,1\n baz ,2\n"

# Using option +write_converters+ with two custom write converters:

# strip_converter = proc {|field| field.respond_to?(:strip) ? field.strip : field }

# upcase_converter = proc {|field| field.respond_to?(:upcase) ? field.upcase : field }

# write_converters = [strip_converter, upcase_converter]

# output_string = CSV.generate(write_converters: write_converters) do |csv|

# csv << [' foo ', 0]

# csv << [' bar ', 1]

# csv << [' baz ', 2]

# end

# output_string # => "FOO,0\nBAR,1\nBAZ,2\n"

#

# === Character Encodings (M17n or Multilingualization)

#

# This new CSV parser is m17n savvy. The parser works in the Encoding of the IO

# or String object being read from or written to. Your data is never transcoded

# (unless you ask Ruby to transcode it for you) and will literally be parsed in

# the Encoding it is in. Thus CSV will return Arrays or Rows of Strings in the

# Encoding of your data. This is accomplished by transcoding the parser itself

# into your Encoding.

#

# Some transcoding must take place, of course, to accomplish this multiencoding

# support. For example, <tt>:col_sep</tt>, <tt>:row_sep</tt>, and

# <tt>:quote_char</tt> must be transcoded to match your data. Hopefully this

# makes the entire process feel transparent, since CSV's defaults should just

# magically work for your data. However, you can set these values manually in

# the target Encoding to avoid the translation.

#

# It's also important to note that while all of CSV's core parser is now

# Encoding agnostic, some features are not. For example, the built-in

# converters will try to transcode data to UTF-8 before making conversions.

# Again, you can provide custom converters that are aware of your Encodings to

# avoid this translation. It's just too hard for me to support native

# conversions in all of Ruby's Encodings.

#

# Anyway, the practical side of this is simple: make sure IO and String objects

# passed into CSV have the proper Encoding set and everything should just work.

# CSV methods that allow you to open IO objects (CSV::foreach(), CSV::open(),

# CSV::read(), and CSV::readlines()) do allow you to specify the Encoding.

#

# One minor exception comes when generating CSV into a String with an Encoding

# that is not ASCII compatible. There's no existing data for CSV to use to

# prepare itself and thus you will probably need to manually specify the desired

# Encoding for most of those cases. It will try to guess using the fields in a

# row of output though, when using CSV::generate_line() or Array#to_csv().

#

# I try to point out any other Encoding issues in the documentation of methods

# as they come up.

#

# This has been tested to the best of my ability with all non-"dummy" Encodings

# Ruby ships with. However, it is brave new code and may have some bugs.

# Please feel free to {report}[mailto:james@grayproductions.net] any issues you

# find with it.

#

class CSV