new

This constructor will wrap either a String or IO object passed in data for reading and/or writing. In addition to the CSV instance methods, several IO methods are delegated. (See CSV::open() for a complete list.) If you pass a String for data, you can later retrieve it (after writing to it, for example) with CSV.string().

Note that a wrapped String will be positioned at at the beginning (for reading). If you want it at the end (for writing), use CSV::generate(). If you want any other positioning, pass a preset StringIO object instead.

You may set any reading and/or writing preferences in the options Hash. Available options are:

:col_sep

The String placed between each field.

This String will be transcoded into
the data's Encoding before parsing.

:row_sep

The String appended to the end of each

row.  This can be set to the special
<tt>:auto</tt> setting, which requests
that CSV automatically discover this
from the data.  Auto-discovery reads
ahead in the data looking for the next
<tt>"\r\n"</tt>, <tt>"\n"</tt>, or
<tt>"\r"</tt> sequence.  A sequence
will be selected even if it occurs in
a quoted field, assuming that you
would have the same line endings
there.  If none of those sequences is
found, +data+ is <tt>ARGF</tt>,
<tt>STDIN</tt>, <tt>STDOUT</tt>, or
<tt>STDERR</tt>, or the stream is only
available for output, the default
<tt>$INPUT_RECORD_SEPARATOR</tt>
(<tt>$/</tt>) is used.  Obviously,
discovery takes a little time.  Set
manually if speed is important.  Also
note that IO objects should be opened
in binary mode on Windows if this
feature will be used as the
line-ending translation can cause
problems with resetting the document
position to where it was before the
read ahead. This String will be
transcoded into the data's Encoding
before parsing.

:quote_char

The character used to quote fields.

This has to be a single character
String.  This is useful for
application that incorrectly use
<tt>'</tt> as the quote character
instead of the correct <tt>"</tt>.
CSV will always consider a double
sequence this character to be an
escaped quote. This String will be
transcoded into the data's Encoding
before parsing.

:field_size_limit

This is a maximum size CSV will read

ahead looking for the closing quote
for a field.  (In truth, it reads to
the first line ending beyond this
size.)  If a quote cannot be found
within the limit CSV will raise a
MalformedCSVError, assuming the data
is faulty.  You can use this limit to
prevent what are effectively DoS
attacks on the parser.  However, this
limit can cause a legitimate parse to
fail and thus is set to +nil+, or off,
by default.

:converters

An Array of names from the Converters

Hash and/or lambdas that handle custom
conversion.  A single converter
doesn't have to be in an Array.  All
built-in converters try to transcode
fields to UTF-8 before converting.
The conversion will fail if the data
cannot be transcoded, leaving the
field unchanged.

:unconverted_fields

If set to true, an

unconverted_fields() method will be
added to all returned rows (Array or
CSV::Row) that will return the fields
as they were before conversion.  Note
that <tt>:headers</tt> supplied by
Array or String were not fields of the
document and thus will have an empty
Array attached.

:headers

If set to :first_row or

+true+, the initial row of the CSV
file will be treated as a row of
headers.  If set to an Array, the
contents will be used as the headers.
If set to a String, the String is run
through a call of CSV::parse_line()
with the same <tt>:col_sep</tt>,
<tt>:row_sep</tt>, and
<tt>:quote_char</tt> as this instance
to produce an Array of headers.  This
setting causes CSV#shift() to return
rows as CSV::Row objects instead of
Arrays and CSV#read() to return
CSV::Table objects instead of an Array
of Arrays.

:return_headers

When false, header rows are silently

swallowed.  If set to +true+, header
rows are returned in a CSV::Row object
with identical headers and
fields (save that the fields do not go
through the converters).

:write_headers

When true and :headers is

set, a header row will be added to the
output.

:header_converters

Identical in functionality to

<tt>:converters</tt> save that the
conversions are only made to header
rows.  All built-in converters try to
transcode headers to UTF-8 before
converting.  The conversion will fail
if the data cannot be transcoded,
leaving the header unchanged.

:skip_blanks

When set to a true value, CSV will

skip over any rows with no content.

:force_quotes

When set to a true value, CSV will

quote all CSV fields it creates.

See CSV::DEFAULT_OPTIONS for the default settings.

Options cannot be overridden in the instance methods for performance reasons, so be sure to set what you want here.

# File lib/csv.rb, line 1562
  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       = data.is_a?(String) ? StringIO.new(data) : data
    # honor the IO encoding if we can, otherwise default to ASCII-8BIT
    @encoding = raw_encoding(nil) ||
                ( if encoding = options.delete(:internal_encoding)
                    case encoding
                    when Encoding; encoding
                    else Encoding.find(encoding)
                    end
                  end ) ||
                ( case encoding = options.delete(:encoding)
                  when Encoding; encoding
                  when /\A[^:]+/; Encoding.find($&)
                  end ) ||
                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) rescue ""
    @re_chars =   /#{%"[-][\\.^$?*+{}()|# \r\n\t\f\v]".encode(@encoding)}/
    # @re_chars =   /#{%"[-][\\.^$?*+{}()|# \r\n\t\f\v]".encode(@encoding, fallback: proc{""})}/

    init_separators(options)
    init_parsers(options)
    init_converters(options)
    init_headers(options)

    options.delete(:encoding)
    options.delete(:internal_encoding)
    options.delete(:external_encoding)
    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