Recipes for Generating CSV ↑

These recipes are specific code examples for specific CSV generating tasks.

For other recipes, see Recipes for CSV.

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

require 'csv'

Contents ↑

Output Formats ↑

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

Generating to a String ↑

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

Recipe: 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"
Recipe: 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"

Generating to a File ↑

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

Recipe: 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"
Recipe: 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"

Generating to an IO Stream ↑

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

Recipe: 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"
Recipe: 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"

Converting Fields ↑

You can use write converters to convert fields when generating CSV.

Recipe: Filter Generated Field Strings ↑

Use option :write_converters and a custom converter to convert field values when generating CSV.

This example defines and uses a custom write converter to strip whitespace from generated fields:

strip_converter = proc {|field| field.respond_to?(:strip) ? field.strip : field }
output_string = CSV.generate(write_converters: strip_converter) do |csv|
  csv << [' foo ', 0]
  csv << [' bar ', 1]
  csv << [' baz ', 2]
end
output_string # => "foo,0\nbar,1\nbaz,2\n"

Recipe: Specify Multiple Write Converters ↑

Use option :write_converters and multiple custom converters to convert field values when generating CSV.

This example defines and uses two custom write converters to strip and upcase generated fields:

strip_converter = proc {|field| field.respond_to?(:strip) ? field.strip : field }
upcase_converter = proc {|field| field.respond_to?(:upcase) ? field.upcase : field }
converters = [strip_converter, upcase_converter]
output_string = CSV.generate(write_converters: converters) do |csv|
  csv << [' foo ', 0]
  csv << [' bar ', 1]
  csv << [' baz ', 2]
end
output_string # => "FOO,0\nBAR,1\nBAZ,2\n"

RFC 4180 Compliance ↑

By default, CSV generates data that is compliant with RFC 4180 with respect to:

Row Separator ↑

RFC 4180 specifies the row separator CRLF (Ruby "\r\n").

Recipe: Generate Compliant Row Separator ↑

For strict compliance, use option :row_sep to specify row separator "\r\n":

output_string = CSV.generate('', row_sep: "\r\n") do |csv|
  csv << ['Foo', 0]
  csv << ['Bar', 1]
  csv << ['Baz', 2]
end
output_string # => "Foo,0\r\nBar,1\r\nBaz,2\r\n"
Recipe: Generate Non-Compliant Row Separator ↑

For data with non-compliant row separators, use option :row_sep with a different value: This example source uses semicolon (";') as its row separator:

output_string = CSV.generate('', row_sep: ";") do |csv|
  csv << ['Foo', 0]
  csv << ['Bar', 1]
  csv << ['Baz', 2]
end
output_string # => "Foo,0;Bar,1;Baz,2;"

Column Separator ↑

RFC 4180 specifies column separator COMMA (Ruby ",").

Recipe: Generate Compliant Column Separator ↑

Because the CSV default comma separator is ",", you need not specify option :col_sep for compliant data:

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"
Recipe: Generate Non-Compliant Column Separator ↑

For data with non-compliant column separators, use option :col_sep. This example source uses TAB ("\t") as its column separator:

output_string = CSV.generate('', col_sep: "\t") do |csv|
  csv << ['Foo', 0]
  csv << ['Bar', 1]
  csv << ['Baz', 2]
end
output_string # => "Foo\t0\nBar\t1\nBaz\t2\n"

Quotes ↑

IFC 4180 allows most fields to be quoted or not. By default, CSV does not quote most fields.

However, a field containing the current row separator, column separator, or quote character is automatically quoted, producing IFC 4180 compliance:

# Field contains row separator.
output_string = CSV.generate('') do |csv|
  row_sep = csv.row_sep
  csv << ["Foo#{row_sep}Foo", 0]
  csv << ['Bar', 1]
  csv << ['Baz', 2]
end
output_string # => "\"Foo\nFoo\",0\nBar,1\nBaz,2\n"
# Field contains column separator.
output_string = CSV.generate('') do |csv|
  col_sep = csv.col_sep
  csv << ["Foo#{col_sep}Foo", 0]
  csv << ['Bar', 1]
  csv << ['Baz', 2]
end
output_string # => "\"Foo,Foo\",0\nBar,1\nBaz,2\n"
# Field contains quote character.
output_string = CSV.generate('') do |csv|
  quote_char = csv.quote_char
  csv << ["Foo#{quote_char}Foo", 0]
  csv << ['Bar', 1]
  csv << ['Baz', 2]
end
output_string # => "\"Foo\"\"Foo\",0\nBar,1\nBaz,2\n"
Recipe: Quote All Fields ↑

Use option :force_quotes to force quoted fields:

output_string = CSV.generate('', force_quotes: true) do |csv|
  csv << ['Foo', 0]
  csv << ['Bar', 1]
  csv << ['Baz', 2]
end
output_string # => "\"Foo\",\"0\"\n\"Bar\",\"1\"\n\"Baz\",\"2\"\n"
Recipe: Quote Empty Fields ↑

Use option :quote_empty to force quoting for empty fields:

output_string = CSV.generate('', quote_empty: true) do |csv|
  csv << ['Foo', 0]
  csv << ['Bar', 1]
  csv << ['', 2]
end
output_string # => "Foo,0\nBar,1\n\"\",2\n"
Recipe: Generate Compliant Quote Character ↑

RFC 4180 specifies quote character DQUOTE (Ruby "\"").

Because the CSV default quote character is also "\"", you need not specify option :quote_char for compliant data:

output_string = CSV.generate('', force_quotes: true) do |csv|
  csv << ['Foo', 0]
  csv << ['Bar', 1]
  csv << ['Baz', 2]
end
output_string # => "\"Foo\",\"0\"\n\"Bar\",\"1\"\n\"Baz\",\"2\"\n"
Recipe: Generate Non-Compliant Quote Character ↑

For data with non-compliant quote characters, use option :quote_char. This example source uses SQUOTE ("'") as its quote character:

output_string = CSV.generate('', quote_char: "'", force_quotes: true) do |csv|
  csv << ['Foo', 0]
  csv << ['Bar', 1]
  csv << ['Baz', 2]
end
output_string # => "'Foo','0'\n'Bar','1'\n'Baz','2'\n"