Flowdock
method

new

Importance_4
new(data, options = Hash.new) public

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 overriden in the instance methods for performance reasons, so be sure to set what you want here.

Show source
Register or log in to add new notes.