Skip to content

Commit 20a9131

Browse files
BurdetteLamarkou
BurdetteLamar
authored and
kou
committed
[ruby/csv] RDoc recipes for RFC-compliant generation (#187)
ruby/csv@5adeaff91f
1 parent d48e688 commit 20a9131

File tree

2 files changed

+105
-10
lines changed

2 files changed

+105
-10
lines changed

‎doc/csv/recipes/generating.rdoc‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,16 @@ All code snippets on this page assume that the following has been executed:
2020
- {Converting Fields}[#label-Converting+Fields]
2121
- {Recipe: Filter Generated Field Strings}[#label-Recipe-3A+Filter+Generated+Field+Strings]
2222
- {Recipe: Specify Multiple Write Converters}[#label-Recipe-3A+Specify+Multiple+Write+Converters]
23+
- {RFC 4180 Compliance}[#label-RFC+4180+Compliance]
24+
- {Row Separator}[#label-Row+Separator]
25+
- {Recipe: Generate Compliant Row Separator}[#label-Recipe-3A+Generate+Compliant+Row+Separator]
26+
- {Recipe: Generate Non-Compliant Row Separator}[#label-Recipe-3A+Generate+Non-Compliant+Row+Separator]
27+
- {Column Separator}[#label-Column+Separator]
28+
- {Recipe: Generate Compliant Column Separator}[#label-Recipe-3A+Generate+Compliant+Column+Separator]
29+
- {Recipe: Generate Non-Compliant Column Separator}[#label-Recipe-3A+Generate+Non-Compliant+Column+Separator]
30+
- {Quote Character}[#label-Quote+Character]
31+
- {Recipe: Generate Compliant Quote Character}[#label-Recipe-3A+Generate+Compliant+Quote+Character]
32+
- {Recipe: Generate Non-Compliant Quote Character}[#label-Recipe-3A+Generate+Non-Compliant+Quote+Character]
2333

2434
=== Output Formats
2535

@@ -147,3 +157,88 @@ This example defines and uses two custom write converters to strip and upcase ge
147157
csv << [' baz ', 2]
148158
end
149159
output_string # => "FOO,0\nBAR,1\nBAZ,2\n"
160+
161+
=== RFC 4180 Compliance
162+
163+
By default, \CSV generates data that is compliant with
164+
{RFC 4180}[https://tools.ietf.org/html/rfc4180]
165+
with respect to:
166+
- Column separator.
167+
- Quote character.
168+
169+
==== Row Separator
170+
171+
RFC 4180 specifies the row separator CRLF (Ruby <tt>"\r\n"</tt>).
172+
173+
===== Recipe: Generate Compliant Row Separator
174+
175+
For strict compliance, use option +:row_sep+ to specify row separator <tt>"\r\n"</tt>:
176+
output_string = CSV.generate('', row_sep: "\r\n") do |csv|
177+
csv << ['Foo', 0]
178+
csv << ['Bar', 1]
179+
csv << ['Baz', 2]
180+
end
181+
output_string # => "Foo,0\r\nBar,1\r\nBaz,2\r\n"
182+
183+
===== Recipe: Generate Non-Compliant Row Separator
184+
185+
For data with non-compliant row separators, use option +:row_sep+ with a different value:
186+
This example source uses semicolon (<tt>";'</tt>) as its row separator:
187+
output_string = CSV.generate('', row_sep: ";") do |csv|
188+
csv << ['Foo', 0]
189+
csv << ['Bar', 1]
190+
csv << ['Baz', 2]
191+
end
192+
output_string # => "Foo,0;Bar,1;Baz,2;"
193+
194+
==== Column Separator
195+
196+
RFC 4180 specifies column separator COMMA (Ruby <tt>","</tt>).
197+
198+
===== Recipe: Generate Compliant Column Separator
199+
200+
Because the \CSV default comma separator is <tt>","</tt>,
201+
you need not specify option +:col_sep+ for compliant data:
202+
output_string = CSV.generate('') do |csv|
203+
csv << ['Foo', 0]
204+
csv << ['Bar', 1]
205+
csv << ['Baz', 2]
206+
end
207+
output_string # => "Foo,0\nBar,1\nBaz,2\n"
208+
209+
===== Recipe: Generate Non-Compliant Column Separator
210+
211+
For data with non-compliant column separators, use option +:col_sep+.
212+
This example source uses TAB (<tt>"\t"</tt>) as its column separator:
213+
output_string = CSV.generate('', col_sep: "\t") do |csv|
214+
csv << ['Foo', 0]
215+
csv << ['Bar', 1]
216+
csv << ['Baz', 2]
217+
end
218+
output_string # => "Foo\t0\nBar\t1\nBaz\t2\n"
219+
220+
==== Quote Character
221+
222+
RFC 4180 specifies quote character DQUOTE (Ruby <tt>"\""</tt>).
223+
224+
===== Recipe: Generate Compliant Quote Character
225+
226+
Because the \CSV default quote character is <tt>"\""</tt>,
227+
you need not specify option +:quote_char+ for compliant data:
228+
output_string = CSV.generate('', force_quotes: true) do |csv|
229+
csv << ['Foo', 0]
230+
csv << ['Bar', 1]
231+
csv << ['Baz', 2]
232+
end
233+
output_string # => "\"Foo\",\"0\"\n\"Bar\",\"1\"\n\"Baz\",\"2\"\n"
234+
235+
===== Recipe: Generate Non-Compliant Quote Character
236+
237+
For data with non-compliant quote characters, use option +:quote_char+.
238+
This example source uses SQUOTE (<tt>"'"</tt>) as its quote character:
239+
output_string = CSV.generate('', quote_char: "'", force_quotes: true) do |csv|
240+
csv << ['Foo', 0]
241+
csv << ['Bar', 1]
242+
csv << ['Baz', 2]
243+
end
244+
output_string # => "'Foo','0'\n'Bar','1'\n'Baz','2'\n"

‎doc/csv/recipes/parsing.rdoc‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -197,14 +197,14 @@ with respect to:
197197

198198
==== Row Separator
199199

200-
RFC 4180 specifies the row separator CRLF (Ruby "\r\n").
200+
RFC 4180 specifies the row separator CRLF (Ruby <tt>"\r\n"</tt>).
201201

202-
Although the \CSV default row separator is "\n",
203-
the parser also by default handles row seperator "\r" and the RFC-compliant "\r\n".
202+
Although the \CSV default row separator is <tt>"\n"</tt>,
203+
the parser also by default handles row separator <tt>"\r"</tt> and the RFC-compliant <tt>"\r\n"</tt>.
204204

205205
===== Recipe: Handle Compliant Row Separator
206206

207-
For strict compliance, use option +:row_sep+ to specify row separator "\r\n",
207+
For strict compliance, use option +:row_sep+ to specify row separator <tt>"\r\n"</tt>,
208208
which allows the compliant row separator:
209209
source = "foo,1\r\nbar,1\r\nbaz,2\r\n"
210210
CSV.parse(source, row_sep: "\r\n") # => [["foo", "1"], ["bar", "1"], ["baz", "2"]]
@@ -219,13 +219,13 @@ But rejects other row separators:
219219
===== Recipe: Handle Non-Compliant Row Separator
220220

221221
For data with non-compliant row separators, use option +:row_sep+.
222-
This example source uses semicolon (';') as its row separator:
222+
This example source uses semicolon (<tt>";"</tt>) as its row separator:
223223
source = "foo,1;bar,1;baz,2;"
224224
CSV.parse(source, row_sep: ';') # => [["foo", "1"], ["bar", "1"], ["baz", "2"]]
225225

226226
==== Column Separator
227227

228-
RFC 4180 specifies column separator COMMA (Ruby ',').
228+
RFC 4180 specifies column separator COMMA (Ruby <tt>","</tt>).
229229

230230
===== Recipe: Handle Compliant Column Separator
231231

@@ -237,25 +237,25 @@ you need not specify option +:col_sep+ for compliant data:
237237
===== Recipe: Handle Non-Compliant Column Separator
238238

239239
For data with non-compliant column separators, use option +:col_sep+.
240-
This example source uses TAB ("\t") as its column separator:
240+
This example source uses TAB (<tt>"\t"</tt>) as its column separator:
241241
source = "foo,1\tbar,1\tbaz,2"
242242
CSV.parse(source, col_sep: "\t") # => [["foo", "1"], ["bar", "1"], ["baz", "2"]]
243243

244244
==== Quote Character
245245

246-
RFC 4180 specifies quote character DQUOTE (Ruby '"').
246+
RFC 4180 specifies quote character DQUOTE (Ruby <tt>"\""</tt>).
247247

248248
===== Recipe: Handle Compliant Quote Character
249249

250-
Because the \CSV default quote character is '"',
250+
Because the \CSV default quote character is <tt>"\""</tt>,
251251
you need not specify option +:quote_char+ for compliant data:
252252
source = "\"foo\",\"1\"\n\"bar\",\"1\"\n\"baz\",\"2\"\n"
253253
CSV.parse(source) # => [["foo", "1"], ["bar", "1"], ["baz", "2"]]
254254

255255
===== Recipe: Handle Non-Compliant Quote Character
256256

257257
For data with non-compliant quote characters, use option +:quote_char+.
258-
This example source uses SQUOTE ("'") as its quote character:
258+
This example source uses SQUOTE (<tt>"'"</tt>) as its quote character:
259259
source = "'foo','1'\n'bar','1'\n'baz','2'\n"
260260
CSV.parse(source, quote_char: "'") # => [["foo", "1"], ["bar", "1"], ["baz", "2"]]
261261

0 commit comments

Comments
 (0)