From 544d82f49b4b1486ae2791a35b6e5cce3e1abed1 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Thu, 2 Jul 2020 21:06:26 -0500 Subject: [PATCH] [ruby/csv] RDoc: summary lists for options (#154) * RDoc: summary lists for options * Enhanced RDoc for certain attributes and instance methods * Enhanced RDoc for certain attributes and instance methods * Enhanced RDoc for certain attributes and instance methods * Enhanced RDoc for certain attributes and instance methods https://github.com/ruby/csv/commit/72d8a25dc9 --- .../options/generating/write_nil_value.rdoc | 2 +- lib/csv.rb | 194 +++++++++++------- 2 files changed, 125 insertions(+), 71 deletions(-) diff --git a/doc/csv/options/generating/write_nil_value.rdoc b/doc/csv/options/generating/write_nil_value.rdoc index 8560f644b3..65d33ff54e 100644 --- a/doc/csv/options/generating/write_nil_value.rdoc +++ b/doc/csv/options/generating/write_nil_value.rdoc @@ -1,6 +1,6 @@ ====== Option +write_nil_value+ -Specifies the object that is to be substituted for each +nil+ field. +Specifies the object that is to be substituted for each +nil+-valued field. Default value: CSV::DEFAULT_OPTIONS.fetch(:write_nil_value) # => nil diff --git a/lib/csv.rb b/lib/csv.rb index 6830fd001f..20fd25c94f 100644 --- a/lib/csv.rb +++ b/lib/csv.rb @@ -337,10 +337,30 @@ using CSV::MatchP if CSV.const_defined?(:MatchP) # # ==== Options for Parsing # -# :include: ../doc/options/common/col_sep.rdoc +# Options for parsing, described in detail below, include: +# - +row_sep+: Specifies the row separator; used to delimit rows. +# - +col_sep+: Specifies the column separator; used to delimit fields. +# - +quote_char+: Specifies the quote character; used to quote fields. +# - +field_size_limit+: Specifies the maximum field size allowed. +# - +converters+: Specifies the field converters to be used. +# - +unconverted_fields+: Specifies whether unconverted fields are to be available. +# - +headers+: Specifies whether data contains headers, +# or specifies the headers themselves. +# - +return_headers+: Specifies whether headers are to be returned. +# - +header_converters+: Specifies the header converters to be used. +# - +skip_blanks+: Specifies whether blanks lines are to be ignored. +# - +skip_lines+: Specifies how comments lines are to be recognized. +# - +strip+: Specifies whether leading and trailing whitespace are +# to be stripped from fields.. +# - +liberal_parsing+: Specifies whether \CSV should attempt to parse +# non-compliant data. +# - +nil_value+: Specifies the object that is to be substituted for each null (no-text) field. +# - +empty_value+: Specifies the object that is to be substituted for each empty field. # # :include: ../doc/options/common/row_sep.rdoc # +# :include: ../doc/options/common/col_sep.rdoc +# # :include: ../doc/options/common/quote_char.rdoc # # :include: ../doc/options/parsing/field_size_limit.rdoc @@ -369,10 +389,21 @@ using CSV::MatchP if CSV.const_defined?(:MatchP) # # ==== Options for Generating # -# :include: ../doc/options/common/col_sep.rdoc +# Options for generating, described in detail below, include: +# - +row_sep+: Specifies the row separator; used to delimit rows. +# - +col_sep+: Specifies the column separator; used to delimit fields. +# - +quote_char+: Specifies the quote character; used to quote fields. +# - +write_headers+: Specifies whether headers are to be written. +# - +force_quotes+: Specifies whether each output field is to be quoted. +# - +quote_empty+: Specifies whether each empty output field is to be quoted. +# - +write_converters+: Specifies the field converters to be used in writing. +# - +write_nil_value+: Specifies the object that is to be substituted for each +nil+-valued field. +# - +write_empty_value+: Specifies the object that is to be substituted for each empty field. # # :include: ../doc/options/common/row_sep.rdoc # +# :include: ../doc/options/common/col_sep.rdoc +# # :include: ../doc/options/common/quote_char.rdoc # # :include: ../doc/options/generating/write_headers.rdoc @@ -1211,11 +1242,11 @@ class CSV # # Create a \CSV object using a file path: # csv = CSV.open(path) - # csv # => # + # csv # => # # # Create a \CSV object using an open \File: # csv = CSV.open(File.open(path)) - # csv # => # + # csv # => # # # --- # @@ -1224,15 +1255,15 @@ class CSV # # Using a file path: # csv = CSV.open(path) {|csv| p csv} - # csv # => # + # csv # => # # Output: - # # + # # # # Using an open \File: # csv = CSV.open(File.open(path)) {|csv| p csv} - # csv # => # + # csv # => # # Output: - # # + # # # # --- # @@ -1642,51 +1673,44 @@ class CSV writer if @writer_options[:write_headers] end - # - # The encoded :col_sep used in parsing and writing. - # See CSV::new for details. - # + # Returns the encoded column separator; used for parsing and writing; + # see {Option +col_sep+}[#class-CSV-label-Option+col_sep]: + # CSV.new('').col_sep # => "," def col_sep parser.column_separator end - # - # The encoded :row_sep used in parsing and writing. - # See CSV::new for details. - # + # Returns the encoded row separator; used for parsing and writing; + # see {Option +row_sep+}[#class-CSV-label-Option+row_sep]: + # CSV.new('').row_sep # => "\n" def row_sep parser.row_separator end - # - # The encoded :quote_char used in parsing and writing. - # See CSV::new for details. - # + # Returns the encoded quote character; used for parsing and writing; + # see {Option +quote_char+}[#class-CSV-label-Option+quote_char]: + # CSV.new('').quote_char # => "\"" def quote_char parser.quote_character end - # - # The limit for field size, if any. - # See CSV::new for details. - # + # Returns the limit for field size; used for parsing; + # see {Option +field_size_limit+}[#class-CSV-label-Option+field_size_limit]: + # CSV.new('').field_size_limit # => nil def field_size_limit parser.field_size_limit end - # - # The regex marking a line as a comment. - # See CSV::new for details. - # + # Returns the \Regexp used to identify comment lines; used for parsing; + # see {Option +skip_lines+}[#class-CSV-label-Option+skip_lines]: + # CSV.new('').skip_lines # => nil def skip_lines parser.skip_lines end - # - # Returns the current list of converters in effect. See CSV::new for details. - # Built-in converters will be returned by name, while others will be returned - # as is. - # + # Returns an \Array containing field converters; used for parsing; + # see {Option +converters+}[#class-CSV-label-Option+converters]: + # CSV.new('').converters # => [] def converters parser_fields_converter.map do |converter| name = Converters.rassoc(converter) @@ -1694,19 +1718,17 @@ class CSV end end - # - # Returns +true+ if unconverted_fields() to parsed results. - # See CSV::new for details. - # + # Returns the value that determines whether unconverted fields are to be + # available; used for parsing; + # see {Option +unconverted_fields+}[#class-CSV-label-Option+unconverted_fields]: + # CSV.new('').unconverted_fields? # => nil def unconverted_fields? parser.unconverted_fields? end - # - # Returns +nil+ if headers will not be used, +true+ if they will but have not - # yet been read, or the actual headers after they have been read. - # See CSV::new for details. - # + # Returns the value that determines whether headers are used; used for parsing; + # see {Option +headers+}[#class-CSV-label-Option+headers]: + # CSV.new('').headers # => nil def headers if @writer @writer.headers @@ -1718,27 +1740,24 @@ class CSV raw_headers end end - # - # Returns +true+ if headers will be returned as a row of results. - # See CSV::new for details. - # + + # Returns the value that determines whether headers are to be returned; used for parsing; + # see {Option +return_headers+}[#class-CSV-label-Option+return_headers]: + # CSV.new('').return_headers? # => false def return_headers? parser.return_headers? end - # - # Returns +true+ if headers are written in output. - # See CSV::new for details. - # + # Returns the value that determines whether headers are to be written; used for generating; + # see {Option +write_headers+}[#class-CSV-label-Option+write_headers]: + # CSV.new('').write_headers? # => nil def write_headers? @writer_options[:write_headers] end - # - # Returns the current list of converters in effect for headers. See CSV::new - # for details. Built-in converters will be returned by name, while others - # will be returned as is. - # + # Returns an \Array containing header converters; used for parsing; + # see {Option +header_converters+}[#class-CSV-label-Option+header_converters]: + # CSV.new('').header_converters # => [] def header_converters header_fields_converter.map do |converter| name = HeaderConverters.rassoc(converter) @@ -1746,34 +1765,59 @@ class CSV end end - # - # Returns +true+ blank lines are skipped by the parser. See CSV::new - # for details. - # + # Returns the value that determines whether blank lines are to be ignored; used for parsing; + # see {Option +skip_blanks+}[#class-CSV-label-Option+skip_blanks]: + # CSV.new('').skip_blanks? # => false def skip_blanks? parser.skip_blanks? end - # Returns +true+ if all output fields are quoted. See CSV::new for details. + # Returns the value that determines whether all output fields are to be quoted; + # used for generating; + # see {Option +force_quotes+}[#class-CSV-label-Option+force_quotes]: + # CSV.new('').force_quotes? # => false def force_quotes? @writer_options[:force_quotes] end - # Returns +true+ if illegal input is handled. See CSV::new for details. + # Returns the value that determines whether illegal input is to be handled; used for parsing; + # see {Option +liberal_parsing+}[#class-CSV-label-Option+liberal_parsing]: + # CSV.new('').liberal_parsing? # => false def liberal_parsing? parser.liberal_parsing? end - # - # The Encoding CSV is parsing or writing in. This will be the Encoding you - # receive parsed data in and/or the Encoding data will be written in. - # + # Returns the encoding used for parsing and generating; + # see {CSV and Character Encodings (M17n or Multilingualization)}[#class-CSV-label-CSV+and+Character+Encodings+-28M17n+or+Multilingualization-29]: + # CSV.new('').encoding # => # attr_reader :encoding + # Returns the count of the rows parsed or generated. # - # The line number of the last row read from this file. Fields with nested - # line-end characters will not affect this count. + # Parsing: + # string = "foo,0\nbar,1\nbaz,2\n" + # path = 't.csv' + # File.write(path, string) + # CSV.open(path) do |csv| + # csv.each do |row| + # p [csv.lineno, row] + # end + # end + # Output: + # [1, ["foo", "0"]] + # [2, ["bar", "1"]] + # [3, ["baz", "2"]] # + # Generating: + # CSV.generate do |csv| + # p csv.lineno; csv << ['foo', 0] + # p csv.lineno; csv << ['bar', 1] + # p csv.lineno; csv << ['baz', 2] + # end + # Output: + # 0 + # 1 + # 2 def lineno if @writer @writer.lineno @@ -1782,9 +1826,19 @@ class CSV end end - # - # The last row read from this file. - # + # Returns the line most recently read: + # string = "foo,0\nbar,1\nbaz,2\n" + # path = 't.csv' + # File.write(path, string) + # CSV.open(path) do |csv| + # csv.each do |row| + # p [csv.lineno, csv.line] + # end + # end + # Output: + # [1, "foo,0\n"] + # [2, "bar,1\n"] + # [3, "baz,2\n"] def line parser.line end