# File lib/faster_csv.rb, line 853
  def self.build_csv_interface
    Object.const_set(:CSV, Class.new).class_eval do
      def self.foreach(path, rs = :auto, &block)  # :nodoc:
        FasterCSV.foreach(path, :row_sep => rs, &block)
      end
      
      def self.generate_line(row, fs = ",", rs = "")  # :nodoc:
        FasterCSV.generate_line(row, :col_sep => fs, :row_sep => rs)
      end
      
      def self.open(path, mode, fs = ",", rs = :auto, &block)  # :nodoc:
        if block and mode.include? "r"
          FasterCSV.open(path, mode, :col_sep => fs, :row_sep => rs) do |csv|
            csv.each(&block)
          end
        else
          FasterCSV.open(path, mode, :col_sep => fs, :row_sep => rs, &block)
        end
      end
      
      def self.parse(str_or_readable, fs = ",", rs = :auto, &block)  # :nodoc:
        FasterCSV.parse(str_or_readable, :col_sep => fs, :row_sep => rs, &block)
      end
      
      def self.parse_line(src, fs = ",", rs = :auto)  # :nodoc:
        FasterCSV.parse_line(src, :col_sep => fs, :row_sep => rs)
      end
      
      def self.readlines(path, rs = :auto)  # :nodoc:
        FasterCSV.readlines(path, :row_sep => rs)
      end
    end
  end

# File lib/faster_csv.rb, line 922
  def self.dump(ary_of_objs, io = "", options = Hash.new)
    obj_template = ary_of_objs.first
    
    csv = FasterCSV.new(io, options)
    
    # write meta information
    begin
      csv << obj_template.class.csv_meta
    rescue NoMethodError
      csv << [:class, obj_template.class]
    end

    # write headers
    begin
      headers = obj_template.csv_headers
    rescue NoMethodError
      headers = obj_template.instance_variables.sort
      if obj_template.class.ancestors.find { |cls| cls.to_s =~ /\AStruct\b/ }
        headers += obj_template.members.map { |mem| "#{mem}=" }.sort
      end
    end
    csv << headers
    
    # serialize each object
    ary_of_objs.each do |obj|
      begin
        csv << obj.csv_dump(headers)
      rescue NoMethodError
        csv << headers.map do |var|
          if var[0] == ?@
            obj.instance_variable_get(var)
          else
            obj[var[0..-2]]
          end
        end
      end
    end
    
    if io.is_a? String
      csv.string
    else
      csv.close
    end
  end

# File lib/faster_csv.rb, line 991
  def self.filter(*args)
    # parse options for input, output, or both
    in_options, out_options = Hash.new, {:row_sep => $INPUT_RECORD_SEPARATOR}
    if args.last.is_a? Hash
      args.pop.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
    end
    # build input and output wrappers
    input   = FasterCSV.new(args.shift || ARGF,    in_options)
    output  = FasterCSV.new(args.shift || $stdout, out_options)
    
    # read, yield, write
    input.each do |row|
      yield row
      output << row
    end
  end

# File lib/faster_csv.rb, line 1025
  def self.foreach(path, options = Hash.new, &block)
    open(path, "rb", options) do |csv|
      csv.each(&block)
    end
  end

# File lib/faster_csv.rb, line 1046
  def self.generate(*args)
    # add a default empty String, if none was given
    if args.first.is_a? String
      io = StringIO.new(args.shift)
      io.seek(0, IO::SEEK_END)
      args.unshift(io)
    else
      args.unshift("")
    end
    faster_csv = new(*args)  # wrap
    yield faster_csv         # yield for appending
    faster_csv.string        # return final String
  end

# File lib/faster_csv.rb, line 1069
  def self.generate_line(row, options = Hash.new)
    options = {:row_sep => $INPUT_RECORD_SEPARATOR}.merge(options)
    (new("", options) << row).string
  end

# File lib/faster_csv.rb, line 1083
  def self.instance(data = $stdout, options = Hash.new)
    # 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/faster_csv.rb, line 1111
  def self.load(io_or_str, options = Hash.new)
    csv = FasterCSV.new(io_or_str, options)
    
    # load meta information
    meta = Hash[*csv.shift]
    cls  = meta["class"].split("::").inject(Object) do |c, const|
      c.const_get(const)
    end
    
    # load headers
    headers = csv.shift
    
    # unserialize each object stored in the file
    results = csv.inject(Array.new) do |all, row|
      begin
        obj = cls.csv_load(meta, headers, row)
      rescue NoMethodError
        obj = cls.allocate
        headers.zip(row) do |name, value|
          if name[0] == ?@
            obj.instance_variable_set(name, value)
          else
            obj.send(name, value)
          end
        end
      end
      all << obj
    end
    
    csv.close unless io_or_str.is_a? String
    
    results
  end

# File lib/faster_csv.rb, line 1400
  def initialize(data, options = Hash.new)
    # build the options for this read/write
    options = DEFAULT_OPTIONS.merge(options)
    
    # create the IO object we will read from
    @io = if data.is_a? String then StringIO.new(data) else data end
    
    init_separators(options)
    init_parsers(options)
    init_converters(options)
    init_headers(options)
    
    unless options.empty?
      raise ArgumentError, "Unknown options:  #{options.keys.join(', ')}."
    end
    
    # track our own lineno since IO gets confused about line-ends is CSV fields
    @lineno = 0
  end

# File lib/faster_csv.rb, line 1190
  def self.open(*args)
    # find the +options+ Hash
    options = if args.last.is_a? Hash then args.pop else Hash.new end
    # default to a binary open mode
    args << "rb" if args.size == 1
    # wrap a File opened with the remaining +args+
    csv     = new(File.open(*args), options)
    
    # 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/faster_csv.rb, line 1222
  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/faster_csv.rb, line 1242
  def self.parse_line(line, options = Hash.new)
    new(line, options).shift
  end

# File lib/faster_csv.rb, line 1250
  def self.read(path, options = Hash.new)
    open(path, "rb", options) { |csv| csv.read }
  end

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

# File lib/faster_csv.rb, line 1266
  def self.table(path, options = Hash.new)
    read( path, { :headers           => true,
                  :converters        => :numeric,
                  :header_converters => :symbol }.merge(options) )
  end

# File lib/faster_csv.rb, line 1452
  def <<(row)
    # make sure headers have been assigned
    if header_row? and [Array, String].include? @use_headers.class
      parse_headers  # won't read data for Array or String
      self << @headers if @write_headers
    end
    
    # Handle FasterCSV::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

    @io << row.map(&@quote).join(@col_sep) + @row_sep  # quote and separate
    
    self  # for chaining
  end

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

# File lib/faster_csv.rb, line 1522
  def each
    while row = shift
      yield row
    end
  end

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

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

# File lib/faster_csv.rb, line 1669
  def inspect
    str = "<##{self.class} 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 other attributes
    %w[ lineno     col_sep     row_sep
        quote_char skip_blanks encoding ].each do |attr_name|
      if a = instance_variable_get("@#{attr_name}")
        str << " #{attr_name}:#{a.inspect}"
      end
    end
    if @use_headers
      str << " headers:#{(@headers || true).inspect}"
    end
    str << ">"
  end

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

# File lib/faster_csv.rb, line 1435
  def rewind
    @headers = nil
    @lineno  = 0
    
    @io.rewind
  end

# File lib/faster_csv.rb, line 1555
  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
    
    # begin with a blank line, so we can always add to it
    line = String.new

    # 
    # 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
    # 
    loop do
      # add another read to the line
      begin
        line  += @io.gets(@row_sep)
      rescue
        return nil
      end
      # copy the line so we can chop it up in parsing
      parse =  line.dup
      parse.sub!(@parsers[:line_end], "")
      
      # 
      # I believe a blank line should be an <tt>Array.new</tt>, not 
      # CSV's <tt>[nil]</tt>
      # 
      if parse.empty?
        @lineno += 1
        if @skip_blanks
          line = ""
          next
        elsif @unconverted_fields
          return add_unconverted_fields(Array.new, Array.new)
        elsif @use_headers
          return FasterCSV::Row.new(Array.new, Array.new)
        else
          return Array.new
        end
      end

      # parse the fields with a mix of String#split and regular expressions
      csv           = Array.new
      current_field = String.new
      field_quotes  = 0
      parse.split(@col_sep, -1).each do |match|
        if current_field.empty? && match.count(@quote_and_newlines).zero?
          csv           << (match.empty? ? nil : match)
        elsif(current_field.empty? ? match[0] : current_field[0]) == @quote_char[0]
          current_field << match
          field_quotes += match.count(@quote_char)
          if field_quotes % 2 == 0
            in_quotes = current_field[@parsers[:quoted_field], 1]
            raise MalformedCSVError unless in_quotes
            current_field = in_quotes
            current_field.gsub!(@quote_char * 2, @quote_char) # unescape contents
            csv           << current_field
            current_field =  String.new
            field_quotes  =  0
          else # we found a quoted field that spans multiple lines
            current_field << @col_sep
          end
        elsif match.count("\r\n").zero?
          raise MalformedCSVError, "Illegal quoting on line #{lineno + 1}."
        else
          raise MalformedCSVError, "Unquoted fields do not allow " +
                                   "\\r or \\n (line #{lineno + 1})."
        end
      end

      # if parse is empty?(), we found all the fields on the line...
      if field_quotes % 2 == 0
        @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 FasterCSV::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
      # if we're not empty?() but 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 current_field.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
    end
  end