class CSV

# File lib/csv.rb, line 1098
def self.filter(input=nil, output=nil, **options)
  # parse options for input, output, or both
  in_options, out_options = Hash.new, {row_sep: $INPUT_RECORD_SEPARATOR}
  options.each do |key, value|
    case key.to_s
    when /\Ain(?:put)?_(.+)\Z/
      in_options[$1.to_sym] = value
    when /\Aout(?:put)?_(.+)\Z/
      out_options[$1.to_sym] = value
    else
      in_options[key]  = value
      out_options[key] = value
    end
  end
  # build input and output wrappers
  input  = new(input  || ARGF,    in_options)
  output = new(output || $stdout, out_options)

  # read, yield, write
  input.each do |row|
    yield row
    output << row
  end
end

# File lib/csv.rb, line 1137
def self.foreach(path, **options, &block)
  return to_enum(__method__, path, options) unless block
  open(path, options) do |csv|
    csv.each(&block)
  end
end

# File lib/csv.rb, line 1162
def self.generate(str=nil, **options)
  # add a default empty String, if none was given
  if str
    io = StringIO.new(str)
    io.seek(0, IO::SEEK_END)
  else
    encoding = options[:encoding]
    str      = String.new
    str.force_encoding(encoding) if encoding
  end
  csv = new(str, options) # wrap
  yield csv         # yield for appending
  csv.string        # return final String
end

# File lib/csv.rb, line 1190
def self.generate_line(row, **options)
  options = {row_sep: $INPUT_RECORD_SEPARATOR}.merge(options)
  str = String.new
  if options[:encoding]
    str.force_encoding(options[:encoding])
  elsif field = row.find { |f| not f.nil? }
    str.force_encoding(String(field).encoding)
  end
  (new(str, options) << row).string
end

# File lib/csv.rb, line 1058
def self.instance(data = $stdout, **options)
  # create a _signature_ for this method call, data object and options
  sig = [data.object_id] +
        options.values_at(*DEFAULT_OPTIONS.keys.sort_by { |sym| sym.to_s })

  # fetch or create the instance for this signature
  @@instances ||= Hash.new
  instance = (@@instances[sig] ||= new(data, options))

  if block_given?
    yield instance  # run block, if given, returning result
  else
    instance        # or return the instance
  end
end

# File lib/csv.rb, line 1517
def initialize(data, col_sep: ",", row_sep: :auto, quote_char: '"', field_size_limit:   nil,
               converters: nil, unconverted_fields: nil, headers: false, return_headers: false,
               write_headers: nil, header_converters: nil, skip_blanks: false, force_quotes: false,
               skip_lines: nil, liberal_parsing: false, internal_encoding: nil, external_encoding: nil, encoding: nil)
  raise ArgumentError.new("Cannot parse nil as CSV") if data.nil?

  # create the IO object we will read from
  @io = data.is_a?(String) ? StringIO.new(data) : data
  # honor the IO encoding if we can, otherwise default to ASCII-8BIT
  internal_encoding = Encoding.find(internal_encoding) if internal_encoding
  external_encoding = Encoding.find(external_encoding) if external_encoding
  if encoding
    encoding, = encoding.split(":", 2) if encoding.is_a?(String)
    encoding = Encoding.find(encoding)
  end
  @encoding = raw_encoding(nil) || internal_encoding || encoding ||
              Encoding.default_internal || Encoding.default_external
  #
  # prepare for building safe regular expressions in the target encoding,
  # if we can transcode the needed characters
  #
  @re_esc   = "\\".encode(@encoding).freeze rescue ""
  @re_chars = /#{%"[-\\]\\[\\.^$?*+{}()|# \r\n\t\f\v]".encode(@encoding)}/
  @unconverted_fields = unconverted_fields

  # Stores header row settings and loads header converters, if needed.
  @use_headers    = headers
  @return_headers = return_headers
  @write_headers  = write_headers

  # headers must be delayed until shift(), in case they need a row of content
  @headers = nil

  init_separators(col_sep, row_sep, quote_char, force_quotes)
  init_parsers(skip_blanks, field_size_limit, liberal_parsing)
  init_converters(converters, :@converters, :convert)
  init_converters(header_converters, :@header_converters, :header_convert)
  init_comments(skip_lines)

  @force_encoding = !!encoding

  # track our own lineno since IO gets confused about line-ends is CSV fields
  @lineno = 0

  # make sure headers have been assigned
  if header_row? and [Array, String].include? @use_headers.class and @write_headers
    parse_headers  # won't read data for Array or String
    self << @headers
  end
end

# File lib/csv.rb, line 1264
def self.open(filename, mode="r", **options)
  # wrap a File opened with the remaining +args+ with no newline
  # decorator
  file_opts = {universal_newline: false}.merge(options)

  begin
    f = File.open(filename, mode, file_opts)
  rescue ArgumentError => e
    raise unless /needs binmode/ =~ e.message and mode == "r"
    mode = "rb"
    file_opts = {encoding: Encoding.default_external}.merge(file_opts)
    retry
  end
  begin
    csv = new(f, options)
  rescue Exception
    f.close
    raise
  end

  # handle blocks like Ruby's open(), not like the CSV library
  if block_given?
    begin
      yield csv
    ensure
      csv.close
    end
  else
    csv
  end
end

# File lib/csv.rb, line 1308
def self.parse(*args, &block)
  csv = new(*args)
  if block.nil?  # slurp contents, if no block is given
    begin
      csv.read
    ensure
      csv.close
    end
  else           # or pass each row to a provided block
    csv.each(&block)
  end
end

# File lib/csv.rb, line 1328
def self.parse_line(line, **options)
  new(line, options).shift
end

# File lib/csv.rb, line 1343
def self.read(path, *options)
  open(path, *options) { |csv| csv.read }
end

# File lib/csv.rb, line 1348
def self.readlines(*args)
  read(*args)
end

# File lib/csv.rb, line 1359
def self.table(path, **options)
  read( path, { headers:           true,
                converters:        :numeric,
                header_converters: :symbol }.merge(options) )
end

# File lib/csv.rb, line 1680
def <<(row)
  # make sure headers have been assigned
  if header_row? and [Array, String].include? @use_headers.class and !@write_headers
    parse_headers  # won't read data for Array or String
  end

  # handle CSV::Row objects and Hashes
  row = case row
        when self.class::Row then row.fields
        when Hash            then @headers.map { |header| row[header] }
        else                      row
        end

  @headers =  row if header_row?
  @lineno  += 1

  output = row.map(&@quote).join(@col_sep) + @row_sep  # quote and separate
  if @io.is_a?(StringIO)             and
     output.encoding != (encoding = raw_encoding)
    if @force_encoding
      output = output.encode(encoding)
    elsif (compatible_encoding = Encoding.compatible?(@io.string, output))
      @io.set_encoding(compatible_encoding)
      @io.seek(0, IO::SEEK_END)
    end
  end
  @io << output

  self  # for chaining
end

# File lib/csv.rb, line 1728
def convert(name = nil, &converter)
  add_converter(:@converters, self.class::Converters, name, &converter)
end

# File lib/csv.rb, line 1594
def converters
  @converters.map do |converter|
    name = Converters.rassoc(converter)
    name ? name.first : converter
  end
end

# File lib/csv.rb, line 1759
def each
  if block_given?
    while row = shift
      yield row
    end
  else
    to_enum
  end
end

# File lib/csv.rb, line 1637
def force_quotes?()       @force_quotes       end

# File lib/csv.rb, line 1743
def header_convert(name = nil, &converter)
  add_converter( :@header_converters,
                 self.class::HeaderConverters,
                 name,
                 &converter )
end

# File lib/csv.rb, line 1625
def header_converters
  @header_converters.map do |converter|
    name = HeaderConverters.rassoc(converter)
    name ? name.first : converter
  end
end

# File lib/csv.rb, line 1785
def header_row?
  @use_headers and @headers.nil?
end

# File lib/csv.rb, line 1610
def headers
  @headers || true if @use_headers
end

# File lib/csv.rb, line 1959
def inspect
  str = ["<#", self.class.to_s, " io_type:"]
  # show type of wrapped IO
  if    @io == $stdout then str << "$stdout"
  elsif @io == $stdin  then str << "$stdin"
  elsif @io == $stderr then str << "$stderr"
  else                      str << @io.class.to_s
  end
  # show IO.path(), if available
  if @io.respond_to?(:path) and (p = @io.path)
    str << " io_path:" << p.inspect
  end
  # show encoding
  str << " encoding:" << @encoding.name
  # show other attributes
  %w[ lineno     col_sep     row_sep
      quote_char skip_blanks liberal_parsing ].each do |attr_name|
    if a = instance_variable_get("@#{attr_name}")
      str << " " << attr_name << ":" << a.inspect
    end
  end
  if @use_headers
    str << " headers:" << headers.inspect
  end
  str << ">"
  begin
    str.join('')
  rescue  # any encoding error
    str.map do |s|
      e = Encoding::Converter.asciicompat_encoding(s.encoding)
      e ? s.encode(e) : s.force_encoding("ASCII-8BIT")
    end.join('')
  end
end

# File lib/csv.rb, line 1639
def liberal_parsing?()    @liberal_parsing    end

# File lib/csv.rb, line 1774
def read
  rows = to_a
  if @use_headers
    Table.new(rows)
  else
    rows
  end
end

# File lib/csv.rb, line 1617
def return_headers?()     @return_headers     end

# File lib/csv.rb, line 1664
def rewind
  @headers = nil
  @lineno  = 0

  @io.rewind
end

# File lib/csv.rb, line 1796
def shift
  #########################################################################
  ### This method is purposefully kept a bit long as simple conditional ###
  ### checks are faster than numerous (expensive) method calls.         ###
  #########################################################################

  # handle headers not based on document content
  if header_row? and @return_headers and
     [Array, String].include? @use_headers.class
    if @unconverted_fields
      return add_unconverted_fields(parse_headers, Array.new)
    else
      return parse_headers
    end
  end

  #
  # it can take multiple calls to <tt>@io.gets()</tt> to get a full line,
  # because of \r and/or \n characters embedded in quoted fields
  #
  in_extended_col = false
  csv             = Array.new

  loop do
    # add another read to the line
    unless parse = @io.gets(@row_sep)
      return nil
    end

    if in_extended_col
      @line.concat(parse)
    else
      @line = parse.clone
    end

    parse.sub!(@parsers[:line_end], "")

    if csv.empty?
      #
      # I believe a blank line should be an <tt>Array.new</tt>, not Ruby 1.8
      # CSV's <tt>[nil]</tt>
      #
      if parse.empty?
        @lineno += 1
        if @skip_blanks
          next
        elsif @unconverted_fields
          return add_unconverted_fields(Array.new, Array.new)
        elsif @use_headers
          return self.class::Row.new(Array.new, Array.new)
        else
          return Array.new
        end
      end
    end

    next if @skip_lines and @skip_lines.match parse

    parts =  parse.split(@col_sep, -1)
    if parts.empty?
      if in_extended_col
        csv[-1] << @col_sep   # will be replaced with a @row_sep after the parts.each loop
      else
        csv << nil
      end
    end

    # This loop is the hot path of csv parsing. Some things may be non-dry
    # for a reason. Make sure to benchmark when refactoring.
    parts.each do |part|
      if in_extended_col
        # If we are continuing a previous column
        if part.end_with?(@quote_char) && part.count(@quote_char) % 2 != 0
          # extended column ends
          csv.last << part[0..-2]
          if csv.last =~ @parsers[:stray_quote]
            raise MalformedCSVError,
                  "Missing or stray quote in line #{lineno + 1}"
          end
          csv.last.gsub!(@double_quote_char, @quote_char)
          in_extended_col = false
        else
          csv.last << part << @col_sep
        end
      elsif part.start_with?(@quote_char)
        # If we are starting a new quoted column
        if part.count(@quote_char) % 2 != 0
          # start an extended column
          csv << (part[1..-1] << @col_sep)
          in_extended_col =  true
        elsif part.end_with?(@quote_char)
          # regular quoted column
          csv << part[1..-2]
          if csv.last =~ @parsers[:stray_quote]
            raise MalformedCSVError,
                  "Missing or stray quote in line #{lineno + 1}"
          end
          csv.last.gsub!(@double_quote_char, @quote_char)
        elsif @liberal_parsing
          csv << part
        else
          raise MalformedCSVError,
                "Missing or stray quote in line #{lineno + 1}"
        end
      elsif part =~ @parsers[:quote_or_nl]
        # Unquoted field with bad characters.
        if part =~ @parsers[:nl_or_lf]
          raise MalformedCSVError, "Unquoted fields do not allow " +
                                   "\\r or \\n (line #{lineno + 1})."
        else
          if @liberal_parsing
            csv << part
          else
            raise MalformedCSVError, "Illegal quoting in line #{lineno + 1}."
          end
        end
      else
        # Regular ole unquoted field.
        csv << (part.empty? ? nil : part)
      end
    end

    # Replace tacked on @col_sep with @row_sep if we are still in an extended
    # column.
    csv[-1][-1] = @row_sep if in_extended_col

    if in_extended_col
      # if we're at eof?(), a quoted field wasn't closed...
      if @io.eof?
        raise MalformedCSVError,
              "Unclosed quoted field on line #{lineno + 1}."
      elsif @field_size_limit and csv.last.size >= @field_size_limit
        raise MalformedCSVError, "Field size exceeded on line #{lineno + 1}."
      end
      # otherwise, we need to loop and pull some more data to complete the row
    else
      @lineno += 1

      # save fields unconverted fields, if needed...
      unconverted = csv.dup if @unconverted_fields

      # convert fields, if needed...
      csv = convert_fields(csv) unless @use_headers or @converters.empty?
      # parse out header rows and handle CSV::Row conversions...
      csv = parse_headers(csv)  if     @use_headers

      # inject unconverted fields and accessor, if requested...
      if @unconverted_fields and not csv.respond_to? :unconverted_fields
        add_unconverted_fields(csv, unconverted)
      end

      # return the results
      break csv
    end
  end
end

# File lib/csv.rb, line 1635
def skip_blanks?()        @skip_blanks        end

# File lib/csv.rb, line 1604
def unconverted_fields?() @unconverted_fields end

# File lib/csv.rb, line 1619
def write_headers?()      @write_headers      end

# File lib/csv.rb, line 2176
def add_converter(var_name, const, name = nil, &converter)
  if name.nil?  # custom converter
    instance_variable_get(var_name) << converter
  else          # named converter
    combo = const[name]
    case combo
    when Array  # combo converter
      combo.each do |converter_name|
        add_converter(var_name, const, converter_name)
      end
    else        # individual named converter
      instance_variable_get(var_name) << combo
    end
  end
end

# File lib/csv.rb, line 2263
def add_unconverted_fields(row, fields)
  class << row
    attr_reader :unconverted_fields
  end
  row.instance_variable_set(:@unconverted_fields, fields)
  row
end

# File lib/csv.rb, line 2199
def convert_fields(fields, headers = false)
  # see if we are converting headers or fields
  converters = headers ? @header_converters : @converters

  fields.map.with_index do |field, index|
    converters.each do |converter|
      break if headers && field.nil?
      field = if converter.arity == 1  # straight field converter
        converter[field]
      else                             # FieldInfo converter
        header = @use_headers && !headers ? @headers[index] : nil
        converter[field, FieldInfo.new(index, lineno, header)]
      end
      break unless field.is_a? String  # short-circuit pipeline for speed
    end
    field  # final state of each field, converted or original
  end
end

# File lib/csv.rb, line 2286
def encode_re(*chunks)
  Regexp.new(encode_str(*chunks))
end

# File lib/csv.rb, line 2294
def encode_str(*chunks)
  chunks.map { |chunk| chunk.encode(@encoding.name) }.join('')
end

# File lib/csv.rb, line 2278
def escape_re(str)
  str.gsub(@re_chars) {|c| @re_esc + c}
end

# File lib/csv.rb, line 2161
def init_comments(skip_lines)
  @skip_lines = skip_lines
  @skip_lines = Regexp.new(Regexp.escape(@skip_lines)) if @skip_lines.is_a? String
  if @skip_lines and not @skip_lines.respond_to?(:match)
    raise ArgumentError, ":skip_lines has to respond to matches"
  end
end

# File lib/csv.rb, line 2136
def init_converters(converters, ivar_name, convert_method)
  converters = case converters
               when nil then []
               when Array then converters
               else [converters]
               end
  instance_variable_set(ivar_name, [])
  convert = method(convert_method)

  # load converters
  converters.each do |converter|
    if converter.is_a? Proc  # custom code block
      convert.call(&converter)
    else                     # by name
      convert.call(converter)
    end
  end
end

# File lib/csv.rb, line 2104
def init_parsers(skip_blanks, field_size_limit, liberal_parsing)
  # store the parser behaviors
  @skip_blanks      = skip_blanks
  @field_size_limit = field_size_limit
  @liberal_parsing  = liberal_parsing

  # prebuild Regexps for faster parsing
  esc_row_sep = escape_re(@row_sep)
  esc_quote   = escape_re(@quote_char)
  @parsers = {
    # for detecting parse errors
    quote_or_nl:    encode_re("[", esc_quote, "\r\n]"),
    nl_or_lf:       encode_re("[\r\n]"),
    stray_quote:    encode_re( "[^", esc_quote, "]", esc_quote,
                               "[^", esc_quote, "]" ),
    # safer than chomp!()
    line_end:       encode_re(esc_row_sep, "\\z"),
    # illegal unquoted characters
    return_newline: encode_str("\r\n")
  }
end

# File lib/csv.rb, line 2006
def init_separators(col_sep, row_sep, quote_char, force_quotes)
  # store the selected separators
  @col_sep    = col_sep.to_s.encode(@encoding)
  @row_sep    = row_sep # encode after resolving :auto
  @quote_char = quote_char.to_s.encode(@encoding)
  @double_quote_char = @quote_char * 2

  if @quote_char.length != 1
    raise ArgumentError, ":quote_char has to be a single character String"
  end

  #
  # automatically discover row separator when requested
  # (not fully encoding safe)
  #
  if @row_sep == :auto
    if [ARGF, STDIN, STDOUT, STDERR].include?(@io) or
       (defined?(Zlib) and @io.class == Zlib::GzipWriter)
      @row_sep = $INPUT_RECORD_SEPARATOR
    else
      begin
        #
        # remember where we were (pos() will raise an exception if @io is pipe
        # or not opened for reading)
        #
        saved_pos = @io.pos
        while @row_sep == :auto
          #
          # if we run out of data, it's probably a single line
          # (ensure will set default value)
          #
          break unless sample = @io.gets(nil, 1024)
          # extend sample if we're unsure of the line ending
          if sample.end_with? encode_str("\r")
            sample << (@io.gets(nil, 1) || "")
          end

          # try to find a standard separator
          if sample =~ encode_re("\r\n?|\n")
            @row_sep = $&
            break
          end
        end

        # tricky seek() clone to work around GzipReader's lack of seek()
        @io.rewind
        # reset back to the remembered position
        while saved_pos > 1024  # avoid loading a lot of data into memory
          @io.read(1024)
          saved_pos -= 1024
        end
        @io.read(saved_pos) if saved_pos.nonzero?
      rescue IOError         # not opened for reading
        # do nothing:  ensure will set default
      rescue NoMethodError   # Zlib::GzipWriter doesn't have some IO methods
        # do nothing:  ensure will set default
      rescue SystemCallError # pipe
        # do nothing:  ensure will set default
      ensure
        #
        # set default if we failed to detect
        # (stream not opened for reading, a pipe, or a single line of data)
        #
        @row_sep = $INPUT_RECORD_SEPARATOR if @row_sep == :auto
      end
    end
  end
  @row_sep = @row_sep.to_s.encode(@encoding)

  # establish quoting rules
  @force_quotes = force_quotes
  do_quote = lambda do |field|
    field = String(field)
    encoded_quote = @quote_char.encode(field.encoding)
    encoded_quote + field.gsub(encoded_quote, encoded_quote * 2) + encoded_quote
  end
  quotable_chars = encode_str("\r\n", @col_sep, @quote_char)
  @quote         = if @force_quotes
    do_quote
  else
    lambda do |field|
      if field.nil?  # represent +nil+ fields as empty unquoted fields
        ""
      else
        field = String(field)  # Stringify fields
        # represent empty fields as empty quoted fields
        if field.empty? or
           field.count(quotable_chars).nonzero?
          do_quote.call(field)
        else
          field  # unquoted field
        end
      end
    end
  end
end

# File lib/csv.rb, line 2228
def parse_headers(row = nil)
  if @headers.nil?                # header row
    @headers = case @use_headers  # save headers
               # Array of headers
               when Array then @use_headers
               # CSV header String
               when String
                 self.class.parse_line( @use_headers,
                                        col_sep:    @col_sep,
                                        row_sep:    @row_sep,
                                        quote_char: @quote_char )
               # first row is headers
               else            row
               end

    # prepare converted and unconverted copies
    row      = @headers                       if row.nil?
    @headers = convert_fields(@headers, true)
    @headers.each { |h| h.freeze if h.is_a? String }

    if @return_headers                                     # return headers
      return self.class::Row.new(@headers, row, true)
    elsif not [Array, String].include? @use_headers.class  # skip to field row
      return shift
    end
  end

  self.class::Row.new(@headers, convert_fields(row))  # field row
end

# File lib/csv.rb, line 2302
def raw_encoding(default = Encoding::ASCII_8BIT)
  if @io.respond_to? :internal_encoding
    @io.internal_encoding || @io.external_encoding
  elsif @io.is_a? StringIO
    @io.string.encoding
  elsif @io.respond_to? :encoding
    @io.encoding
  else
    default
  end
end