Skip to content

Commit 5ed9f76

Browse files
BurdetteLamarnobu
BurdetteLamar
authored and
nobu
committed
[ruby/csv] Enhanced Rdoc (ruby#124)
* Enhanced Rdoc for ::new * Rdoc for parse_line * More on parse_line * Make ::new neater with :call-seq: * Make better use of :call-seq: * Rdoc for generate_line * Respond to review ruby/csv@0d42df39cb
1 parent eef14e2 commit 5ed9f76

File tree

1 file changed

+100
-26
lines changed

1 file changed

+100
-26
lines changed

‎lib/csv.rb‎

Lines changed: 100 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@
109109
#
110110
# The most generic interface of the library is:
111111
#
112-
# csv = CSV.new(string_or_io, **options)
112+
# csv = CSV.new(io, **options)
113113
#
114114
# # Reading: IO object should be open for read
115115
# csv.read # => array of rows
@@ -809,19 +809,37 @@ def generate(str=nil, **options)
809809
csv.string # return final String
810810
end
811811

812+
# :call-seq:
813+
# CSV.generate_line(ary)
814+
# CSV.generate_line(ary, **options)
812815
#
813-
# This method is a shortcut for converting a single row (Array) into a CSV
814-
# String.
816+
# Returns the \String created by generating \CSV from +ary+
817+
# using the specified +options+.
815818
#
816-
# See {Options for Generating}[#class-CSV-label-Options+for+Generating].
819+
# Argument +ary+ must be an \Array.
820+
#
821+
# Special options:
822+
# * Option <tt>:row_sep</tt> defaults to <tt>$INPUT_RECORD_SEPARATOR</tt>
823+
# (<tt>$/</tt>).:
824+
# $INPUT_RECORD_SEPARATOR # => "\n"
825+
# * This method accepts an additional option, <tt>:encoding</tt>, which sets the base
826+
# Encoding for the output. This method will try to guess your Encoding from
827+
# the first non-+nil+ field in +row+, if possible, but you may need to use
828+
# this parameter as a backup plan.
829+
#
830+
# For other +options+,
831+
# see {Options for Generating}[#class-CSV-label-Options+for+Generating].
817832
#
818-
# This method accepts an additional option, <tt>:encoding</tt>, which sets the base
819-
# Encoding for the output. This method will try to guess your Encoding from
820-
# the first non-+nil+ field in +row+, if possible, but you may need to use
821-
# this parameter as a backup plan.
833+
# ---
822834
#
823-
# The <tt>:row_sep</tt> +option+ defaults to <tt>$INPUT_RECORD_SEPARATOR</tt>
824-
# (<tt>$/</tt>) when calling this method.
835+
# Returns the \String generated from an \Array:
836+
# CSV.generate_line(['foo', '0']) # => "foo,0\n"
837+
#
838+
# ---
839+
#
840+
# Raises an exception if +ary+ is not an \Array:
841+
# # Raises NoMethodError (undefined method `find' for :foo:Symbol)
842+
# CSV.generate_line(:foo)
825843
#
826844
def generate_line(row, **options)
827845
options = {row_sep: $INPUT_RECORD_SEPARATOR}.merge(options)
@@ -955,12 +973,41 @@ def parse(str, **options, &block)
955973
end
956974
end
957975

976+
# :call-seq:
977+
# CSV.parse_line(string)
978+
# CSV.parse_line(io)
979+
# CSV.parse_line(string, **options)
980+
# CSV.parse_line(io, **options)
958981
#
959-
# This method is a shortcut for converting a single line of a CSV String into
960-
# an Array. Note that if +line+ contains multiple rows, anything beyond the
961-
# first row is ignored.
982+
# Returns the new \Array created by parsing the first line of +string+ or +io+
983+
# using the specified +options+.
962984
#
963-
# See {Options for Parsing}[#class-CSV-label-Options+for+Parsing].
985+
# Argument +string+ should be a \String object;
986+
# it will be put into a new \StringIO object positioned at the beginning.
987+
#
988+
# Argument +io+ should be an \IO object; it will be positioned at the beginning.
989+
#
990+
# For +options+, see {Options for Parsing}[#class-CSV-label-Options+for+Parsing].
991+
#
992+
# ---
993+
# Returns data from the first line from a String object:
994+
# CSV.parse_line('foo,0') # => ["foo", "0"]
995+
#
996+
# Returns data from the first line from a File object:
997+
# File.write('t.csv', 'foo,0')
998+
# CSV.parse_line(File.open('t.csv')) # => ["foo", "0"]
999+
#
1000+
# Ignores lines after the first:
1001+
# CSV.parse_line("foo,0\nbar,1\nbaz,2") # => ["foo", "0"]
1002+
#
1003+
# Returns +nil+ if the argument is an empty \String:
1004+
# CSV.parse_line('') # => nil
1005+
#
1006+
# ---
1007+
#
1008+
# Raises an exception if the argument is +nil+:
1009+
# # Raises ArgumentError (Cannot parse nil as CSV):
1010+
# CSV.parse_line(nil)
9641011
#
9651012
def parse_line(line, **options)
9661013
new(line, **options).each.first
@@ -1008,22 +1055,49 @@ def table(path, **options)
10081055
end
10091056
end
10101057

1058+
# :call-seq:
1059+
# CSV.new(string)
1060+
# CSV.new(io)
1061+
# CSV.new(string, **options)
1062+
# CSV.new(io, **options)
1063+
#
1064+
# Returns the new \CSV object created using +string+ or +io+
1065+
# and the specified +options+.
1066+
#
1067+
# Argument +string+ should be a \String object;
1068+
# it will be put into a new \StringIO object positioned at the beginning.
1069+
#
1070+
# Argument +io+ should be an \IO object; it will be positioned at the beginning.
1071+
#
1072+
# To position at the end, for appending, use method CSV.generate.
1073+
# For any other positioning, pass a preset StringIO object instead.
1074+
#
1075+
# In addition to the \CSV instance methods, several \IO
1076+
# methods are delegated. See CSV::open for a complete list.
1077+
#
1078+
# For +options+, see:
1079+
# * {Options for Parsing}[#class-CSV-label-Options+for+Parsing]
1080+
# * {Options for Generating}[#class-CSV-label-Options+for+Generating]
1081+
#
1082+
# For performance reasons, the options cannot be overridden
1083+
# in a \CSV object, so the options specified here will endure.
1084+
#
1085+
# ---
10111086
#
1012-
# This constructor will wrap either a String or IO object passed in +data+ for
1013-
# reading and/or writing. In addition to the CSV instance methods, several IO
1014-
# methods are delegated. (See CSV::open() for a complete list.) If you pass
1015-
# a String for +data+, you can later retrieve it (after writing to it, for
1016-
# example) with CSV.string().
1087+
# Create a \CSV object from a \String object:
1088+
# csv = CSV.new('foo,0')
1089+
# csv # => #<CSV io_type:StringIO encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\n" quote_char:"\"">
10171090
#
1018-
# Note that a wrapped String will be positioned at the beginning (for
1019-
# reading). If you want it at the end (for writing), use CSV::generate().
1020-
# If you want any other positioning, pass a preset StringIO object instead.
1091+
# Create a \CSV object from a \File object:
1092+
# File.write('t.csv', 'foo,0')
1093+
# csv = CSV.new(File.open('t.csv'))
1094+
# csv # => #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\n" quote_char:"\"">
10211095
#
1022-
# See {Options for Parsing}[#class-CSV-label-Options+for+Parsing]
1023-
# and {Options for Generating}[#class-CSV-label-Options+for+Generating].
1096+
# ---
10241097
#
1025-
# Options cannot be overridden in the instance methods for performance reasons,
1026-
# so be sure to set what you want here.
1098+
# Raises an exception if the argument is +nil+:
1099+
# # Raises ArgumentError (Cannot parse nil as CSV):
1100+
# CSV.new(nil)
10271101
#
10281102
def initialize(data,
10291103
col_sep: ",",

0 commit comments

Comments
 (0)