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.crcsv/error.cr
Constant Summary
-
DEFAULT_QUOTE_CHAR =
'"'
-
DEFAULT_SEPARATOR =
','
Constructors
- .new(string_or_io : String | IO, headers = false, strip : Bool = false, separator : Char = DEFAULT_SEPARATOR, quote_char : Char = DEFAULT_QUOTE_CHAR)
- .new(string_or_io : String | IO, headers = false, strip = false, separator : Char = DEFAULT_SEPARATOR, quote_char : Char = DEFAULT_QUOTE_CHAR, &)
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, &)
- .each_row(string_or_io : String | IO, separator : Char = DEFAULT_SEPARATOR, quote_char : Char = DEFAULT_QUOTE_CHAR)
-
.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.
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
Constructor Detail
Creates a new instance from the given String
or IO
.
- If strip is
true
, row values are stripped withString#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.
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 withString#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.
Class Method Detail
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"
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"]
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"]
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;"]]
Instance Method Detail
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