Provides methods and classes for parsing and generating CSV (comma-separated values) strings.
This module conforms to RFC 4180.
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
.
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
.
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
To create CSV data, check CSV#build
and the CSV::Builder
class.
'"'
','
Builds a CSV.
Appends CSV data to the given IO
.
Parses a CSV or IO
into an array.
Returns the current row's value corresponding to the given header name.
Returns the current row's value at the given column index.
Returns the current row's value corresponding to the given header_pattern.
Returns the current row's value corresponding to the given header name.
Returns the current row's value at the given column index.
Returns the current row's value corresponding to the given header_pattern.
Invokes the block once for each row in this CSV, yielding self
.
Returns this CSV headers.
Advanced the cursor to the next row.
Rewinds this CSV to the beginning, rewinding the underlying IO if any.
Returns the current row as a Row
instance.
Returns a tuple of the current row's values at given indices A negative index counts from the end.
Returns a tuple of the current row's values corresponding to the given headers Raises KeyError
if any header doesn't exist.
Reference
Reference
Object
Object
Creates a new instance from the given String
or IO
.
true
, row values are stripped with String#strip
before being returned from methods.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.
Creates a new instance from the given String
or IO
, and yields it to the given block once for each row in the CSV.
true
, row values are stripped with String#strip
before being returned from methods.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.
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"
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"
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;"]]
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.
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.
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.
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.
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.
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.
Returns this CSV headers. Their values are always stripped. Raises CSV::Error
if headers were not requested.
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.
Rewinds this CSV to the beginning, rewinding the underlying IO if any.
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
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
© 2012–2020 Manas Technology Solutions.
Licensed under the Apache License, Version 2.0.
https://crystal-lang.org/api/0.35.1/CSV.html