Skip to content

Commit 01ffd0d

Browse files
BurdetteLamarBurdetteLamar
authored
Experimenting with recipes in CSV RDoc (#175)
1 parent 203c5e0 commit 01ffd0d

File tree

2 files changed

+326
-0
lines changed

2 files changed

+326
-0
lines changed

‎csv.gemspec

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ Gem::Specification.new do |spec|
4343
"LICENSE.txt",
4444
"NEWS.md",
4545
"README.md",
46+
"doc/csv/recipes.rdoc"
4647
]
4748
spec.extra_rdoc_files = rdoc_files
4849

‎doc/csv/recipes.rdoc

Lines changed: 325 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,325 @@
1+
== Recipes
2+
3+
=== Contents
4+
- {Parsing}[#label-Parsing]
5+
- {Parse from String Without Headers}[#label-Parse+from+String+Without+Headers]
6+
- {Parse from String with Headers}[#label-Parse+from+String+with+Headers]
7+
- {Parse from File Without Headers}[#label-Parse+from+File+Without+Headers]
8+
- {Parse from File with Headers}[#label-Parse+from+File+with+Headers]
9+
- {Parse from IO Stream Without Headers}[#label-Parse+from+IO+Stream+Without+Headers]
10+
- {Parse from IO Stream with Headers}[#label-Parse+from+IO+Stream+with+Headers]
11+
- {Generating}[#label-Generating]
12+
- {Generate to String Without Headers}[#label-Generate+to+String+Without+Headers]
13+
- {Generate to String with Headers}[#label-Generate+to+String+with+Headers]
14+
- {Generate to File Without Headers}[#label-Generate+to+File+Without+Headers]
15+
- {Generate to File with Headers}[#label-Generate+to+File+with+Headers]
16+
- {Generate to IO Stream Without Headers}[#label-Generate+to+IO+Stream+Without+Headers]
17+
- {Generate to IO Stream with Headers}[#label-Generate+to+IO+Stream+with+Headers]
18+
- {Filtering}[#label-Filtering]
19+
- {Filter String to String Without Headers}[#label-Filter+String+to+String+Without+Headers]
20+
- {Filter String to String with Headers}[#label-Filter+String+to+String+with+Headers]
21+
- {Filter String to IO Stream Without Headers}[#label-Filter+String+to+IO+Stream+Without+Headers]
22+
- {Filter String to IO Stream with Headers}[#label-Filter+String+to+IO+Stream+with+Headers]
23+
- {Filter IO Stream to String Without Headers}[#label-Filter+IO+Stream+to+String+Without+Headers]
24+
- {Filter IO Stream to String with Headers}[#label-Filter+IO+Stream+to+String+with+Headers]
25+
- {Filter IO Stream to IO Stream Without Headers}[#label-Filter+IO+Stream+to+IO+Stream+Without+Headers]
26+
- {Filter IO Stream to IO Stream with Headers}[#label-Filter+IO+Stream+to+IO+Stream+with+Headers]
27+
28+
=== Parsing
29+
30+
==== Parse from \String Without Headers
31+
32+
\Class method CSV.parse can read a source \String all at once,
33+
and so may have memory resource implications:
34+
string = "foo,0\nbar,1\nbaz,2\n"
35+
CSV.parse(string) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
36+
37+
Instance method CSV#each can read a source \String one row at a time:
38+
CSV.new(string).each do |row|
39+
p row
40+
end
41+
Output:
42+
["foo", "0"]
43+
["bar", "1"]
44+
["baz", "2"]
45+
46+
==== Parse from \String with Headers
47+
48+
\Class method CSV.parse can read a source \String all at once,
49+
and so may have memory resource implications:
50+
string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
51+
CSV.parse(string, headers: true) # => #<CSV::Table mode:col_or_row row_count:4>
52+
53+
Instance method CSV#each can read a source \String one row at a time:
54+
CSV.new(string, headers: true).each do |row|
55+
p row
56+
end
57+
Ouput:
58+
#<CSV::Row "Name":"foo" "Value":"0">
59+
#<CSV::Row "Name":"bar" "Value":"1">
60+
#<CSV::Row "Name":"baz" "Value":"2">
61+
62+
==== Parse from \File Without Headers
63+
64+
\Class method CSV.read can read a file all at once:
65+
string = "foo,0\nbar,1\nbaz,2\n"
66+
path = 't.csv'
67+
File.write(path, string)
68+
CSV.read(path) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
69+
70+
\Class method CSV.foreach can read one row at a time:
71+
CSV.foreach(path) do |row|
72+
p row
73+
end
74+
Output:
75+
["foo", "0"]
76+
["bar", "1"]
77+
["baz", "2"]
78+
79+
==== Parse from \File with Headers
80+
81+
Instance method CSV#read can reada file all at once:
82+
string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
83+
path = 't.csv'
84+
File.write(path, string)
85+
CSV.read(path, headers: true) # => #<CSV::Table mode:col_or_row row_count:4>
86+
87+
\Class method CSV.foreach can read one row at a time:
88+
CSV.foreach(path, headers: true) do |row|
89+
p row
90+
end
91+
Output:
92+
#<CSV::Row "Name":"foo" "Value":"0">
93+
#<CSV::Row "Name":"bar" "Value":"1">
94+
#<CSV::Row "Name":"baz" "Value":"2">
95+
96+
==== Parse from \IO Stream Without Headers
97+
98+
\Class method CSV.parse can read an \IO stream all at once:
99+
string = "foo,0\nbar,1\nbaz,2\n"
100+
path = 't.csv'
101+
File.write(path, string)
102+
File.open(path) do |file|
103+
CSV.parse(file)
104+
end # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
105+
106+
\Class method CSV.foreach can read one row at a time:
107+
File.open(path) do |file|
108+
CSV.foreach(file) do |row|
109+
p row
110+
end
111+
end
112+
Output:
113+
["foo", "0"]
114+
["bar", "1"]
115+
["baz", "2"]
116+
117+
==== Parse from \IO Stream with Headers
118+
119+
\Class method CSV.parse can read an \IO stream all at once:
120+
string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
121+
path = 't.csv'
122+
File.write(path, string)
123+
File.open(path) do |file|
124+
CSV.parse(file, headers: true)
125+
end # => #<CSV::Table mode:col_or_row row_count:4>
126+
127+
\Class method CSV.foreach can read one row at a time:
128+
File.open(path) do |file|
129+
CSV.foreach(file, headers: true) do |row|
130+
p row
131+
end
132+
end
133+
Output:
134+
#<CSV::Row "Name":"foo" "Value":"0">
135+
#<CSV::Row "Name":"bar" "Value":"1">
136+
#<CSV::Row "Name":"baz" "Value":"2">
137+
138+
=== Generating
139+
140+
==== Generate to \String Without Headers
141+
142+
\Class method CSV.generate can generate to a \String.
143+
144+
This example uses method CSV#<< to append the rows
145+
that are to be generated:
146+
output_string = CSV.generate do |csv|
147+
csv << ['Foo', 0]
148+
csv << ['Bar', 1]
149+
csv << ['Baz', 2]
150+
end
151+
output_string # => "Foo,0\nBar,1\nBaz,2\n"
152+
153+
==== Generate to \String with Headers
154+
155+
\Class method CSV.generate can generate to a \String.
156+
157+
This example uses method CSV#<< to append the rows
158+
that are to be generated:
159+
output_string = CSV.generate('', headers: ['Name', 'Value'], write_headers: true) do |csv|
160+
csv << ['Foo', 0]
161+
csv << ['Bar', 1]
162+
csv << ['Baz', 2]
163+
end
164+
output_string # => "Name,Value\nFoo,0\nBar,1\nBaz,2\n"
165+
166+
==== Generate to \File Without Headers
167+
168+
\Class method CSV.open can generate to a \File.
169+
170+
This example uses method CSV#<< to append the rows
171+
that are to be generated:
172+
path = 't.csv'
173+
CSV.open(path, 'w') do |csv|
174+
csv << ['Foo', 0]
175+
csv << ['Bar', 1]
176+
csv << ['Baz', 2]
177+
end
178+
p File.read(path) # => "Foo,0\nBar,1\nBaz,2\n"
179+
180+
==== Generate to \File with Headers
181+
182+
\Class method CSV.open can generate to a \File.
183+
184+
This example uses method CSV#<< to append the rows
185+
that are to be generated:
186+
path = 't.csv'
187+
CSV.open(path, 'w', headers: ['Name', 'Value'], write_headers: true) do |csv|
188+
csv << ['Foo', 0]
189+
csv << ['Bar', 1]
190+
csv << ['Baz', 2]
191+
end
192+
p File.read(path) # => "Name,Value\nFoo,0\nBar,1\nBaz,2\n"
193+
194+
==== Generate to \IO Stream Without Headers
195+
196+
\Class method CSV.new can generate \CSV data to an \IO stream:
197+
path = 't.csv'
198+
File.open(path, 'w') do |file|
199+
csv = CSV.new(file)
200+
csv << ['Foo', 0]
201+
csv << ['Bar', 1]
202+
csv << ['Baz', 2]
203+
end
204+
p File.read(path) # => "Foo,0\nBar,1\nBaz,2\n"
205+
206+
==== Generate to \IO Stream with Headers
207+
208+
\\Classs method CSV.new can generate \CSV data to an \IO stream:
209+
path = 't.csv'
210+
File.open(path, 'w') do |file|
211+
csv = CSV.new(file, headers: ['Name', 'Value'], write_headers: true)
212+
csv << ['Foo', 0]
213+
csv << ['Bar', 1]
214+
csv << ['Baz', 2]
215+
end
216+
p File.read(path) # => "Name,Value\nFoo,0\nBar,1\nBaz,2\n"
217+
218+
=== Filtering
219+
220+
\Class method CSV.filter provides a Unix-style filter for \CSV data.
221+
The input \CSV data is processed to form output \CSV data.
222+
223+
==== Filter \String to \String Without Headers
224+
225+
in_string = "foo,0\nbar,1\nbaz,2\n"
226+
out_string = ''
227+
CSV.filter(in_string, out_string) do |row|
228+
row[0] = row[0].upcase
229+
row[1] *= 4
230+
end
231+
out_string # => "FOO,0000\nBAR,1111\nBAZ,2222\n"
232+
233+
==== Filter \String to \String with Headers
234+
235+
in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
236+
out_string = ''
237+
CSV.filter(in_string, out_string, headers: true) do |row|
238+
row[0] = row[0].upcase
239+
row[1] *= 4
240+
end
241+
out_string # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"
242+
243+
==== Filter \String to \IO Stream Without Headers
244+
245+
in_string = "foo,0\nbar,1\nbaz,2\n"
246+
path = 't.csv'
247+
File.open(path, 'w') do |out_io|
248+
CSV.filter(in_string, out_io) do |row|
249+
row[0] = row[0].upcase
250+
row[1] *= 4
251+
end
252+
end
253+
p File.read(path) # => "FOO,0000\nBAR,1111\nBAZ,2222\n"
254+
255+
==== Filter \String to \IO Stream with Headers
256+
257+
in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
258+
path = 't.csv'
259+
File.open(path, 'w') do |out_io|
260+
CSV.filter(in_string, out_io, headers: true) do |row|
261+
row[0] = row[0].upcase
262+
row[1] *= 4
263+
end
264+
end
265+
p File.read(path) # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"
266+
267+
==== Filter \IO Stream to \String Without Headers
268+
269+
in_string = "foo,0\nbar,1\nbaz,2\n"
270+
path = 't.csv'
271+
File.write(path, in_string)
272+
out_string = ''
273+
File.open(path) do |in_io|
274+
CSV.filter(in_io, out_string) do |row|
275+
row[0] = row[0].upcase
276+
row[1] *= 4
277+
end
278+
end
279+
out_string # => "FOO,0000\nBAR,1111\nBAZ,2222\n"
280+
281+
==== Filter \IO Stream to \String with Headers
282+
283+
in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
284+
path = 't.csv'
285+
File.write(path, in_string)
286+
out_string = ''
287+
File.open(path, headers: true) do |in_io|
288+
CSV.filter(in_io, out_string, headers: true) do |row|
289+
row[0] = row[0].upcase
290+
row[1] *= 4
291+
end
292+
end
293+
out_string # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"
294+
295+
==== Filter \IO Stream to \IO Stream Without Headers
296+
297+
in_path = 't.csv'
298+
in_string = "foo,0\nbar,1\nbaz,2\n"
299+
File.write(in_path, in_string)
300+
out_path = 'u.csv'
301+
File.open(in_path) do |in_io|
302+
File.open(out_path, 'w') do |out_io|
303+
CSV.filter(in_io, out_io) do |row|
304+
row[0] = row[0].upcase
305+
row[1] *= 4
306+
end
307+
end
308+
end
309+
p File.read(out_path) # => "FOO,0000\nBAR,1111\nBAZ,2222\n"
310+
311+
==== Filter \IO Stream to \IO Stream with Headers
312+
313+
in_path = 't.csv'
314+
in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
315+
File.write(in_path, in_string)
316+
out_path = 'u.csv'
317+
File.open(in_path) do |in_io|
318+
File.open(out_path, 'w') do |out_io|
319+
CSV.filter(in_io, out_io, headers: true) do |row|
320+
row[0] = row[0].upcase
321+
row[1] *= 4
322+
end
323+
end
324+
end
325+
p File.read(out_path) # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"

0 commit comments

Comments
 (0)