ruby-changes:62298
From: Burdette <ko1@a...>
Date: Mon, 20 Jul 2020 03:35:50 +0900 (JST)
Subject: [ruby-changes:62298] 7c55c96147 (master): [ruby/csv] Rdoc (#137)
https://git.ruby-lang.org/ruby.git/commit/?id=7c55c96147 From 7c55c961475619126cfb45331ac7a0724f99a536 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Sat, 13 Jun 2020 13:26:30 -0500 Subject: [ruby/csv] Rdoc (#137) Enhancements for open, parse, minor tweaks. https://github.com/ruby/csv/commit/35392f4e45 diff --git a/lib/csv.rb b/lib/csv.rb index bc9cfaf..65f31a6 100644 --- a/lib/csv.rb +++ b/lib/csv.rb @@ -832,7 +832,7 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L832 # Returns an integer, or, if there were no rows, +nil+. # # * Argument +path+, if given, must be the path to a file. - # * Argument +io+, if given, must be an \IO object opened for reading. + # :include: ../doc/argument_io.rdoc # * Argument +mode+, if given, must be a \File mode # See {Open Mode}[IO.html#method-c-new-label-Open+Mode]. # * Arguments <tt>**options</tt> must be keyword options. @@ -854,7 +854,6 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L854 # string = "foo,0\nbar,1\nbaz,2\n" # path = 't.csv' # File.write(path, string) - # io = File.open(path) # # Read rows from a file at +path+: # CSV.foreach(path) {|row| p row } # => 21 @@ -864,7 +863,7 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L863 # ["baz", "2"] # # Read rows from an \IO object: - # CSV.foreach(io) {|row| p row } # => 21 + # CSV.foreach(File.open(path)) {|row| p row } # => 21 # Output: # ["foo", "0"] # ["bar", "1"] @@ -872,10 +871,10 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L871 # # Returns a new \Enumerator if no block given: # CSV.foreach(path) # => #<Enumerator: CSV:foreach("t.csv", "r")> - # CSV.foreach(io) # => #<Enumerator: CSV:foreach(#<File:t.csv>, "r")> + # CSV.foreach(File.open(path)) # => #<Enumerator: CSV:foreach(#<File:t.csv>, "r")> # # Issues a warning if an encoding is unsupported: - # CSV.foreach(io, encoding: 'foo:bar') {|row| } # => 21 + # CSV.foreach(File.open(path), encoding: 'foo:bar') {|row| } # => 21 # Output: # warning: Unsupported encoding foo ignored # warning: Unsupported encoding bar ignored @@ -892,8 +891,8 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L891 # CSV.foreach(io) {|row| } # # Raises an exception if +mode+ is invalid: - # # Raises IOError (not opened for reading): - # CSV.foreach(path, 'w') {|row| } + # # Raises ArgumentError (invalid access mode nosuch): + # CSV.foreach(path, 'nosuch') {|row| } # def foreach(path, mode="r", **options, &block) return to_enum(__method__, path, mode, **options) unless block_given? @@ -1022,10 +1021,10 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L1021 # # :call-seq: - # open( filename, mode = "rb", **options ) { |faster_csv| ... } - # open( filename, **options ) { |faster_csv| ... } - # open( filename, mode = "rb", **options ) - # open( filename, **options ) + # open(file_path, mode = "rb", **options ) -> new_csv + # open(io, mode = "rb", **options ) -> new_csv + # open(file_path, mode = "rb", **options ) { |csv| ... } -> new_csv + # open(io, mode = "rb", **options ) { |csv| ... } -> new_csv # # possible options elements: # hash form: @@ -1034,28 +1033,63 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L1033 # :undef => :replace # replace undefined conversion # :replace => string # replacement string ("?" or "\uFFFD" if not specified) # - # This method opens an IO object, and wraps that with CSV. This is intended - # as the primary interface for writing a CSV file. + # * Argument +path+, if given, must be the path to a file. + # :include: ../doc/argument_io.rdoc + # * Argument +mode+, if given, must be a \File mode + # See {Open Mode}[IO.html#method-c-new-label-Open+Mode]. + # * Arguments <tt>**options</tt> must be keyword options. + # See {Options for Generating}[#class-CSV-label-Options+for+Generating]. + # * This method optionally accepts an additional <tt>:encoding</tt> option + # that you can use to specify the Encoding of the data read from +path+ or +io+. + # You must provide this unless your data is in the encoding + # given by <tt>Encoding::default_external</tt>. + # Parsing will use this to determine how to parse the data. + # You may provide a second Encoding to + # have the data transcoded as it is read. For example, + # encoding: 'UTF-32BE:UTF-8' + # would read +UTF-32BE+ data from the file + # but transcode it to +UTF-8+ before parsing. # - # You must pass a +filename+ and may optionally add a +mode+ for Ruby's - # open(). + # --- # - # See {Options for Parsing}[#class-CSV-label-Options+for+Parsing]. + # These examples assume prior execution of: + # string = "foo,0\nbar,1\nbaz,2\n" + # path = 't.csv' + # File.write(path, string) + # + # --- + # + # With no block given, returns a new \CSV object. + # + # Create a \CSV object using a file path: + # csv = CSV.open(path) + # csv # => #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\r\n" quote_char:"\""> # - # This method works like Ruby's open() call, in that it will pass a CSV object - # to a provided block and close it when the block terminates, or it will - # return the CSV object when no block is provided. (*Note*: This is different - # from the Ruby 1.8 CSV library which passed rows to the block. Use - # CSV::foreach() for that behavior.) + # Create a \CSV object using an open \File: + # csv = CSV.open(File.open(path)) + # csv # => #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\r\n" quote_char:"\""> + # + # --- + # + # With a block given, calls the block with the created \CSV object: + # + # Using a file path: + # csv = CSV.open(path) {|csv| p csv} + # csv # => #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\r\n" quote_char:"\""> + # Output: + # #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\r\n" quote_char:"\""> + # + # Using an open \File: + # csv = CSV.open(File.open(path)) {|csv| p csv} + # csv # => #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\r\n" quote_char:"\""> + # Output: + # #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\r\n" quote_char:"\""> # - # You must provide a +mode+ with an embedded Encoding designator unless your - # data is in Encoding::default_external(). CSV will check the Encoding of the - # underlying IO object (set by the +mode+ you pass) to determine how to parse - # the data. You may provide a second Encoding to have the data transcoded as - # it is read just as you can with a normal call to IO::open(). For example, - # <tt>"rb:UTF-32BE:UTF-8"</tt> would read UTF-32BE data from the file but - # transcode it to UTF-8 before CSV parses it. + # --- # + # Raises an exception if the argument is not a \String object or \IO object: + # # Raises TypeError (no implicit conversion of Symbol into String) + # CSV.open(:foo) def open(filename, mode="r", **options) # wrap a File opened with the remaining +args+ with no newline # decorator @@ -1093,16 +1127,60 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L1127 # # :call-seq: - # parse( str, **options ) { |row| ... } - # parse( str, **options ) + # parse(string) -> array_of_arrays + # parse(io) -> array_of_arrays + # parse(string, **options) {|row| ... } -> integer + # parse(io, **options) {|row| ... } -> integer # - # This method can be used to easily parse CSV out of a String. You may either - # provide a +block+ which will be called with each row of the String in turn, - # or just use the returned Array of Arrays (when no +block+ is given). + # Parses +string+ or +io+ using the specified +options+. # - # You pass your +str+ to read from, and an optional +options+. - # See {Options for Parsing}[#class-CSV-label-Options+for+Parsing]. + # - Argument +string+ should be a \String object; + # it will be put into a new StringIO object positioned at the beginning. + # :include: ../doc/argument_io.rdoc + # - Argument +options+: see {Options for Parsing}[#class-CSV-label-Options+for+Parsing] + # + # These examples assume prior execution of: + # string = "foo,0\nbar,1\nbaz,2\n" + # path = 't.csv' + # File.write(path, string) + # + # --- + # + # With no block given, returns an \Array of Arrays formed from the source. + # + # Parse a \String: + # a_of_a = CSV.parse(string) + # a_of_a # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] + # + # Parse an open \File: + # a_of_a = CSV.parse(File.open(path)) + # a_of_a # => [["foo", "0"], ["bar", "1"], ["baz", "2"]] + # + # --- + # + # With a block given, calls the block with each parsed row: + # + # Parse a \String: + # CSV.parse(string) {|row| p row } # => 18 + # + # Output: + # ["foo", "0"] + # ["bar", "1"] + # ["baz", "2"] + # + # Parse an open \File: + # CSV.parse(File.open(path)) {|row| p row } # => 18 + # + # Output: + # ["foo", "0"] + # ["bar", "1"] + # ["baz", "2"] + # + # --- # + # Raises an exception if the argument is not a \String object or \IO object: + # # Raises NoMethodError (undefined method `close' for :foo:Symbol) + # CSV.parse(:foo) def parse(str, **options, &block) csv = new(str, **options) @@ -1127,11 +1205 (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/