class CSV

• CSV
• Reference
• Object

Overview

Provides methods and classes for parsing and generating CSV (comma-separated values) strings.

This module conforms toRFC 4180.

NOTE To useCSV or its children, you must explicitly import it withrequire "csv"

Parsing

Several ways of parsing CSV are provided. The most straight-forward, but slow or inefficient for some scenarios, isCSV#parse, which returns an array of arrays of all data.

Rows can be traversed in a linear fashion withCSV#each_row, or using anIterator.

To parse a CSV in an efficient way, optionally being able to access row values from header names, create an instance of aCSV.

Parsing withCSV#new

A CSV instance holds a cursor to the current row in the CSV. The cursor is advanced by invoking#next, which returnstrue if a next row was found, andfalse otherwise. A first call to#next is required to position the CSV parser in the first row.

Once positioned in a row, values can be obtained with the several#[] methods, which can accept a header name, column position, or header name pattern as aRegex.

Additionally, aRow object can be obtained with the#row method which provides similar methods and can be converted to anArray orHash.

Example

require "csv"

csv = CSV.new("Name, Age\nJohn, 20\nPeter, 30", headers: true)
csv.next # => true

csv["Name"]  # => "John"
csv[0]       # => "John"
csv[-2]      # => "John"
csv[/name/i] # => "John"

csv["Age"] # => " 20"

csv.row.to_a # => ["John", " 20"]
csv.row.to_h # => {"Name" => "John", "Age" => " 20"}

csv.next    # => true
csv["Name"] # => "Peter"

csv.next # => false

Building

To create CSV data, checkCSV#build and theCSV::Builder class.

Defined in:

Constant Summary

DEFAULT_QUOTE_CHAR = '"'

DEFAULT_SEPARATOR = ','

Constructors

• .new(string_or_io : String | IO, headers : Bool = false, strip : Bool = false, separator : Char = DEFAULT_SEPARATOR, quote_char : Char = DEFAULT_QUOTE_CHAR)

  Creates a new instance from the givenString orIO.

• .new(string_or_io : String | IO, headers = false, strip = false, separator : Char = DEFAULT_SEPARATOR, quote_char : Char = DEFAULT_QUOTE_CHAR, &)

  Creates a new instance from the givenString orIO, and yields it to the given block once for each row in the CSV.

Class Method Summary

• .build(separator : Char = DEFAULT_SEPARATOR, quote_char : Char = DEFAULT_QUOTE_CHAR, quoting : Builder::Quoting = Builder::Quoting::RFC, &) : String

  Builds a CSV.

• .build(io : IO, separator : Char = DEFAULT_SEPARATOR, quote_char : Char = DEFAULT_QUOTE_CHAR, quoting : Builder::Quoting = Builder::Quoting::RFC, &) : Nil

  Appends CSV data to the givenIO.

• .each_row(string_or_io : String | IO, separator : Char = DEFAULT_SEPARATOR, quote_char : Char = DEFAULT_QUOTE_CHAR, &)

  Yields each of a CSV's rows as anArray(String).

• .each_row(string_or_io : String | IO, separator : Char = DEFAULT_SEPARATOR, quote_char : Char = DEFAULT_QUOTE_CHAR) : Iterator(Array(String))

  Returns anIterator ofArray(String) over a CSV's rows.

• .parse(string_or_io : String | IO, separator : Char = DEFAULT_SEPARATOR, quote_char : Char = DEFAULT_QUOTE_CHAR) : Array(Array(String))

  Parses a CSV orIO into an array.

Instance Method Summary

• #[](header : String) : String

  Returns the current row's value corresponding to the givenheader name.

• #[](column : Int) : String

  Returns the current row's value at the given column index.

• #[](header_pattern : Regex, *, options : Regex::MatchOptions = Regex::MatchOptions::None) : String

  Returns the current row's value corresponding to the givenheader_pattern.

• #[]?(header : String) : String | Nil

  Returns the current row's value corresponding to the givenheader name.

• #[]?(column : Int) : String | Nil

  Returns the current row's value at the given column index.

• #[]?(header_pattern : Regex, *, options : Regex::MatchOptions = Regex::MatchOptions::None) : String | Nil

  Returns the current row's value corresponding to the givenheader_pattern.

• #each(&) : Nil

  Invokes the block once for each row in this CSV, yieldingself.

• #headers : Array(String)

  Returns this CSV headers.

• #next : Bool

  Advanced the cursor to the next row.

• #rewind : Nil

  Rewinds this CSV to the beginning, rewinding the underlying IO if any.

• #row : Row

  Returns the current row as aRow instance.

• #values_at(*columns : Int)

  Returns a tuple of the current row's values at given indices A negative index counts from the end.

• #values_at(*headers : String)

  Returns a tuple of the current row's values corresponding to the givenheaders RaisesKeyError if any header doesn't exist.

Constructor Detail

Class Method Detail

require "csv"

result = CSV.build do |csv|
  csv.row "one", "two"
  csv.row "three"
end
result # => "one,two\nthree\n"
result = CSV.build(quoting: CSV::Builder::Quoting::ALL) do |csv|
  csv.row "one", "two"
  csv.row "three"
end
result # => "\"one\",\"two\"\n\"three\"\n"

require "csv"

io = IO::Memory.new
io.puts "HEADER"
CSV.build(io) do |csv|
  csv.row "one", "two"
  csv.row "three"
end
io.to_s # => "HEADER\none,two\nthree\n"

require "csv"

CSV.each_row("one,two\nthree") do |row|
  puts row
end

["one", "two"]
["three"]

require "csv"

rows = CSV.each_row("one,two\nthree")
rows.next # => ["one", "two"]
rows.next # => ["three"]

require "csv"

CSV.parse("one,two\nthree")
# => [["one", "two"], ["three"]]
CSV.parse("one;two\n'three;'", separator: ';', quote_char: '\'')
# => [["one", "two"], ["three;"]]

Instance Method Detail