ruby--ruby/doc/csv/recipes/generating.rdoc

== Recipes for Generating \CSV

For other recipes, see {Recipes for CSV}[./recipes_rdoc.html].

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

=== Contents

- {Output Formats}[#label-Output+Formats]
  - {Generating to a String}[#label-Generating+to+a+String]
    - {Recipe: Generate to String with Headers}[#label-Recipe-3A+Generate+to+String+with+Headers]
    - {Recipe: Generate to String Without Headers}[#label-Recipe-3A+Generate+to+String+Without+Headers]
  - {Generating to a File}[#label-Generating+to+a+File]
    - {Recipe: Generate to File with Headers}[#label-Recipe-3A+Generate+to+File+with+Headers]
    - {Recipe: Generate to File Without Headers}[#label-Recipe-3A+Generate+to+File+Without+Headers]
  - {Generating to IO an Stream}[#label-Generating+to+an+IO+Stream]
    - {Recipe: Generate to IO Stream with Headers}[#label-Recipe-3A+Generate+to+IO+Stream+with+Headers]
    - {Recipe: Generate to IO Stream Without Headers}[#label-Recipe-3A+Generate+to+IO+Stream+Without+Headers]
- {Converting Fields}[#label-Converting+Fields]
  - {Recipe: Filter Generated Field Strings}[#label-Recipe-3A+Filter+Generated+Field+Strings]
  - {Recipe: Specify Multiple Write Converters}[#label-Recipe-3A+Specify+Multiple+Write+Converters]

=== 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 <tt>:write_converters</tt> 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 <tt>:write_converters</tt> and multiple custom coverters
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"