method

new

v2_5_5 - Show latest stable - 0 notes - Class: CSV

new(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)

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 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 `:auto` setting, which requests that CSV automatically discover this from the data. Auto-discovery reads ahead in the data looking for the next `"\r\n",` `"\n",` or `"\r"` 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 `ARGF,` `STDIN,` `STDOUT,` or `STDERR,` or the stream is only available for output, the default `$INPUT_RECORD_SEPARATOR` (`$/`) 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 `'` as the quote character instead of the correct `"`. CSV will always consider a double sequence of 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 `:headers` 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 `:col_sep,` `:row_sep,` and `:quote_char` 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 `:converters` 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 empty rows. Note that this setting will not skip rows that contain column separators, even if the rows contain no actual data. If you want to skip rows that contain separators but no content, consider using `:skip_lines,` or inspecting fields.compact.empty? on each row.
`:force_quotes`	When set to a `true` value, CSV will quote all CSV fields it creates.
`:skip_lines`	When set to an object responding to `match,` every line matching it is considered a comment and ignored during parsing. When set to a String, it is first converted to a Regexp. When set to `nil` no line is considered a comment. If the passed object does not respond to `match,` `ArgumentError` is thrown.
`:liberal_parsing`	When set to a `true` value, CSV will attempt to parse input not conformant with RFC 4180, such as double quotes in unquoted fields.

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.

Show source

# File lib/csv.rb, line 1518
  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

new

Related methods