csv 3.1.7 → 3.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c834580f6d364830ddcd85b07edcb44fc91520fd594492a835cb57f43f145c94
-  data.tar.gz: 989310760b22148eeb70be9181a39c2d08c8040f7e79fd6a06dc7586409c4e7f
+  metadata.gz: 9a9f965a5db6ac6d07f525f513e212f082c137b487d73328373d0afef7bb8312
+  data.tar.gz: 5184ad5878a6dee8603e3b48fc820b50e3687eafb96cbcec152a8d621ceaffd6
 SHA512:
-  metadata.gz: 75859dd4eff126ab15bf372305da6eeb638ce1927186931f3ea87fe00c0a769c8adb38cb786b8ee3f7fd418de720d26fe01fba9ca28ac565bbd761431057cec8
-  data.tar.gz: 56b5de70961f3e9792296e6b68941fa1ea1e1eaa5ad2811ae47954a775c986d8f9455af50e5e6d25deb797794b697cef0e0c4a87695dc3a42d9fa477008d85dc
+  metadata.gz: 422a1a8751e4e8c21884848e7f465e39090b946c3febff711bb756c98e61b7e6aebf0e552adee851d653f89e9ef2772984db2b05a243c7fac8060c64def34ae0
+  data.tar.gz: 9d85fa756cd744e74da2ae1e89650768370566a5fd8ce1830337d528f9875d07422508eb007522ae3e7ec9c20c9ec055983f09c9b951e78441706bb2d33fdd59

data/NEWS.md

@@ -1,5 +1,16 @@
 # News
 
+## 3.1.8 - 2020-11-18
+
+### Improvements
+
+  * Improved documentation.
+    [Patch by Burdette Lamar]
+
+### Thanks
+
+  * Burdette Lamar
+
 ## 3.1.7 - 2020-08-04
 
 ### Improvements

data/README.md

@@ -31,6 +31,11 @@ CSV.foreach("path/to/file.csv") do |row|
 end
 ```
 
+## Documentation
+
+- {API}[CSV.html]:  all classes, methods, and constants.
+- {Recipes}[doc/csv/recipes/recipes_rdoc.html]:  specific code for specific tasks.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/doc/csv/options/common/col_sep.rdoc

@@ -1,6 +1,6 @@
 ====== Option +col_sep+
 
-Specifies the \String field separator to be used
+Specifies the \String column separator to be used
 for both parsing and generating.
 The \String will be transcoded into the data's \Encoding before use.
 
@@ -55,9 +55,3 @@ Raises an exception if parsing with the empty \String:
   # Raises ArgumentError (:col_sep must be 1 or more characters: "")
   CSV.parse("foo0\nbar1\nbaz2\n", col_sep: col_sep)
 
-Raises an exception if the given value is not String-convertible:
-  col_sep = BasicObject.new
-  # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
-  CSV.generate(line, col_sep: col_sep)
-  # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
-  CSV.parse(str, col_sep: col_sep)

data/doc/csv/options/common/row_sep.rdoc

@@ -89,12 +89,3 @@ if any of the following is true:
 * The stream is only available for output.
 
 Obviously, discovery takes a little time. Set manually if speed is important. Also note that IO objects should be opened in binary mode on Windows if this feature will be used as the line-ending translation can cause problems with resetting the document position to where it was before the read ahead.
-
----
-
-Raises an exception if the given value is not String-convertible:
-  row_sep = BasicObject.new
-  # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
-  CSV.generate(ary, row_sep: row_sep)
-  # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
-  CSV.parse(str, row_sep: row_sep)

data/doc/csv/options/generating/write_converters.rdoc

@@ -23,11 +23,3 @@ With two write converters (called in order):
   str # => "a,b,c\n"
 
 See also {Write Converters}[#class-CSV-label-Write+Converters]
-
----
-
-Raises an exception if the converter returns a value that is neither +nil+
-nor \String-convertible:
-  bad_converter = proc {|field| BasicObject.new }
-  # Raises NoMethodError (undefined method `is_a?' for #<BasicObject:>)
-  CSV.generate_line(['a', 'b', 'c'], write_converters: bad_converter)

data/doc/csv/recipes/filtering.rdoc

@@ -0,0 +1,158 @@
+== Recipes for Filtering \CSV
+
+These recipes are specific code examples for specific \CSV filtering tasks.
+
+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
+
+- {Source and Output Formats}[#label-Source+and+Output+Formats]
+  - {Filtering String to String}[#label-Filtering+String+to+String]
+    - {Recipe: Filter String to String with Headers}[#label-Recipe-3A+Filter+String+to+String+with+Headers]
+    - {Recipe: Filter String to String Without Headers}[#label-Recipe-3A+Filter+String+to+String+Without+Headers]
+  - {Filtering String to IO Stream}[#label-Filtering+String+to+IO+Stream]
+    - {Recipe: Filter String to IO Stream with Headers}[#label-Recipe-3A+Filter+String+to+IO+Stream+with+Headers]
+    - {Recipe: Filter String to IO Stream Without Headers}[#label-Recipe-3A+Filter+String+to+IO+Stream+Without+Headers]
+  - {Filtering IO Stream to String}[#label-Filtering+IO+Stream+to+String]
+    - {Recipe: Filter IO Stream to String with Headers}[#label-Recipe-3A+Filter+IO+Stream+to+String+with+Headers]
+    - {Recipe: Filter IO Stream to String Without Headers}[#label-Recipe-3A+Filter+IO+Stream+to+String+Without+Headers]
+  - {Filtering IO Stream to IO Stream}[#label-Filtering+IO+Stream+to+IO+Stream]
+    - {Recipe: Filter IO Stream to IO Stream with Headers}[#label-Recipe-3A+Filter+IO+Stream+to+IO+Stream+with+Headers]
+    - {Recipe: Filter IO Stream to IO Stream Without Headers}[#label-Recipe-3A+Filter+IO+Stream+to+IO+Stream+Without+Headers]
+
+=== Source and Output Formats
+
+You can use a Unix-style "filter" for \CSV data.
+The filter reads source \CSV data and writes output \CSV data as modified by the filter.
+The input and output \CSV data may be any mixture of \Strings and \IO streams.
+
+==== Filtering \String to \String
+
+You can filter one \String to another, with or without headers.
+
+===== Recipe: Filter \String to \String with Headers
+
+Use class method CSV.filter with option +headers+ to filter a \String to another \String:
+  in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  out_string = ''
+  CSV.filter(in_string, out_string, headers: true) do |row|
+    row[0] = row[0].upcase
+    row[1] *= 4
+  end
+  out_string # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"
+
+===== Recipe: Filter \String to \String Without Headers
+
+Use class method CSV.filter without option +headers+ to filter a \String to another \String:
+  in_string = "foo,0\nbar,1\nbaz,2\n"
+  out_string = ''
+  CSV.filter(in_string, out_string) do |row|
+    row[0] = row[0].upcase
+    row[1] *= 4
+  end
+  out_string # => "FOO,0000\nBAR,1111\nBAZ,2222\n"
+
+==== Filtering \String to \IO Stream
+
+You can filter a \String to an \IO stream, with or without headers.
+
+===== Recipe: Filter \String to \IO Stream with Headers
+
+Use class method CSV.filter with option +headers+ to filter a \String to an \IO stream:
+  in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  path = 't.csv'
+  File.open(path, 'w') do |out_io|
+    CSV.filter(in_string, out_io, headers: true) do |row|
+      row[0] = row[0].upcase
+      row[1] *= 4
+    end
+  end
+  p File.read(path) # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"
+
+===== Recipe: Filter \String to \IO Stream Without Headers
+
+Use class method CSV.filter without option +headers+ to filter a \String to an \IO stream:
+  in_string = "foo,0\nbar,1\nbaz,2\n"
+  path = 't.csv'
+  File.open(path, 'w') do |out_io|
+    CSV.filter(in_string, out_io) do |row|
+      row[0] = row[0].upcase
+      row[1] *= 4
+    end
+  end
+  p File.read(path) # => "FOO,0000\nBAR,1111\nBAZ,2222\n"
+
+==== Filtering \IO Stream to \String
+
+You can filter an \IO stream to a \String, with or without headers.
+
+===== Recipe: Filter \IO Stream to \String with Headers
+
+Use class method CSV.filter with option +headers+ to filter an \IO stream to a \String:
+  in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  path = 't.csv'
+  File.write(path, in_string)
+  out_string = ''
+  File.open(path, headers: true) do |in_io|
+    CSV.filter(in_io, out_string, headers: true) do |row|
+      row[0] = row[0].upcase
+      row[1] *= 4
+    end
+  end
+  out_string # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"
+
+===== Recipe: Filter \IO Stream to \String Without Headers
+
+Use class method CSV.filter without option +headers+ to filter an \IO stream to a \String:
+  in_string = "foo,0\nbar,1\nbaz,2\n"
+  path = 't.csv'
+  File.write(path, in_string)
+  out_string = ''
+  File.open(path) do |in_io|
+    CSV.filter(in_io, out_string) do |row|
+      row[0] = row[0].upcase
+      row[1] *= 4
+    end
+  end
+  out_string # => "FOO,0000\nBAR,1111\nBAZ,2222\n"
+
+==== Filtering \IO Stream to \IO Stream
+
+You can filter an \IO stream to another \IO stream, with or without headers.
+
+===== Recipe: Filter \IO Stream to \IO Stream with Headers
+
+Use class method CSV.filter with option +headers+ to filter an \IO stream to another \IO stream:
+  in_path = 't.csv'
+  in_string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  File.write(in_path, in_string)
+  out_path = 'u.csv'
+  File.open(in_path) do |in_io|
+    File.open(out_path, 'w') do |out_io|
+      CSV.filter(in_io, out_io, headers: true) do |row|
+        row[0] = row[0].upcase
+        row[1] *= 4
+      end
+    end
+  end
+  p File.read(out_path) # => "Name,Value\nFOO,0000\nBAR,1111\nBAZ,2222\n"
+
+===== Recipe: Filter \IO Stream to \IO Stream Without Headers
+
+Use class method CSV.filter without option +headers+ to filter an \IO stream to another \IO stream:
+  in_path = 't.csv'
+  in_string = "foo,0\nbar,1\nbaz,2\n"
+  File.write(in_path, in_string)
+  out_path = 'u.csv'
+  File.open(in_path) do |in_io|
+    File.open(out_path, 'w') do |out_io|
+      CSV.filter(in_io, out_io) do |row|
+        row[0] = row[0].upcase
+        row[1] *= 4
+      end
+    end
+  end
+  p File.read(out_path) # => "FOO,0000\nBAR,1111\nBAZ,2222\n"

data/doc/csv/recipes/generating.rdoc

@@ -0,0 +1,298 @@
+== Recipes for Generating \CSV
+
+These recipes are specific code examples for specific \CSV generating tasks.
+
+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]
+  - {Quotes}[#label-Quotes]
+    - {Recipe: Quote All Fields}[#label-Recipe-3A+Quote+All+Fields]
+    - {Recipe: Quote Empty Fields}[#label-Recipe-3A+Quote+Empty+Fields]
+    - {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"
+
+==== Quotes
+
+IFC 4180 allows most fields to be quoted or not.
+By default, \CSV does not quote most fields.
+
+However, a field containing the current row separator, column separator,
+or quote character is automatically quoted, producing IFC 4180 compliance:
+  # Field contains row separator.
+  output_string = CSV.generate('') do |csv|
+    row_sep = csv.row_sep
+    csv << ["Foo#{row_sep}Foo", 0]
+    csv << ['Bar', 1]
+    csv << ['Baz', 2]
+  end
+  output_string # => "\"Foo\nFoo\",0\nBar,1\nBaz,2\n"
+  # Field contains column separator.
+  output_string = CSV.generate('') do |csv|
+    col_sep = csv.col_sep
+    csv << ["Foo#{col_sep}Foo", 0]
+    csv << ['Bar', 1]
+    csv << ['Baz', 2]
+  end
+  output_string # => "\"Foo,Foo\",0\nBar,1\nBaz,2\n"
+  # Field contains quote character.
+  output_string = CSV.generate('') do |csv|
+    quote_char = csv.quote_char
+    csv << ["Foo#{quote_char}Foo", 0]
+    csv << ['Bar', 1]
+    csv << ['Baz', 2]
+  end
+  output_string # => "\"Foo\"\"Foo\",0\nBar,1\nBaz,2\n"
+
+===== Recipe: Quote All Fields
+
+Use option +:force_quotes+ to force quoted fields:
+  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: Quote Empty Fields
+
+Use option +:quote_empty+ to force quoting for empty fields:
+  output_string = CSV.generate('', quote_empty: true) do |csv|
+    csv << ['Foo', 0]
+    csv << ['Bar', 1]
+    csv << ['', 2]
+  end
+  output_string # => "Foo,0\nBar,1\n\"\",2\n"
+
+===== Recipe: Generate Compliant Quote Character
+
+RFC 4180 specifies quote character DQUOTE (Ruby <tt>"\""</tt>).
+
+Because the \CSV default quote character is also <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"