ruby-changes:62297
From: Burdette <ko1@a...>
Date: Mon, 20 Jul 2020 03:35:48 +0900 (JST)
Subject: [ruby-changes:62297] da83401ba4 (master): [ruby/csv] Enhanced RDoc for filter (#149)
https://git.ruby-lang.org/ruby.git/commit/?id=da83401ba4 From da83401ba4813cd55d7d462ebfd78f0575ec4ce9 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Sun, 28 Jun 2020 16:25:31 -0500 Subject: [ruby/csv] Enhanced RDoc for filter (#149) * Enhanced RDoc for filter * Correct return values for ::filter, ::foreach, ::parse * Enhanced RDoc for filter * Remove "returns nil"s Co-authored-by: Sutou Kouhei <kou@c...> https://github.com/ruby/csv/commit/2c347f9a3d diff --git a/lib/csv.rb b/lib/csv.rb index 02ebdb9..8eb555e 100644 --- a/lib/csv.rb +++ b/lib/csv.rb @@ -769,33 +769,61 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L769 end end - # # :call-seq: - # filter( **options ) { |row| ... } - # filter( input, **options ) { |row| ... } - # filter( input, output, **options ) { |row| ... } - # - # This method is a convenience for building Unix-like filters for CSV data. - # Each row is yielded to the provided block which can alter it as needed. - # After the block returns, the row is appended to +output+ altered or not. - # - # The +input+ and +output+ arguments can be anything CSV::new() accepts - # (generally String or IO objects). If not given, they default to - # <tt>ARGF</tt> and <tt>$stdout</tt>. - # - # The +options+ parameter is also filtered down to CSV::new() after some - # clever key parsing. Any key beginning with <tt>:in_</tt> or - # <tt>:input_</tt> will have that leading identifier stripped and will only - # be used in the +options+ Hash for the +input+ object. Keys starting with - # <tt>:out_</tt> or <tt>:output_</tt> affect only +output+. All other keys - # are assigned to both objects. - # - # See {Options for Parsing}[#class-CSV-label-Options+for+Parsing] - # and {Options for Generating}[#class-CSV-label-Options+for+Generating]. - # - # The <tt>:output_row_sep</tt> +option+ defaults to - # <tt>$INPUT_RECORD_SEPARATOR</tt> (<tt>$/</tt>). + # filter(**options) {|row| ... } + # filter(in_string, **options) {|row| ... } + # filter(in_io, **options) {|row| ... } + # filter(in_string, out_string, **options) {|row| ... } + # filter(in_string, out_io, **options) {|row| ... } + # filter(in_io, out_string, **options) {|row| ... } + # filter(in_io, out_io, **options) {|row| ... } + # + # Reads \CSV input and writes \CSV output. + # + # For each input row: + # - Forms the data into: + # - A CSV::Row object, if headers are in use. + # - An \Array of Arrays, otherwise. + # - Calls the block with that object. + # - Appends the block's return value to the output. + # + # Arguments: + # * \CSV source: + # * Argument +in_string+, if given, should be a \String object; + # it will be put into a new StringIO object positioned at the beginning. + # * Argument +in_io+, if given, should be an IO object that is + # open for reading; on return, the IO object will be closed. + # * If neither +in_string+ nor +in_io+ is given, + # the input stream defaults to {ARGF}[https://ruby-doc.org/core/ARGF.html]. + # * \CSV output: + # * Argument +out_string+, if given, should be a \String object; + # it will be put into a new StringIO object positioned at the beginning. + # * Argument +out_io+, if given, should be an IO object that is + # ppen for writing; on return, the IO object will be closed. + # * If neither +out_string+ nor +out_io+ is given, + # the output stream defaults to <tt>$stdout</tt>. + # * Argument +options+ should be keyword arguments. + # - Each argument name that is prefixed with +in_+ or +input_+ + # is stripped of its prefix and is treated as an option + # for parsing the input. + # Option +input_row_sep+ defaults to <tt>$INPUT_RECORD_SEPARATOR</tt>. + # - Each argument name that is prefixed with +out_+ or +output_+ + # is stripped of its prefix and is treated as an option + # for generating the output. + # Option +output_row_sep+ defaults to <tt>$INPUT_RECORD_SEPARATOR</tt>. + # - Each argument not prefixed as above is treated as an option + # both for parsing the input and for generating the output. + # - See {Options for Parsing}[#class-CSV-label-Options+for+Parsing] + # and {Options for Generating}[#class-CSV-label-Options+for+Generating]. # + # Example: + # 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" def filter(input=nil, output=nil, **options) # parse options for input, output, or both in_options, out_options = Hash.new, {row_sep: $INPUT_RECORD_SEPARATOR} @@ -823,15 +851,14 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L851 # # :call-seq: - # foreach(path, mode='r', **options) {|row| ... ) -> integer or nil - # foreach(io, mode='r', **options {|row| ... ) -> integer or nil - # foreach(path, mode='r', headers: ..., **options) {|row| ... ) -> integer or nil - # foreach(io, mode='r', headers: ..., **options {|row| ... ) -> integer or nil + # foreach(path, mode='r', **options) {|row| ... ) + # foreach(io, mode='r', **options {|row| ... ) + # foreach(path, mode='r', headers: ..., **options) {|row| ... ) + # foreach(io, mode='r', headers: ..., **options {|row| ... ) # foreach(path, mode='r', **options) -> new_enumerator # foreach(io, mode='r', **options -> new_enumerator # # Calls the block with each row read from source +path+ or +io+. - # Returns an integer, or, if there were no rows, +nil+. # # * Argument +path+, if given, must be the path to a file. # :include: ../doc/arguments/io.rdoc @@ -860,7 +887,7 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L887 # File.write(path, string) # # Read rows from a file at +path+: - # CSV.foreach(path) {|row| p row } # => 21 + # CSV.foreach(path) {|row| p row } # Output: # ["foo", "0"] # ["bar", "1"] @@ -868,7 +895,7 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L895 # # Read rows from an \IO object: # File.open(path) do |file| - # CSV.foreach(file) {|row| p row } # => 21 + # CSV.foreach(file) {|row| p row } # end # # Output: @@ -881,7 +908,7 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L908 # CSV.foreach(File.open(path)) # => #<Enumerator: CSV:foreach(#<File:t.csv>, "r")> # # Issues a warning if an encoding is unsupported: - # CSV.foreach(File.open(path), encoding: 'foo:bar') {|row| } # => 21 + # CSV.foreach(File.open(path), encoding: 'foo:bar') {|row| } # Output: # warning: Unsupported encoding foo ignored # warning: Unsupported encoding bar ignored @@ -897,7 +924,7 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L924 # File.write(path, string) # # Read rows from a file at +path+: - # CSV.foreach(path, headers: true) {|row| p row } # => 21 + # CSV.foreach(path, headers: true) {|row| p row } # # Output: # #<CSV::Row "Name":"foo" "Count":"0"> @@ -906,7 +933,7 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L933 # # Read rows from an \IO object: # File.open(path) do |file| - # CSV.foreach(file, headers: true) {|row| p row } # => 21 + # CSV.foreach(file, headers: true) {|row| p row } # end # # Output: @@ -1167,8 +1194,8 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L1194 # parse(io) -> array_of_arrays # parse(string, headers: ..., **options) -> csv_table # parse(io, headers: ..., **options) -> csv_table - # parse(string, **options) {|row| ... } -> integer - # parse(io, **options) {|row| ... } -> integer + # parse(string, **options) {|row| ... } + # parse(io, **options) {|row| ... } # # Parses +string+ or +io+ using the specified +options+. # @@ -1179,7 +1206,7 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L1206 # # ====== Without Option +headers+ # - # Without option +headers+, returns an \Array of Arrays or an integer. + # Without {option +headers+}[#class-CSV-label-Option+headers] case. # # These examples assume prior execution of: # string = "foo,0\nbar,1\nbaz,2\n" @@ -1205,7 +1232,7 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L1232 # With a block given, calls the block with each parsed row: # # Parse a \String: - # CSV.parse(string) {|row| p row } # => 18 + # CSV.parse(string) {|row| p row } # # Output: # ["foo", "0"] @@ -1214,7 +1241,7 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L1241 # # Parse an open \File: # File.open(path) do |file| - # CSV.parse(file) {|row| p row } # => 18 + # CSV.parse(file) {|row| p row } # end # # Output: @@ -1224,8 +1251,7 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L1251 # # ====== With Option +headers+ # - # With {option +headers+}[#class-CSV-label-Option+headers], - # returns a new CSV::Table object or an integer. + # With {option +headers+}[#class-CSV-label-Option+headers] case. # # These examples assume prior execution of: # string = "Name,Count\nfoo,0\nbar,1\nbaz,2\n" @@ -1252,7 +1278,7 @@ class CSV https://github.com/ruby/ruby/blob/trunk/lib/csv.rb#L1278 # which has been formed into a CSV::Row object: # # Parse a \String: - # CSV.parse(string, headers: ['Name', 'Count']) {|row| p row } # => 18 + # CSV.parse(string, headers: ['Na (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/