class CSV

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:

csv.cr
csv/error.cr

Constant Summary

DEFAULT_QUOTE_CHAR = '"'
DEFAULT_SEPARATOR = ','

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class Reference

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other)
==
, dup dup, hash(hasher) hash, initialize initialize, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference) : Bool
same?(other : Nil)
same?
, to_s(io : IO) : Nil to_s

Constructor methods inherited from class Reference

new new, unsafe_construct(address : Pointer, *args, **opts) : self unsafe_construct

Class methods inherited from class Reference

pre_initialize(address : Pointer) pre_initialize

Instance methods inherited from class Object

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other)
===
, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash
hash
, in?(collection : Object) : Bool
in?(*values : Object) : Bool
in?
, inspect(io : IO) : Nil
inspect : String
inspect
, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil!
not_nil!
, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String
to_json
, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil
to_pretty_json
, to_s(io : IO) : Nil
to_s : String
to_s
, to_yaml(io : IO) : Nil
to_yaml : String
to_yaml
, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

Class methods inherited from class Object

from_json(string_or_io, root : String)
from_json(string_or_io)
from_json
, from_yaml(string_or_io : String | IO) from_yaml

Macros inherited from class Object

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

Constructor Detail

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

Creates a new instance from the given String or IO.

  • If strip is true, row values are stripped with String#strip before being returned from methods.
  • If headers is true, row values can be accessed with header names or patterns. Headers are always stripped.

See CSV.parse about the separator and quote_char arguments.


[View source]
def self.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.

  • If strip is true, row values are stripped with String#strip before being returned from methods.
  • If headers is true, row values can be accessed with header names or patterns. Headers are always stripped.

See CSV.parse about the separator and quote_char arguments.


[View source]

Class Method Detail

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

Builds a CSV. This yields a CSV::Builder to the given block.

Takes optional quoting argument to define quote behavior.

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"

See: CSV::Builder::Quoting


[View source]
def self.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. This yields a CSV::Builder that writes to the given IO.

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"

[View source]
def self.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).

See CSV.parse about the separator and quote_char arguments.

require "csv"

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

Output:

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

[View source]
def self.each_row(string_or_io : String | IO, separator : Char = DEFAULT_SEPARATOR, quote_char : Char = DEFAULT_QUOTE_CHAR) #

Returns an Iterator of Array(String) over a CSV's rows.

See CSV.parse about the separator and quote_char arguments.

require "csv"

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

[View source]
def self.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.

Takes optional separator and quote_char arguments for defining non-standard csv cell separators and quote characters.

require "csv"

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

[View source]

Instance Method Detail

def [](header : String) : String #

Returns the current row's value corresponding to the given header name. Raises KeyError if no such header exists. Raises CSV::Error if headers were not requested.


[View source]
def [](column : Int) : String #

Returns the current row's value at the given column index. A negative index counts from the end. Raises IndexError if no such column exists.


[View source]
def [](header_pattern : Regex, *, options : Regex::MatchOptions = Regex::MatchOptions::None) : String #

Returns the current row's value corresponding to the given header_pattern. Raises KeyError if no such header exists. Raises CSV::Error if headers were not requested.


[View source]
def []?(header : String) : String | Nil #

Returns the current row's value corresponding to the given header name. Returns nil if no such header exists. Raises CSV::Error if headers were not requested.


[View source]
def []?(column : Int) : String | Nil #

Returns the current row's value at the given column index. A negative index counts from the end. Returns nil if no such column exists.


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

Returns the current row's value corresponding to the given header_pattern. Returns nil if no such header exists. Raises CSV::Error if headers were not requested.


[View source]
def each(&) : Nil #

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


[View source]
def headers : Array(String) #

Returns this CSV headers. Their values are always stripped. Raises CSV::Error if headers were not requested.


[View source]
def next : Bool #

Advanced the cursor to the next row. Must be called once to position the cursor in the first row. Returns true if a next row was found, false otherwise.


[View source]
def rewind : Nil #

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


[View source]
def row : Row #

Returns the current row as a Row instance.


[View source]
def values_at(*columns : Int) #

Returns a tuple of the current row's values at given indices A negative index counts from the end. Raises IndexError if any column doesn't exist The behavior of returning a tuple is similar to Hash#values_at


[View source]
def 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. Raises CSV::Error if headers were not requested The behavior of returning a tuple is similar to Hash#values_at


[View source]