8000 Enhanced RDoc for filter (#149) · ruby/csv@2c347f9 · GitHub
[go: up one dir, main page]
Skip to content

Commit 2c347f9

Browse files
BurdetteLamarkou
BurdetteLamar
and
kou
authored
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@clear-code.com>
1 parent 25dd4cd commit 2c347f9

File tree

1 file changed

+70
-44
lines changed

1 file changed

+70
-44
lines changed

‎lib/csv.rb

Lines changed: 70 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -769,33 +769,61 @@ def instance(data = $stdout, **options)
769769
end
770770
end
771771

772-
#
773772
# :call-seq:
774-
# filter( **options ) { |row| ... }
775-
# filter( input, **options ) { |row| ... }
776-
# filter( input, output, **options ) { |row| ... }
777-
#
778-
# This method is a convenience for building Unix-like filters for CSV data.
779-
# Each row is yielded to the provided block which can alter it as needed.
780-
# After the block returns, the row is appended to +output+ altered or not.
781-
#
782-
# The +input+ and +output+ arguments can be anything CSV::new() accepts
783-
# (generally String or IO objects). If not given, they default to
784-
# <tt>ARGF</tt> and <tt>$stdout</tt>.
785-
#
786-
# The +options+ parameter is also filtered down to CSV::new() after some
787-
# clever key parsing. Any key beginning with <tt>:in_</tt> or
788-
# <tt>:input_</tt> will have that leading identifier stripped and will only
789-
# be used in the +options+ Hash for the +input+ object. Keys starting with
790-
# <tt>:out_</tt> or <tt>:output_</tt> affect only +output+. All other keys
791-
# are assigned to both objects.
792-
#
793-
# See {Options for Parsing}[#class-CSV-label-Options+for+Parsing]
794-
# and {Options for Generating}[#class-CSV-label-Options+for+Generating].
795-
#
796-
# The <tt>:output_row_sep</tt> +option+ defaults to
797-
# <tt>$INPUT_RECORD_SEPARATOR</tt> (<tt>$/</tt>).
773+
# filter(**options) {|row| ... }
774+
# filter(in_string, **options) {|row| ... }
775+
# filter(in_io, **options) {|row| ... }
776+
# filter(in_string, out_string, **options) {|row| ... }
777+
# filter(in_string, out_io, **options) {|row| ... }
778+
# filter(in_io, out_string, **options) {|row| ... }
779+
# filter(in_io, out_io, **options) {|row| ... }
780+
#
781+
# Reads \CSV input and writes \CSV output.
782+
#
783+
# For each input row:
784+
# - Forms the data into:
785+
# - A CSV::Row object, if headers are in use.
786+
# - An \Array of Arrays, otherwise.
787+
# - Calls the block with that object.
788+
# - Appends the block's return value to the output.
789+
#
790+
# Arguments:
791+
# * \CSV source:
792+
# * Argument +in_string+, if given, should be a \String object;
793+
# it will be put into a new StringIO object positioned at the beginning.
794+
# * Argument +in_io+, if given, should be an IO object that is
795+
# open for reading; on return, the IO object will be closed.
796+
# * If neither +in_string+ nor +in_io+ is given,
797+
# the input stream defaults to {ARGF}[https://ruby-doc.org/core/ARGF.html].
798+
# * \CSV output:
799+
# * Argument +out_string+, if given, should be a \String object;
800+
# it will be put into a new StringIO object positioned at the beginning.
801+
# * Argument +out_io+, if given, should be an IO object that is
802+
# ppen for writing; on return, the IO object will be closed.
803+
# * If neither +out_string+ nor +out_io+ is given,
804+
# the output stream defaults to <tt>$stdout</tt>.
805+
# * Argument +options+ should be keyword arguments.
806+
# - Each argument name that is prefixed with +in_+ or +input_+
807+
# is stripped of its prefix and is treated as an option
808+
# for parsing the input.
809+
# Option +input_row_sep+ defaults to <tt>$INPUT_RECORD_SEPARATOR</tt>.
810+
# - Each argument name that is prefixed with +out_+ or +output_+
811+
# is stripped of its prefix and is treated as an option
812+
# for generating the output.
813+
# Option +output_row_sep+ defaults to <tt>$INPUT_RECORD_SEPARATOR</tt>.
814+
# - Each argument not prefixed as above is treated as an option
815+
# both for parsing the input and for generating the output.
816+
# - See {Options for Parsing}[#class-CSV-label-Options+for+Parsing]
817+
# and {Options for Generating}[#class-CSV-label-Options+for+Generating].
798818
#
819+
# Example:
820+
# in_string = "foo,0\nbar,1\nbaz,2\n"
821+
# out_string = ''
822+
# CSV.filter(in_string, out_string) do |row|
823+
# row[0] = row[0].upcase
824+
# row[1] *= 4
825+
# end
826+
# out_string # => "FOO,0000\nBAR,1111\nBAZ,2222\n"
799827
def filter(input=nil, output=nil, **options)
800828
# parse options for input, output, or both
801829
in_options, out_options = Hash.new, {row_sep: $INPUT_RECORD_SEPARATOR}
@@ -823,15 +851,14 @@ def filter(input=nil, output=nil, **options)
823851

824852
#
825853
# :call-seq:
826-
# foreach(path, mode='r', **options) {|row| ... ) -> integer or nil
827-
# foreach(io, mode='r', **options {|row| ... ) -> integer or nil
828-
# foreach(path, mode='r', headers: ..., **options) {|row| ... ) -> integer or nil
829-
# foreach(io, mode='r', headers: ..., **options {|row| ... ) -> integer or nil
854+
# foreach(path, mode='r', **options) {|row| ... )
855+
# foreach(io, mode='r', **options {|row| ... )
856+
# foreach(path, mode='r', headers: ..., **options) {|row| ... )
857+
# foreach(io, mode='r', headers: ..., **options {|row| ... )
830858
# foreach(path, mode='r', **options) -> new_enumerator
831859
# foreach(io, mode='r', **options -> new_enumerator
832860
#
833861
# Calls the block with each row read from source +path+ or +io+.
834-
# Returns an integer, or, if there were no rows, +nil+.
835862
#
836863
# * Argument +path+, if given, must be the path to a file.
837864
# :include: ../doc/arguments/io.rdoc
@@ -860,15 +887,15 @@ def filter(input=nil, output=nil, **options)
860887
# File.write(path, string)
861888
#
862889
# Read rows from a file at +path+:
863-
# CSV.foreach(path) {|row| p row } # => 21
890+
# CSV.foreach(path) {|row| p row }
864891
# Output:
865892
# ["foo", "0"]
866893
# ["bar", "1"]
867894
# ["baz", "2"]
868895
#
869896
# Read rows from an \IO object:
870897
# File.open(path) do |file|
871-
# CSV.foreach(file) {|row| p row } # => 21
898+
# CSV.foreach(file) {|row| p row }
872899
# end
873900
#
874901
# Output:
@@ -881,7 +908,7 @@ def filter(input=nil, output=nil, **options)
881908
# CSV.foreach(File.open(path)) # => #<Enumerator: CSV:foreach(#<File:t.csv>, "r")>
882909
#
883910
# Issues a warning if an encoding is unsupported:
884-
# CSV.foreach(File.open(path), encoding: 'foo:bar') {|row| } # => 21
911+
# CSV.foreach(File.open(path), encoding: 'foo:bar') {|row| }
885912
# Output:
886913
# warning: Unsupported encoding foo ignored
887914
# warning: Unsupported encoding bar ignored
@@ -897,7 +924,7 @@ def filter(input=nil, output=nil, **options)
897924
# File.write(path, string)
898925
#
899926
# Read rows from a file at +path+:
900-
# CSV.foreach(path, headers: true) {|row| p row } # => 21
927+
# CSV.foreach(path, headers: true) {|row| p row }
901928
#
902929
# Output:
903930
# #<CSV::Row "Name":"foo" "Count":"0">
@@ -906,7 +933,7 @@ def filter(input=nil, output=nil, **options)
906933
#
907934
# Read rows from an \IO object:
908935
# File.open(path) do |file|
909-
# CSV.foreach(file, headers: true) {|row| p row } # => 21
936+
# CSV.foreach(file, headers: true) {|row| p row }
910937
# end
911938
#
912939
# Output:
@@ -1167,8 +1194,8 @@ def open(filename, mode="r", **options)
11671194
# parse(io) -> array_of_arrays
11681195
# parse(string, headers: ..., **options) -> csv_table
11691196
# parse(io, headers: ..., **options) -> csv_table
1170-
# parse(string, **options) {|row| ... } -> integer
1171-
# parse(io, **options) {|row| ... } -> integer
1197+
# parse(string, **options) {|row| ... }
1198+
# parse(io, **options) {|row| ... }
11721199
#
11731200
# Parses +string+ or +io+ using the specified +options+.
11741201
#
@@ -1179,7 +1206,7 @@ def open(filename, mode="r", **options)
11791206
#
11801207
# ====== Without Option +headers+
11811208
#
1182-
# Without option +headers+, returns an \Array of Arrays or an integer.
1209+
# Without {option +headers+}[#class-CSV-label-Option+headers] case.
11831210
#
11841211
# These examples assume prior execution of:
11851212
# string = "foo,0\nbar,1\nbaz,2\n"
@@ -1205,7 +1232,7 @@ def open(filename, mode="r", **options)
12051232
# With a block given, calls the block with each parsed row:
12061233
#
12071234
# Parse a \String:
1208-
# CSV.parse(string) {|row| p row } # => 18
1235+
# CSV.parse(string) {|row| p row }
12091236
#
12101237
# Output:
12111238
# ["foo", "0"]
@@ -1214,7 +1241,7 @@ def open(filename, mode="r", **options)
12141241
#
12151242
# Parse an open \File:
12161243
# File.open(path) do |file|
1217-
# CSV.parse(file) {|row| p row } # => 18
1244+
# CSV.parse(file) {|row| p row }
12181245
# end
12191246
#
12201247
# Output:
@@ -1224,8 +1251,7 @@ def open(filename, mode="r", **options)
12241251
#
12251252
# ====== With Option +headers+
12261253
#
1227-
# With {option +headers+}[#class-CSV-label-Option+headers],
1228-
# returns a new CSV::Table object or an integer.
1254+
# With {option +headers+}[#class-CSV-label-Option+headers] case.
12291255
#
12301256
# These examples assume prior execution of:
12311257
# string = "Name,Count\nfoo,0\nbar,1\nbaz,2\n"
@@ -1252,7 +1278,7 @@ def open(filename, mode="r", **options)
12521278
# which has been formed into a CSV::Row object:
12531279
#
12541280
# Parse a \String:
1255-
# CSV.parse(string, headers: ['Name', 'Count']) {|row| p row } # => 18
1281+
# CSV.parse(string, headers: ['Name', 'Count']) {|row| p row }
12561282
#
12571283
# Output:
12581284
# # <CSV::Row "Name":"foo" "Count":"0">
@@ -1261,7 +1287,7 @@ def open(filename, mode="r", **options)
12611287
#
12621288
# Parse an open \File:
12631289
# File.open(path) do |file|
1264-
# CSV.parse(file, headers: ['Name', 'Count']) {|row| p row } # => 18
1290+
# CSV.parse(file, headers: ['Name', 'Count']) {|row| p row }
12651291
# end
12661292
#
12671293
# Output:

0 commit comments

Comments
 (0)
0