ruby-changes:63720
From: Burdette <ko1@a...>
Date: Tue, 24 Nov 2020 09:34:27 +0900 (JST)
Subject: [ruby-changes:63720] 4641a9a92b (master): [ruby/csv] Emphasize with-headers over without-headers in recipes (#180)
https://git.ruby-lang.org/ruby.git/commit/?id=4641a9a92b From 4641a9a92b449e2e9d4cbc91a93de27f98396a96 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Thu, 1 Oct 2020 17:00:24 -0500 Subject: [ruby/csv] Emphasize with-headers over without-headers in recipes (#180) https://github.com/ruby/csv/commit/c7bbedd28a diff --git a/doc/csv/recipes.rdoc b/doc/csv/recipes.rdoc index be75ded..816f933 100644 --- a/doc/csv/recipes.rdoc +++ b/doc/csv/recipes.rdoc @@ -7,14 +7,14 @@ All code snippets on this page assume that the following has been executed: https://github.com/ruby/ruby/blob/trunk/doc/csv/recipes.rdoc#L7 - {Parsing: Source Formats}[#label-Parsing-3A+Source+Formats] - {Parse from String}[#label-Parse+from+String] - - {Parse from String Without Headers}[#label-Parse+from+String+Without+Headers] - {Parse from String with Headers}[#label-Parse+from+String+with+Headers] + - {Parse from String Without Headers}[#label-Parse+from+String+Without+Headers] - {Parse from File}[#label-Parse+from+File] - - {Parse from File Without Headers}[#label-Parse+from+File+Without+Headers] - {Parse from File with Headers}[#label-Parse+from+File+with+Headers] + - {Parse from File Without Headers}[#label-Parse+from+File+Without+Headers] - {Parse from IO Stream}[#label-Parse+from+IO+Stream] - - {Parse from IO Stream Without Headers}[#label-Parse+from+IO+Stream+Without+Headers] - {Parse from IO Stream with Headers}[#label-Parse+from+IO+Stream+with+Headers] + - {Parse from IO Stream Without Headers}[#label-Parse+from+IO+Stream+Without+Headers] - {Parsing: Field Converters}[#label-Parsing-3A+Field+Converters] - {Convert Fields to Objects}[#label-Convert+Fields+to+Objects] - {Convert Fields to Objects Using Built-In Converters}[#label-Convert+Fields+to+Objects+Using+Built-In+Converters] @@ -22,48 +22,32 @@ All code snippets on this page assume that the following has been executed: https://github.com/ruby/ruby/blob/trunk/doc/csv/recipes.rdoc#L22 - {Filter Field Strings}[#label-Filter+Field+Strings] - {Generating: Output Formats}[#label-Generating-3A+Output+Formats] - {Generate to String}[#label-Generate+to+String] - - {Generate to String Without Headers}[#label-Generate+to+String+Without+Headers] - {Generate to String with Headers}[#label-Generate+to+String+with+Headers] + - {Generate to String Without Headers}[#label-Generate+to+String+Without+Headers] - {Generate to File}[#label-Generate+to+File] - - {Generate to File Without Headers}[#label-Generate+to+File+Without+Headers] - {Generate to File with Headers}[#label-Generate+to+File+with+Headers] + - {Generate to File Without Headers}[#label-Generate+to+File+Without+Headers] - {Generate to IO Stream}[#label-Generate+to+IO+Stream] - - {Generate to IO Stream Without Headers}[#label-Generate+to+IO+Stream+Without+Headers] - {Generate to IO Stream with Headers}[#label-Generate+to+IO+Stream+with+Headers] + - {Generate to IO Stream Without Headers}[#label-Generate+to+IO+Stream+Without+Headers] - {Filtering: Source and Output Formats}[#label-Filtering-3A+Source+and+Output+Formats] - {Filter String to String}[#label-Filter+String+to+String] - - {Filter String to String Without Headers}[#label-Filter+String+to+String+Without+Headers] - {Filter String to String with Headers}[#label-Filter+String+to+String+with+Headers] + - {Filter String to String Without Headers}[#label-Filter+String+to+String+Without+Headers] - {Filter String to IO Stream}[#label-Filter+String+to+IO+Stream] - - {Filter String to IO Stream Without Headers}[#label-Filter+String+to+IO+Stream+Without+Headers] - {Filter String to IO Stream with Headers}[#label-Filter+String+to+IO+Stream+with+Headers] + - {Filter String to IO Stream Without Headers}[#label-Filter+String+to+IO+Stream+Without+Headers] - {Filter IO Stream to String}[#label-Filter+IO+Stream+to+String] - - {Filter IO Stream to String Without Headers}[#label-Filter+IO+Stream+to+String+Without+Headers] - {Filter IO Stream to String with Headers}[#label-Filter+IO+Stream+to+String+with+Headers] + - {Filter IO Stream to String Without Headers}[#label-Filter+IO+Stream+to+String+Without+Headers] - {Filter IO Stream to IO Stream}[#label-Filter+IO+Stream+to+IO+Stream] - - {Filter IO Stream to IO Stream Without Headers}[#label-Filter+IO+Stream+to+IO+Stream+Without+Headers] - {Filter IO Stream to IO Stream with Headers}[#label-Filter+IO+Stream+to+IO+Stream+with+Headers] + - {Filter IO Stream to IO Stream Without Headers}[#label-Filter+IO+Stream+to+IO+Stream+Without+Headers] === Parsing: Source Formats ==== Parse from \String -===== Parse from \String Without Headers - -\Class method CSV.parse can read a source \String all at once, -and so may have memory resource implications: - string = "foo,0\nbar,1\nbaz,2\n" - CSV.parse(string) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] - -Instance method CSV#each can read a source \String one row at a time: - CSV.new(string).each do |row| - p row - end -Output: - ["foo", "0"] - ["bar", "1"] - ["baz", "2"] - ===== Parse from \String with Headers \Class method CSV.parse can read a source \String all at once, @@ -80,18 +64,15 @@ Ouput: https://github.com/ruby/ruby/blob/trunk/doc/csv/recipes.rdoc#L64 #<CSV::Row "Name":"bar" "Value":"1"> #<CSV::Row "Name":"baz" "Value":"2"> -==== Parse from \File - -===== Parse from \File Without Headers +===== Parse from \String Without Headers -\Class method CSV.read can read a file all at once: +\Class method CSV.parse can read a source \String all at once, +and so may have memory resource implications: string = "foo,0\nbar,1\nbaz,2\n" - path = 't.csv' - File.write(path, string) - CSV.read(path) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] + CSV.parse(string) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] -\Class method CSV.foreach can read one row at a time: - CSV.foreach(path) do |row| +Instance method CSV#each can read a source \String one row at a time: + CSV.new(string).each do |row| p row end Output: @@ -99,6 +80,8 @@ Output: https://github.com/ruby/ruby/blob/trunk/doc/csv/recipes.rdoc#L80 ["bar", "1"] ["baz", "2"] +==== Parse from \File + ===== Parse from \File with Headers Instance method CSV#read can reada file all at once: @@ -116,29 +99,25 @@ Output: https://github.com/ruby/ruby/blob/trunk/doc/csv/recipes.rdoc#L99 #<CSV::Row "Name":"bar" "Value":"1"> #<CSV::Row "Name":"baz" "Value":"2"> -==== Parse from \IO Stream - -===== Parse from \IO Stream Without Headers +===== Parse from \File Without Headers -\Class method CSV.parse can read an \IO stream all at once: +\Class method CSV.read can read a file all at once: string = "foo,0\nbar,1\nbaz,2\n" path = 't.csv' File.write(path, string) - File.open(path) do |file| - CSV.parse(file) - end # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] + CSV.read(path) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] \Class method CSV.foreach can read one row at a time: - File.open(path) do |file| - CSV.foreach(file) do |row| - p row - end + CSV.foreach(path) do |row| + p row end Output: ["foo", "0"] ["bar", "1"] ["baz", "2"] +==== Parse from \IO Stream + ===== Parse from \IO Stream with Headers \Class method CSV.parse can read an \IO stream all at once: @@ -160,6 +139,27 @@ Output: https://github.com/ruby/ruby/blob/trunk/doc/csv/recipes.rdoc#L139 #<CSV::Row "Name":"bar" "Value":"1"> #<CSV::Row "Name":"baz" "Value":"2"> +===== Parse from \IO Stream Without Headers + +\Class method CSV.parse can read an \IO stream all at once: + string = "foo,0\nbar,1\nbaz,2\n" + path = 't.csv' + File.write(path, string) + File.open(path) do |file| + CSV.parse(file) + end # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] + +\Class method CSV.foreach can read one row at a time: + File.open(path) do |file| + CSV.foreach(file) do |row| + p row + end + end +Output: + ["foo", "0"] + ["bar", "1"] + ["baz", "2"] + === Parsing: Field Converters ==== Convert Fields to Objects @@ -235,19 +235,6 @@ You can also register a custom field converter, then refer to it by name: https://github.com/ruby/ruby/blob/trunk/doc/csv/recipes.rdoc#L235 === Generating: Output Formats -==== Generate to \String Without Headers - -\Class method CSV.generate can 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" - ==== Generate to \String ===== Generate to \String with Headers @@ -263,19 +250,18 @@ that are to be generated: https://github.com/ruby/ruby/blob/trunk/doc/csv/recipes.rdoc#L250 end output_string # => "Name,Value\nFoo,0\nBar,1\nBaz,2\n" -===== Generate to \File Without Headers +===== Generate to \String Without Headers -\Class method CSV.open can generate to a \File. +\Class method CSV.generate can generate to a \String. This example uses method CSV#<< to append the rows that are to be generated: - path = 't.csv' - CSV.open(path, 'w') do |csv| + output_string = CSV.generate do |csv| csv << ['Foo', 0] csv << ['Bar', 1] csv << ['Baz', 2] end - p File.read(path) # => "Foo,0\nBar,1\nBaz,2\n" + output_string # => "Foo,0\nBar,1\nBaz,2\n" ==== Generate to \File @@ -293,20 +279,22 @@ that are to be generated: https://github.com/ruby/ruby/blob/trunk/doc/csv/recipes.rdoc#L279 end p File.read(path) # => "Name,Value\nFoo,0\nBar,1\nBaz,2\n" -==== Generate to \IO Stream +===== Generate to \File Without Headers -===== Generate to \IO Stream Without Headers +\Class method CSV.open can generate to a \File. -\Class method CSV.new can generate \CSV data to an \IO stream: +This example uses method CSV#<< to append the rows +that are to be generated: path = 't.csv' - Fi (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/