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"