class CSV

• CSV
• Reference
• Object

Overview

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

This module conforms to RFC 4180.

NOTE To use CSV or its children, you must explicitly import it with require "csv"

Parsing

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

Rows can be traversed in a linear fashion with CSV#each_row, or using an Iterator.

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

Parsing with CSV#new

A CSV instance holds a cursor to the current row in the CSV. The cursor is advanced by invoking #next, which returns true if a next row was found, and false 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 a Regex.

Additionally, a Row object can be obtained with the #row method which provides similar methods and can be converted to an Array or Hash.

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, check CSV#build and the CSV::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 given String or IO.

• .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 given String or IO, 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 given IO.

• .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 an Array(String).

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

  Returns an Iterator of Array(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 or IO into an array.

Instance Method Summary

• #[](header : String) : String

  Returns the current row's value corresponding to the given header 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 given header_pattern.

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

  Returns the current row's value corresponding to the given header 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 given header_pattern.

• #each(&) : Nil

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

• #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 a Row 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 given headers Raises KeyError 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