mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
244 lines
8.6 KiB
Text
244 lines
8.6 KiB
Text
== 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]
|
|
- {RFC 4180 Compliance}[#label-RFC+4180+Compliance]
|
|
- {Row Separator}[#label-Row+Separator]
|
|
- {Recipe: Generate Compliant Row Separator}[#label-Recipe-3A+Generate+Compliant+Row+Separator]
|
|
- {Recipe: Generate Non-Compliant Row Separator}[#label-Recipe-3A+Generate+Non-Compliant+Row+Separator]
|
|
- {Column Separator}[#label-Column+Separator]
|
|
- {Recipe: Generate Compliant Column Separator}[#label-Recipe-3A+Generate+Compliant+Column+Separator]
|
|
- {Recipe: Generate Non-Compliant Column Separator}[#label-Recipe-3A+Generate+Non-Compliant+Column+Separator]
|
|
- {Quote Character}[#label-Quote+Character]
|
|
- {Recipe: Generate Compliant Quote Character}[#label-Recipe-3A+Generate+Compliant+Quote+Character]
|
|
- {Recipe: Generate Non-Compliant Quote Character}[#label-Recipe-3A+Generate+Non-Compliant+Quote+Character]
|
|
|
|
=== 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"
|
|
|
|
=== RFC 4180 Compliance
|
|
|
|
By default, \CSV generates data that is compliant with
|
|
{RFC 4180}[https://tools.ietf.org/html/rfc4180]
|
|
with respect to:
|
|
- Column separator.
|
|
- Quote character.
|
|
|
|
==== Row Separator
|
|
|
|
RFC 4180 specifies the row separator CRLF (Ruby <tt>"\r\n"</tt>).
|
|
|
|
===== Recipe: Generate Compliant Row Separator
|
|
|
|
For strict compliance, use option +:row_sep+ to specify row separator <tt>"\r\n"</tt>:
|
|
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 (<tt>";'</tt>) 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 <tt>","</tt>).
|
|
|
|
===== Recipe: Generate Compliant Column Separator
|
|
|
|
Because the \CSV default comma separator is <tt>","</tt>,
|
|
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 (<tt>"\t"</tt>) 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"
|
|
|
|
==== Quote Character
|
|
|
|
RFC 4180 specifies quote character DQUOTE (Ruby <tt>"\""</tt>).
|
|
|
|
===== Recipe: Generate Compliant Quote Character
|
|
|
|
Because the \CSV default quote character is <tt>"\""</tt>,
|
|
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 (<tt>"'"</tt>) 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"
|