1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[ruby/csv] RDoc recipes for RFC-compliant generation (#187)

Browse Source 
https://github.com/ruby/csv/commit/5adeaff91f
This commit is contained in:
Burdette Lamar 2020-10-22 20:51:44 -05:00 committed by Sutou Kouhei
parent d48e688f64
commit 20a9131270
Notes: git 2020-11-24 09:34:26 +09:00 
Merged: https://github.com/ruby/ruby/pull/3804
2 changed files with 105 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
doc/csv/recipes/generating.rdoc
View File

@ -20,6 +20,16 @@ All code snippets on this page assume that the following has been executed:
- {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
@ -147,3 +157,88 @@ This example defines and uses two custom write converters to strip and upcase ge
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"

20
doc/csv/recipes/parsing.rdoc
View File

@ -197,14 +197,14 @@ with respect to:
==== Row Separator
RFC 4180 specifies the row separator CRLF (Ruby "\r\n").
RFC 4180 specifies the row separator CRLF (Ruby <tt>"\r\n"</tt>).
Although the \CSV default row separator is "\n",
the parser also by default handles row seperator "\r" and the RFC-compliant "\r\n".
Although the \CSV default row separator is <tt>"\n"</tt>,
the parser also by default handles row separator <tt>"\r"</tt> and the RFC-compliant <tt>"\r\n"</tt>.
===== Recipe: Handle Compliant Row Separator
For strict compliance, use option +:row_sep+ to specify row separator "\r\n",
For strict compliance, use option +:row_sep+ to specify row separator <tt>"\r\n"</tt>,
which allows the compliant row separator:
source = "foo,1\r\nbar,1\r\nbaz,2\r\n"
CSV.parse(source, row_sep: "\r\n") # => [["foo", "1"], ["bar", "1"], ["baz", "2"]]
@ -219,13 +219,13 @@ But rejects other row separators:
===== Recipe: Handle Non-Compliant Row Separator
For data with non-compliant row separators, use option +:row_sep+.
This example source uses semicolon (';') as its row separator:
This example source uses semicolon (<tt>";"</tt>) as its row separator:
source = "foo,1;bar,1;baz,2;"
CSV.parse(source, row_sep: ';') # => [["foo", "1"], ["bar", "1"], ["baz", "2"]]
==== Column Separator
RFC 4180 specifies column separator COMMA (Ruby ',').
RFC 4180 specifies column separator COMMA (Ruby <tt>","</tt>).
===== Recipe: Handle Compliant Column Separator
@ -237,17 +237,17 @@ you need not specify option +:col_sep+ for compliant data:
===== Recipe: Handle 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:
This example source uses TAB (<tt>"\t"</tt>) as its column separator:
source = "foo,1\tbar,1\tbaz,2"
CSV.parse(source, col_sep: "\t") # => [["foo", "1"], ["bar", "1"], ["baz", "2"]]
==== Quote Character
RFC 4180 specifies quote character DQUOTE (Ruby '"').
RFC 4180 specifies quote character DQUOTE (Ruby <tt>"\""</tt>).
===== Recipe: Handle Compliant Quote Character
Because the \CSV default quote character is '"',
Because the \CSV default quote character is <tt>"\""</tt>,
you need not specify option +:quote_char+ for compliant data:
source = "\"foo\",\"1\"\n\"bar\",\"1\"\n\"baz\",\"2\"\n"
CSV.parse(source) # => [["foo", "1"], ["bar", "1"], ["baz", "2"]]
@ -255,7 +255,7 @@ you need not specify option +:quote_char+ for compliant data:
===== Recipe: Handle Non-Compliant Quote Character
For data with non-compliant quote characters, use option +:quote_char+.
This example source uses SQUOTE ("'") as its quote character:
This example source uses SQUOTE (<tt>"'"</tt>) as its quote character:
source = "'foo','1'\n'bar','1'\n'baz','2'\n"
CSV.parse(source, quote_char: "'") # => [["foo", "1"], ["bar", "1"], ["baz", "2"]]