Skip to content

Commit 35392f4

Browse files
BurdetteLamarBurdetteLamar
authored
Rdoc (#137)
Enhancements for open, parse, minor tweaks.
1 parent 85e293c commit 35392f4

File tree

1 file changed

+116
-41
lines changed

1 file changed

+116
-41
lines changed

‎lib/csv.rb‎

Lines changed: 116 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -832,7 +832,7 @@ def filter(input=nil, output=nil, **options)
832832
# Returns an integer, or, if there were no rows, +nil+.
833833
#
834834
# * Argument +path+, if given, must be the path to a file.
835-
# * Argument +io+, if given, must be an \IO object opened for reading.
835+
# :include: ../doc/argument_io.rdoc
836836
# * Argument +mode+, if given, must be a \File mode
837837
# See {Open Mode}[IO.html#method-c-new-label-Open+Mode].
838838
# * Arguments <tt>**options</tt> must be keyword options.
@@ -854,7 +854,6 @@ def filter(input=nil, output=nil, **options)
854854
# string = "foo,0\nbar,1\nbaz,2\n"
855855
# path = 't.csv'
856856
# File.write(path, string)
857-
# io = File.open(path)
858857
#
859858
# Read rows from a file at +path+:
860859
# CSV.foreach(path) {|row| p row } # => 21
@@ -864,18 +863,18 @@ def filter(input=nil, output=nil, **options)
864863
# ["baz", "2"]
865864
#
866865
# Read rows from an \IO object:
867-
# CSV.foreach(io) {|row| p row } # => 21
866+
# CSV.foreach(File.open(path)) {|row| p row } # => 21
868867
# Output:
869868
# ["foo", "0"]
870869
# ["bar", "1"]
871870
# ["baz", "2"]
872871
#
873872
# Returns a new \Enumerator if no block given:
874873
# CSV.foreach(path) # => #<Enumerator: CSV:foreach("t.csv", "r")>
875-
# CSV.foreach(io) # => #<Enumerator: CSV:foreach(#<File:t.csv>, "r")>
874+
# CSV.foreach(File.open(path)) # => #<Enumerator: CSV:foreach(#<File:t.csv>, "r")>
876875
#
877876
# Issues a warning if an encoding is unsupported:
878-
# CSV.foreach(io, encoding: 'foo:bar') {|row| } # => 21
877+
# CSV.foreach(File.open(path), encoding: 'foo:bar') {|row| } # => 21
879878
# Output:
880879
# warning: Unsupported encoding foo ignored
881880
# warning: Unsupported encoding bar ignored
@@ -892,8 +891,8 @@ def filter(input=nil, output=nil, **options)
892891
# CSV.foreach(io) {|row| }
893892
#
894893
# Raises an exception if +mode+ is invalid:
895-
# # Raises IOError (not opened for reading):
896-
# CSV.foreach(path, 'w') {|row| }
894+
# # Raises ArgumentError (invalid access mode nosuch):
895+
# CSV.foreach(path, 'nosuch') {|row| }
897896
#
898897
def foreach(path, mode="r", **options, &block)
899898
return to_enum(__method__, path, mode, **options) unless block_given?
@@ -1022,10 +1021,10 @@ def generate_line(row, **options)
10221021

10231022
#
10241023
# :call-seq:
1025-
# open( filename, mode = "rb", **options ) { |faster_csv| ... }
1026-
# open( filename, **options ) { |faster_csv| ... }
1027-
# open( filename, mode = "rb", **options )
1028-
# open( filename, **options )
1024+
# open(file_path, mode = "rb", **options ) -> new_csv
1025+
# open(io, mode = "rb", **options ) -> new_csv
1026+
# open(file_path, mode = "rb", **options ) { |csv| ... } -> new_csv
1027+
# open(io, mode = "rb", **options ) { |csv| ... } -> new_csv
10291028
#
10301029
# possible options elements:
10311030
# hash form:
@@ -1034,28 +1033,63 @@ def generate_line(row, **options)
10341033
# :undef => :replace # replace undefined conversion
10351034
# :replace => string # replacement string ("?" or "\uFFFD" if not specified)
10361035
#
1037-
# This method opens an IO object, and wraps that with CSV. This is intended
1038-
# as the primary interface for writing a CSV file.
1036+
# * Argument +path+, if given, must be the path to a file.
1037+
# :include: ../doc/argument_io.rdoc
1038+
# * Argument +mode+, if given, must be a \File mode
1039+
# See {Open Mode}[IO.html#method-c-new-label-Open+Mode].
1040+
# * Arguments <tt>**options</tt> must be keyword options.
1041+
# See {Options for Generating}[#class-CSV-label-Options+for+Generating].
1042+
# * This method optionally accepts an additional <tt>:encoding</tt> option
1043+
# that you can use to specify the Encoding of the data read from +path+ or +io+.
1044+
# You must provide this unless your data is in the encoding
1045+
# given by <tt>Encoding::default_external</tt>.
1046+
# Parsing will use this to determine how to parse the data.
1047+
# You may provide a second Encoding to
1048+
# have the data transcoded as it is read. For example,
1049+
# encoding: 'UTF-32BE:UTF-8'
1050+
# would read +UTF-32BE+ data from the file
1051+
# but transcode it to +UTF-8+ before parsing.
10391052
#
1040-
# You must pass a +filename+ and may optionally add a +mode+ for Ruby's
1041-
# open().
1053+
# ---
10421054
#
1043-
# See {Options for Parsing}[#class-CSV-label-Options+for+Parsing].
1055+
# These examples assume prior execution of:
1056+
# string = "foo,0\nbar,1\nbaz,2\n"
1057+
# path = 't.csv'
1058+
# File.write(path, string)
1059+
#
1060+
# ---
1061+
#
1062+
# With no block given, returns a new \CSV object.
1063+
#
1064+
# Create a \CSV object using a file path:
1065+
# csv = CSV.open(path)
1066+
# csv # => #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\r\n" quote_char:"\"">
10441067
#
1045-
# This method works like Ruby's open() call, in that it will pass a CSV object
1046-
# to a provided block and close it when the block terminates, or it will
1047-
# return the CSV object when no block is provided. (*Note*: This is different
1048-
# from the Ruby 1.8 CSV library which passed rows to the block. Use
1049-
# CSV::foreach() for that behavior.)
1068+
# Create a \CSV object using an open \File:
1069+
# csv = CSV.open(File.open(path))
1070+
# csv # => #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\r\n" quote_char:"\"">
1071+
#
1072+
# ---
1073+
#
1074+
# With a block given, calls the block with the created \CSV object:
1075+
#
1076+
# Using a file path:
1077+
# csv = CSV.open(path) {|csv| p csv}
1078+
# csv # => #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\r\n" quote_char:"\"">
1079+
# Output:
1080+
# #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\r\n" quote_char:"\"">
1081+
#
1082+
# Using an open \File:
1083+
# csv = CSV.open(File.open(path)) {|csv| p csv}
1084+
# csv # => #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\r\n" quote_char:"\"">
1085+
# Output:
1086+
# #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\r\n" quote_char:"\"">
10501087
#
1051-
# You must provide a +mode+ with an embedded Encoding designator unless your
1052-
# data is in Encoding::default_external(). CSV will check the Encoding of the
1053-
# underlying IO object (set by the +mode+ you pass) to determine how to parse
1054-
# the data. You may provide a second Encoding to have the data transcoded as
1055-
# it is read just as you can with a normal call to IO::open(). For example,
1056-
# <tt>"rb:UTF-32BE:UTF-8"</tt> would read UTF-32BE data from the file but
1057-
# transcode it to UTF-8 before CSV parses it.
1088+
# ---
10581089
#
1090+
# Raises an exception if the argument is not a \String object or \IO object:
1091+
# # Raises TypeError (no implicit conversion of Symbol into String)
1092+
# CSV.open(:foo)
10591093
def open(filename, mode="r", **options)
10601094
# wrap a File opened with the remaining +args+ with no newline
10611095
# decorator
@@ -1093,16 +1127,60 @@ def open(filename, mode="r", **options)
10931127

10941128
#
10951129
# :call-seq:
1096-
# parse( str, **options ) { |row| ... }
1097-
# parse( str, **options )
1130+
# parse(string) -> array_of_arrays
1131+
# parse(io) -> array_of_arrays
1132+
# parse(string, **options) {|row| ... } -> integer
1133+
# parse(io, **options) {|row| ... } -> integer
10981134
#
1099-
# This method can be used to easily parse CSV out of a String. You may either
1100-
# provide a +block+ which will be called with each row of the String in turn,
1101-
# or just use the returned Array of Arrays (when no +block+ is given).
1135+
# Parses +string+ or +io+ using the specified +options+.
11021136
#
1103-
# You pass your +str+ to read from, and an optional +options+.
1104-
# See {Options for Parsing}[#class-CSV-label-Options+for+Parsing].
1137+
# - Argument +string+ should be a \String object;
1138+
# it will be put into a new StringIO object positioned at the beginning.
1139+
# :include: ../doc/argument_io.rdoc
1140+
# - Argument +options+: see {Options for Parsing}[#class-CSV-label-Options+for+Parsing]
1141+
#
1142+
# These examples assume prior execution of:
1143+
# string = "foo,0\nbar,1\nbaz,2\n"
1144+
# path = 't.csv'
1145+
# File.write(path, string)
1146+
#
1147+
# ---
1148+
#
1149+
# With no block given, returns an \Array of Arrays formed from the source.
1150+
#
1151+
# Parse a \String:
1152+
# a_of_a = CSV.parse(string)
1153+
# a_of_a # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
1154+
#
1155+
# Parse an open \File:
1156+
# a_of_a = CSV.parse(File.open(path))
1157+
# a_of_a # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
1158+
#
1159+
# ---
1160+
#
1161+
# With a block given, calls the block with each parsed row:
1162+
#
1163+
# Parse a \String:
1164+
# CSV.parse(string) {|row| p row } # => 18
1165+
#
1166+
# Output:
1167+
# ["foo", "0"]
1168+
# ["bar", "1"]
1169+
# ["baz", "2"]
1170+
#
1171+
# Parse an open \File:
1172+
# CSV.parse(File.open(path)) {|row| p row } # => 18
1173+
#
1174+
# Output:
1175+
# ["foo", "0"]
1176+
# ["bar", "1"]
1177+
# ["baz", "2"]
1178+
#
1179+
# ---
11051180
#
1181+
# Raises an exception if the argument is not a \String object or \IO object:
1182+
# # Raises NoMethodError (undefined method `close' for :foo:Symbol)
1183+
# CSV.parse(:foo)
11061184
def parse(str, **options, &block)
11071185
csv = new(str, **options)
11081186

@@ -1127,11 +1205,10 @@ def parse(str, **options, &block)
11271205
#
11281206
# - Argument +string+ should be a \String object;
11291207
# it will be put into a new StringIO object positioned at the beginning.
1130-
# - Argument +io+ should be an IO object, positioned at the beginning.
1208+
# :include: ../doc/argument_io.rdoc
11311209
# To position at the end, for appending, use method CSV.generate.
11321210
# For any other positioning, pass a preset \StringIO object instead.
1133-
# - Argument +options+: see {Options for Generating}[#class-CSV-label-Options+for+Generating]
1134-
# For +options+, see {Options for Parsing}[#class-CSV-label-Options+for+Parsing].
1211+
# - Argument +options+: see {Options for Parsing}[#class-CSV-label-Options+for+Parsing]
11351212
#
11361213
# ---
11371214
# Returns data from the first line from a String object:
@@ -1210,9 +1287,7 @@ def table(path, **options)
12101287
#
12111288
# - Argument +string+ should be a \String object;
12121289
# it will be put into a new StringIO object positioned at the beginning.
1213-
# - Argument +io+ should be an IO object, positioned at the beginning.
1214-
# To position at the end, for appending, use method CSV.generate.
1215-
# For any other positioning, pass a preset StringIO object instead.
1290+
# :include: ../doc/argument_io.rdoc
12161291
# - Argument +options+: See:
12171292
# * {Options for Parsing}[#class-CSV-label-Options+for+Parsing]
12181293
# * {Options for Generating}[#class-CSV-label-Options+for+Generating]

0 commit comments

Comments
 (0)