path: root/doc/csv/recipes.rdoc

== Recipes

All code snippets on this page assume that the following has been executed:
  require 'csv'

=== Contents

- {Parsing: Source Formats}[#label-Parsing-3A+Source+Formats]
  - {Parse from String}[#label-Parse+from+String]
    - {Parse from String with Headers}[#label-Parse+from+String+with+Headers]
    - {Parse from String Without Headers}[#label-Parse+from+String+Without+Headers]
  - {Parse from File}[#label-Parse+from+File]
    - {Parse from File with Headers}[#label-Parse+from+File+with+Headers]
    - {Parse from File Without Headers}[#label-Parse+from+File+Without+Headers]
  - {Parse from IO Stream}[#label-Parse+from+IO+Stream]
    - {Parse from IO Stream with Headers}[#label-Parse+from+IO+Stream+with+Headers]
    - {Parse from IO Stream Without Headers}[#label-Parse+from+IO+Stream+Without+Headers]
- {Parsing: Field Converters}[#label-Parsing-3A+Field+Converters]
  - {Convert Fields to Objects}[#label-Convert+Fields+to+Objects]
    - {Convert Fields to Objects Using Built-In Converters}[#label-Convert+Fields+to+Objects+Using+Built-In+Converters]
    - {Convert Fields to Objects Using Custom Converters}[#label-Convert+Fields+to+Objects+Using+Custom+Converters]
  - {Filter Field Strings}[#label-Filter+Field+Strings]
- {Generating: Output Formats}[#label-Generating-3A+Output+Formats]
  - {Generate to String}[#label-Generate+to+String]
    - {Generate to String with Headers}[#label-Generate+to+String+with+Headers]
    - {Generate to String Without Headers}[#label-Generate+to+String+Without+Headers]
  - {Generate to File}[#label-Generate+to+File]
    - {Generate to File with Headers}[#label-Generate+to+File+with+Headers]
    - {Generate to File Without Headers}[#label-Generate+to+File+Without+Headers]
  - {Generate to IO Stream}[#label-Generate+to+IO+Stream]
    - {Generate to IO Stream with Headers}[#label-Generate+to+IO+Stream+with+Headers]
    - {Generate to IO Stream Without Headers}[#label-Generate+to+IO+Stream+Without+Headers]
- {Filtering: Source and Output Formats}[#label-Filtering-3A+Source+and+Output+Formats]
  - {Filter String to String}[#label-Filter+String+to+String]
    - {Filter String to String with Headers}[#label-Filter+String+to+String+with+Headers]
    - {Filter String to String Without Headers}[#label-Filter+String+to+String+Without+Headers]
  - {Filter String to IO Stream}[#label-Filter+String+to+IO+Stream]
    - {Filter String to IO Stream with Headers}[#label-Filter+String+to+IO+Stream+with+Headers]
    - {Filter String to IO Stream Without Headers}[#label-Filter+String+to+IO+Stream+Without+Headers]
  - {Filter IO Stream to String}[#label-Filter+IO+Stream+to+String]
    - {Filter IO Stream to String with Headers}[#label-Filter+IO+Stream+to+String+with+Headers]
    - {Filter IO Stream to String Without Headers}[#label-Filter+IO+Stream+to+String+Without+Headers]
  - {Filter IO Stream to IO Stream}[#label-Filter+IO+Stream+to+IO+Stream]
    - {Filter IO Stream to IO Stream with Headers}[#label-Filter+IO+Stream+to+IO+Stream+with+Headers]
    - {Filter IO Stream to IO Stream Without Headers}[#label-Filter+IO+Stream+to+IO+Stream+Without+Headers]

=== Parsing: Source Formats

You can parse \CSV data from a \String, from a \File (via its path), or from an \IO stream.

==== Parse from \String

You can parse \CSV data from a \String, with or without headers.

===== Parse from \String with Headers

Use class method CSV.parse with option +headers+ to read a source \String all at once
(may have memory resource implications):
  string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
  CSV.parse(string, headers: true) # => #<CSV::Table mode:col_or_row row_count:4>

Use instance method CSV#each with option +headers+ to read a source \String one row at a time:
  CSV.new(string, headers: true).each do |row|
    p row
  end
Ouput:
  #<CSV::Row "Name":"foo" "Value":"0">
  #<CSV::Row "Name":"bar" "Value":"1">
  #<CSV::Row "Name":"baz" "Value":"2">

===== Parse from \String Without Headers

Use class method CSV.parse without option +headers+ to read a source \String all at once
(may have memory resource implications):
  string = "foo,0\nbar,1\nbaz,2\n"
  CSV.parse(string) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Use instance method CSV#each without option +headers+ to read a source \String one row at a time:
  CSV.new(string).each do |row|
    p row
  end
Output:
  ["foo", "0"]
  ["bar", "1"]
  ["baz", "2"]

==== Parse from \File

You can parse \CSV data from a \File, with or without headers.

===== Parse from \File with Headers

Use instance method CSV#read with option +headers+ to read a file all at once:
  string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
  path = 't.csv'
  File.write(path, string)
  CSV.read(path, headers: true) # => #<CSV::Table mode:col_or_row row_count:4>

Use class method CSV.foreach with option +headers+ to read one row at a time:
  CSV.foreach(path, headers: true) do |row|
    p row
  end
Output:
  #<CSV::Row "Name":"foo" "Value":"0">
  #<CSV::Row "Name":"bar" "Value":"1">
  #<CSV::Row "Name":"baz" "Value":"2">

===== Parse from \File Without Headers

Use class method CSV.read without option +headers+ to read a file all at once:
  string = "foo,0\nbar,1\nbaz,2\n"
  path = 't.csv'
  File.write(path, string)
  CSV.read(path) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Use class method CSV.foreach without option +headers+ to read one row at a time:
  CSV.foreach(path) do |row|
    p row
  end
Output:
  ["foo", "0"]
  ["bar", "1"]
  ["baz", "2"]

==== Parse from \IO Stream

You can parse \CSV data from an \IO stream, with or without headers.

===== Parse from \IO Stream with Headers

Use class method CSV.parse with option +headers+ to read an \IO stream all at once:
  string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
  path = 't.csv'
  File.write(path, string)
  File.open(path) do |file|
    CSV.parse(file, headers: true)
  end # => #<CSV::Table mode:col_or_row row_count:4>

Use class method CSV.foreach with option +headers+ to read one row at a time:
  File.open(path) do |file|
    CSV.foreach(file, headers: true) do |row|
      p row
    end
  end
Output:
  #<CSV::Row "Name":"foo" "Value":"0">
  #<CSV::Row "Name":"bar" "Value":"1">
  #<CSV::Row "Name":"baz" "Value":"2">

===== Parse from \IO Stream Without Headers

Use class method CSV.parse without option +headers+ to read an \IO stream all at once:
  string = "foo,0\nbar,1\nbaz,2\n"
  path = 't.csv'
  File.write(path, string)
  File.open(path) do |file|
    CSV.parse(file)
  end # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Use class method CSV.foreach without option +headers+ to read one row at a time:
  File.open(path) do |file|
    CSV.foreach(file) do |row|
      p row
    end
  end
Output:
  ["foo", "0"]
  ["bar", "1"]
  ["baz", "2"]

=== Parsing: Field Converters

You can use field converters to change parsed Strings into other objects,
or to otherwise modify \String fields.

==== Convert Fields to Objects

Use field converters to change parsed Strings into other, more specific, objects.

==== Convert Fields to Objects Using Built-In Converters

Without converters (all fields parsed as Strings):
  source = "0,1.1,2020-09-19"
  parsed = CSV.parse(source)
  parsed # => [["0", "1.1", "2020-09-19"]]
  parsed.first.each {|field| p field.class }
Output:
  String
  String
  String

With built-in converters (see {Built-In Field Converters}[../../CSV.html#class-CSV-label-Built-In+Field+Converters]):
  parsed = CSV.parse(source, converters: :all)
  parsed # => [[0, 1.1, #<DateTime: 2020-09-19T00:00:00+00:00 ((2459112j,0s,0n),+0s,2299161j)>]]
  parsed.first.each {|field| p field.class }
Output:
  Integer
  Float
  DateTime

==== Convert Fields to Objects Using Custom Converters

You can define custom field converters to convert \String fields into other objects.
This example defines and uses a custom field converter
that converts each column-1 value to a \Rational object.

Define a custom field converter:
  rational_converter = proc do |field, field_context|
    field_context.index == 1 ? field.to_r : field
  end

Without the new converter:
  string = "foo,0\nbar,1\nbaz,2\n"
  array = CSV.parse(string)
  array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

With the new converter:
  array = CSV.parse(string, converters: rational_converter)
  array # => [["foo", (0/1)], ["bar", (1/1)], ["baz", (2/1)]]

You can also register a custom field converter, then refer to it by name:
  CSV::Converters[:rational] = rational_converter
  array = CSV.parse(string, converters: :rational)
  array # => [["foo", (0/1)], ["bar", (1/1)], ["baz", (2/1)]]

==== Filter Field Strings

You can define custom field converters to modify \String fields.
This example defines and uses a custom field converter
that strips whitespace from each field value.

Define a custom field converter:
  strip_converter = proc {|field| field.strip }

Without the new converter:
  string = " foo , 0 \n bar , 1 \n baz , 2 \n"
  array = CSV.parse(string)
  array # => [[" foo ", " 0 "], [" bar ", " 1 "], [" baz ", " 2 "]]

With the new converter:
  array = CSV.parse(string, converters: strip_converter)
  array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

You can also register a custom field converter, then refer to it by name:
  CSV::Converters[:strip] = strip_converter
  array = CSV.parse(string, converters: :strip)
  array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

=== Generating: Output Formats

You can generate \CSV output to a \String, to a \File (via its path), or to an \IO stream.

==== Generate to \String

You can generate \CSV output to a \String, with or without headers.

===== Generate to \String with Headers

Use class method CSV.generate with option +headers+ to generate to a \String.

This example uses method CSV#<< to append the rows
that are to be generated:
  output_string = CSV.generate('', headers: ['Name', 'Value'], write_headers: true) do |csv|
    csv << ['Foo', 0]
    csv << ['Bar', 1]
    csv << ['Baz', 2]
  end
  output_string # => "Name,Value\nFoo,0\nBar,1\nBaz,2\n"

===== Generate to \String Without Headers

Use class method CSV.generate without option +headers+ to generate to a \String.

This example uses method CSV#<< to append the rows
that are to be generated:
  output_string = CSV.generate do |csv|
    csv << ['Foo', 0]
    csv << ['Bar', 1]
    csv << ['Baz', 2]
  end
  output_string # => "Foo,0\nBar,1\nBaz,2\n"

==== Generate to \File

You can generate /CSV data to a \File, with or without headers.

===== Generate to \File with Headers

Use class method CSV.open with option +headers+ generate to a \File.

This example uses method CSV#<< to append the rows
that are to be generated:
  path = 't.csv'
  CSV.open(path, 'w', headers: ['Name', 'Value'], write_headers: true) do |csv|
    csv << ['Foo', 0]
    csv << ['Bar', 1]
    csv << ['Baz', 2]
  end
  p File.read(path) # => "Name,Value\nFoo,0\nBar,1\nBaz,2\n"

===== Generate to \File Without Headers

Use class method CSV.open without option +headers+ to generate to a \File.

This example uses method CSV#<< to append the rows
that are to be generated:
  path = 't.csv'
  CSV.open(path, 'w') do |csv|
    csv << ['Foo', 0]
    csv << ['Bar', 1]
    csv << ['Baz', 2]
  end
  p File.read(path) # => "Foo,0\nBar,1\nBaz,2\n"

==== Generate to \IO Stream

You can generate \CSV data to an \IO stream, with or without headers.

==== Generate to \IO Stream with Headers

Use class method CSV.new with option +headers+ to generate \CSV data to an \IO stream:
  path = 't.csv'
  File.open(path, 'w') do |file|
    csv = CSV.new(file, headers: ['Name', 'Value'], write_headers: true)
    csv << ['Foo', 0]
    csv << ['Bar', 1]
    csv << ['Baz', 2]
  end
  p File.read(path) # => "Name,Value\nFoo,0\nBar,1\nBaz,2\n"

===== Generate to \IO Stream Without Headers

Use class method CSV.new without option +headers+ to generate \CSV data to an \IO stream:
  path = 't.csv'
  File.open(path, 'w') do |file|
    csv = CSV.new(file)
    csv << ['Foo', 0]
    csv << ['Bar', 1]
    csv << ['Baz', 2]
  end
  p File.read(path) # => "Foo,0\nBar,1\nBaz,2\n"

=== Filtering: Source and Output Formats

You can use a Unix-style "filter" for \CSV data.
The filter reads source \CSV data and writes output \CSV data as modified by the filter.
The input and output \CSV data may be any mixture of \Strings and \IO streams.

==== Filter \String to \String

You can filter one \String to another, with or without headers.

===== Filter \String to \String with Headers

Use class method CSV.filter with option +headers+ to filter a \String to another \String:
  in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
  out_string = ''
  CSV.filter(in_string, out_string, headers: true) do |row|
    row[0] = row[0].upcase
    row[1] *= 4
  end
  out_string # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"

===== Filter \String to \String Without Headers

Use class method CSV.filter without option +headers+ to filter a \String to another \String:
  in_string = "foo,0\nbar,1\nbaz,2\n"
  out_string = ''
  CSV.filter(in_string, out_string) do |row|
    row[0] = row[0].upcase
    row[1] *= 4
  end
  out_string # => "FOO,0000\nBAR,1111\nBAZ,2222\n"

==== Filter \String to \IO Stream

You can filter a \String to an \IO stream, with or without headers.

===== Filter \String to \IO Stream with Headers

Use class method CSV.filter with option +headers+ to filter a \String to an \IO stream:
  in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
  path = 't.csv'
  File.open(path, 'w') do |out_io|
    CSV.filter(in_string, out_io, headers: true) do |row|
      row[0] = row[0].upcase
      row[1] *= 4
    end
  end
  p File.read(path) # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"

===== Filter \String to \IO Stream Without Headers

Use class method CSV.filter without option +headers+ to filter a \String to an \IO stream:
  in_string = "foo,0\nbar,1\nbaz,2\n"
  path = 't.csv'
  File.open(path, 'w') do |out_io|
    CSV.filter(in_string, out_io) do |row|
      row[0] = row[0].upcase
      row[1] *= 4
    end
  end
  p File.read(path) # => "FOO,0000\nBAR,1111\nBAZ,2222\n"

==== Filter \IO Stream to \String

You can filter an \IO stream to a \String, with or without headers.

===== Filter \IO Stream to \String with Headers

Use class method CSV.filter with option +headers+ to filter an \IO stream to a \String:
  in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
  path = 't.csv'
  File.write(path, in_string)
  out_string = ''
  File.open(path, headers: true) do |in_io|
    CSV.filter(in_io, out_string, headers: true) do |row|
      row[0] = row[0].upcase
      row[1] *= 4
    end
  end
  out_string # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"

===== Filter \IO Stream to \String Without Headers

Use class method CSV.filter without option +headers+ to filter an \IO stream to a \String:
  in_string = "foo,0\nbar,1\nbaz,2\n"
  path = 't.csv'
  File.write(path, in_string)
  out_string = ''
  File.open(path) do |in_io|
    CSV.filter(in_io, out_string) do |row|
      row[0] = row[0].upcase
      row[1] *= 4
    end
  end
  out_string # => "FOO,0000\nBAR,1111\nBAZ,2222\n"

==== Filter \IO Stream to \IO Stream

You can filter an \IO stream to another \IO stream, with or without headers.

===== Filter \IO Stream to \IO Stream with Headers

Use class method CSV.filter with option +headers+ to filter an \IO stream to another \IO stream:
  in_path = 't.csv'
  in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
  File.write(in_path, in_string)
  out_path = 'u.csv'
  File.open(in_path) do |in_io|
    File.open(out_path, 'w') do |out_io|
      CSV.filter(in_io, out_io, headers: true) do |row|
        row[0] = row[0].upcase
        row[1] *= 4
      end
    end
  end
  p File.read(out_path) # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"

===== Filter \IO Stream to \IO Stream Without Headers

Use class method CSV.filter without option +headers+ to filter an \IO stream to another \IO stream:
  in_path = 't.csv'
  in_string = "foo,0\nbar,1\nbaz,2\n"
  File.write(in_path, in_string)
  out_path = 'u.csv'
  File.open(in_path) do |in_io|
    File.open(out_path, 'w') do |out_io|
      CSV.filter(in_io, out_io) do |row|
        row[0] = row[0].upcase
        row[1] *= 4
      end
    end
  end
  p File.read(out_path) # => "FOO,0000\nBAR,1111\nBAZ,2222\n"